API dla Registration Form

Ta strona opisuje publiczny interfejs API do zarządzania formularzami Registration Form – formularzami rejestracyjnymi, które przesyłają Twoi klienci hurtowi. Wszystkie 4 operacje korzystają z tego samego bazowego adresu URL, nagłówków i uwierzytelniania opisanych w Public APIs.

Notatka

Układ pól formularza rejestracyjnego (elements) może być złożony. Zanim zaczniesz budować żądanie od zera, zalecamy użycie GET na istniejącym formularzu utworzonym w aplikacji, aby zobaczyć prawdziwy przykład oczekiwanej struktury, a następnie zmienić tylko to, czego potrzebujesz.

Tworzenie formularza Registration Form

Punkt końcowy

POST https://wholesale.samita.io/api/v1/registration-forms

Nagłówki żądania

Nagłówek	Opis	Wymagane
X-SAMITA-API-KEY	Klucz API dostępny w aplikacji Wholesale	Tak
X-SAMITA-SHOP-URL	Domena sklepu Shopify w formacie xxx.myshopify.com	Tak
CONTENT-TYPE	Musi mieć wartość application/json	Tak

Ten interfejs API wymaga uprawnienia Create dla klucza API.

Treść żądania

Pola najwyższego poziomu:

Pole	Typ	Wymagane	Opis
title	string	Zalecane	Nazwa formularza w aplikacji.
status	boolean	Zalecane	Czy formularz jest aktywny.
shopify_integration	object	Tak	Określa, jak przesłane formularze łączą się z klientami Shopify – zobacz poniżej.
elements	array	Tak	Pola formularza, w kolejności wyświetlania – zobacz poniżej.
header	object	Nie	Tekst nagłówka wyświetlany na górze formularza.
footer	object	Nie	Przyciski i tekst stopki wyświetlane na dole formularza.
general	object	Nie	Sposób zatwierdzania i domyślne tagi klientów.
errorMessage	object	Nie	Własny tekst błędów walidacji.
reCaptcha	object	Nie	Czy na tym formularzu wymagana jest reCAPTCHA.
afterSubmit	object	Nie	Co dzieje się po przesłaniu formularza przez klienta.

shopify_integration

Pole	Typ	Uwagi
ifExist	string (wymagane)	returnError, continueAndUpdate lub continueAndIgnoreError – co się dzieje, gdy przesłany adres e-mail ma już konto klienta.
showMessage	boolean	Wyświetla komunikat kierujący klienta do zalogowania się.
messageRedirectToLogin	string	Tekst tego komunikatu.
sendEmailInvite	boolean	Wysyła e-mail aktywacyjny konta Shopify.
acceptsMarketing	boolean	Zapisuje nowego klienta na e-maile marketingowe.

elements (array of field objects)

Każdy element wymaga type – typowe typy to text, email, phone, password, number, name, url, checkbox, radio, country, datetime, file, hidden, heading, paragraph, devider i html.

Pole	Typ	Dotyczy	Uwagi
type	string (wymagane)	wszystkie	Typ elementu.
columnWidth	number (wymagane poza devider)	wszystkie	33.33, 50 lub 100.
label / placeholder / description	string	typy pól wejściowych	Opisy pola.
required	boolean (wymagane dla heading, paragraph, devider, html)	te typy	Czy pole musi być wypełnione.
hasConfirm, labelConfirm, placeholderConfirm, descriptionConfirm	—	password	Dodaje pole potwierdzenia hasła.
options, defaultOptions, defaultOption, defaultSelected	—	checkbox, radio, country	Konfiguracja listy wyborów.
inlineOption	number (wymagane)	checkbox, radio	20, 25, 33.33, 50 lub 100.
heading / text	string	heading / paragraph	Wyświetlana treść.
html	string	html	Blok surowego kodu HTML.
allowed-multiple	boolean	file	Zezwala na przesyłanie wielu plików.
allowed-extension	array	file	Dowolne z: csv, pdf, jpg, jpeg, gif, svg, png, psd, ai, stl, stp, step, doc, docx, txt, ex2, dxf, gbr, eps, mov, mp4, xls, xlsx, ods, numbers, xlsm, zip, heic, heif.
format, date-format, time-format	string	datetime	format: date/time/date-and-time. date-format: Y-m-d/d-m-Y/m-d-Y/d-m/m-d. time-format: 12h/24h.
integration	string	dowolny	Mapuje to pole na właściwość klienta Shopify: email, phone, first_name, last_name, addresses.address1, addresses.address2, addresses.city, addresses.province, addresses.zip, addresses.company, addresses.country, password, tags[] lub note[].

header, footer, general, errorMessage, reCaptcha, afterSubmit

Sekcja	Pole	Typ	Uwagi
header	active	boolean	Pokazuje lub ukrywa nagłówek.
header	title	string, maks. 255
header	description	string
footer	description	string
footer	previousText, nextText, submitText, resetButtonText	string	Etykiety przycisków.
footer	resetButton, submitFullWidth	boolean
footer	submitAlignment	string	left, center lub right.
general	customerTaxExempt	boolean
general	customerProcess	string	review-approving (ręczne zatwierdzanie) lub approving (automatyczne).
general	customerTags	array	Tagi przypisywane zatwierdzonym klientom.
errorMessage	required, invalidName, invalidEmail, invalidURL, invalidPhone, invalidNumber, invalidPassword, confirmPasswordNotMatch, customerAlreadyExists, fileSizeLimit, fileNotAllowed, requiredCaptcha, shopifyInvalidPhone, shopifyPhoneHasAlready, shopifyInvalidProvice, otherError	string	Własny tekst dla każdego błędu walidacji.
reCaptcha	enable	boolean
afterSubmit	action	string	clearForm, redirectToPage lub hideForm.
afterSubmit	message, redirectUrl	string

Odpowiedź

200 – Sukces zwraca utworzony rekord. Strukturę odpowiedzi znajdziesz w przykładzie poniżej w sekcji Pobieranie formularza Registration Form.

Aktualizowanie formularza Registration Form

PUT https://wholesale.samita.io/api/v1/registration-forms/{id}

Te same nagłówki co przy tworzeniu. Wysyłaj tylko pola, które chcesz zmienić – title, status i secret_configs (pełny obiekt konfiguracji, w takiej samej strukturze, jaką zwraca GET, pod kluczem configs) są opcjonalne. Nieokreślone pola zachowują dotychczasową wartość. Ten interfejs API wymaga uprawnienia Update.

Pobieranie formularza Registration Form

GET https://wholesale.samita.io/api/v1/registration-forms/{id}

Te same nagłówki co przy tworzeniu, bez treści żądania. Ten interfejs API wymaga uprawnienia View.

Przykład odpowiedzi 200 – Sukces:

{
  "id": 1,
  "title": "Wholesale Registration",
  "status": true,
  "created_at": "2026-01-15T10:00:00",
  "updated_at": "2026-01-15T10:00:00",
  "configs": {
    "header": {
      "active": true,
      "title": "Apply for a wholesale account",
      "description": ""
    },
    "footer": {
      "previousText": "Back",
      "nextText": "Next",
      "submitText": "Submit",
      "resetButton": false,
      "resetButtonText": "Reset",
      "submitFullWidth": false,
      "submitAlignment": "left"
    },
    "general": {
      "customerTaxExempt": false,
      "customerProcess": "review-approving",
      "customerTags": ["wholesale"]
    },
    "reCaptcha": {
      "enable": false
    },
    "afterSubmit": {
      "action": "clearForm",
      "message": "Thanks! We'll review your application shortly.",
      "redirectUrl": ""
    },
    "integration": {
      "shopify": {
        "ifExist": "returnError",
        "showMessage": true,
        "sendEmailInvite": true,
        "acceptsMarketing": false,
        "integrationElements": {
          "email": "email",
          "first_name": "first_name",
          "last_name": "last_name"
        }
      }
    },
    "elements": [
      { "id": "first_name", "type": "name", "label": "First name", "required": true, "columnWidth": 50 },
      { "id": "last_name", "type": "name", "label": "Last name", "required": true, "columnWidth": 50 },
      { "id": "email", "type": "email", "label": "Email", "required": true, "columnWidth": 100 }
    ]
  }
}

Usuwanie formularza Registration Form

DELETE https://wholesale.samita.io/api/v1/registration-forms/{id}

Te same nagłówki co przy tworzeniu. Przekaż parametr ids – listę ID formularzy do usunięcia, rozdzieloną przecinkami (jako parametr ciągu zapytania lub pole treści JSON), np. ids=1,2,3. Ten interfejs API wymaga uprawnienia Delete.

200 – Sukces:

{
  "success": true
}

Odpowiedzi z błędem

Wszystkie 4 punkty końcowe mają te same odpowiedzi z błędem co pozostała część publicznego interfejsu API – zobacz Public APIs, aby poznać 401 Unauthorized, 403 Forbidden i 429 Too Many Requests.