API per Registration Form

Questa pagina descrive la Public API per gestire i Registration Form, cioè i moduli di iscrizione che invia la clientela all’ingrosso. Tutte e 4 le operazioni condividono lo stesso URL di base, le stesse intestazioni e la stessa autenticazione descritte in API pubbliche.

Nota

La struttura dei campi di un Registration Form (elements) può diventare complessa. Prima di creare una richiesta da zero, ti consigliamo di usare GET su un modulo esistente creato nell’app per vedere un esempio reale della struttura prevista, poi modifica solo ciò che ti serve.

Crea un Registration Form

Endpoint

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

Intestazioni della richiesta

Header	Descrizione	Obbligatorio
X-SAMITA-API-KEY	Chiave API fornita nell’app Wholesale	Sì
X-SAMITA-SHOP-URL	Dominio del negozio Shopify nel formato xxx.myshopify.com	Sì
CONTENT-TYPE	Deve essere application/json	Sì

Questa API richiede l’autorizzazione Create sulla chiave API.

Corpo della richiesta

Campi di primo livello:

Campo	Tipo	Obbligatorio	Descrizione
title	stringa	Consigliato	Il nome del modulo nell’app.
status	booleano	Consigliato	Indica se il modulo è attivo.
shopify_integration	oggetto	Sì	Controlla come gli invii si collegano ai clienti Shopify (vedi sotto).
elements	array	Sì	I campi del modulo, in ordine di visualizzazione (vedi sotto).
header	oggetto	No	Testo dell’intestazione mostrato in cima al modulo.
footer	oggetto	No	Pulsanti e testo del piè di pagina mostrati in fondo al modulo.
general	oggetto	No	Comportamento di approvazione e tag cliente predefiniti.
errorMessage	oggetto	No	Testo personalizzato degli errori di convalida.
reCaptcha	oggetto	No	Indica se reCAPTCHA è richiesto in questo modulo.
afterSubmit	oggetto	No	Cosa succede dopo l’invio da parte di una persona.

shopify_integration

Campo	Tipo	Note
ifExist	stringa (obbligatorio)	returnError, continueAndUpdate o continueAndIgnoreError: cosa succede se l’email inviata ha già un account cliente.
showMessage	booleano	Mostra un messaggio che invita ad accedere.
messageRedirectToLogin	stringa	Testo di quel messaggio.
sendEmailInvite	booleano	Invia l’email di attivazione dell’account di Shopify.
acceptsMarketing	booleano	Iscrive la nuova persona alle email di marketing.

elements (array di oggetti campo)

Ogni elemento richiede un type; i tipi più comuni sono text, email, phone, password, number, name, url, checkbox, radio, country, datetime, file, hidden, heading, paragraph, devider, and html.

Campo	Tipo	Si applica a	Note
type	stringa (obbligatorio)	tutti	Tipo di elemento.
columnWidth	numero (obbligatorio tranne per devider)	tutti	33.33, 50 o 100.
label / placeholder / description	stringa	tipi di input	Etichette del campo.
required	booleano (obbligatorio per heading, paragraph, devider, html)	questi tipi	Indica se il campo deve essere compilato.
hasConfirm, labelConfirm, placeholderConfirm, descriptionConfirm	—	password	Aggiunge un campo di conferma della password.
options, defaultOptions, defaultOption, defaultSelected	—	checkbox, radio, country	Configurazione dell’elenco di scelte.
inlineOption	numero (obbligatorio)	checkbox, radio	20, 25, 33.33, 50 o 100.
heading / text	stringa	heading / paragraph	Contenuto visualizzato.
html	stringa	html	Blocco HTML grezzo.
allowed-multiple	booleano	file	Consente il caricamento di più file.
allowed-extension	array	file	Uno qualsiasi tra: 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	stringa	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	stringa	qualsiasi	Associa questo campo a una proprietà del cliente Shopify: email, phone, first_name, last_name, addresses.address1, addresses.address2, addresses.city, addresses.province, addresses.zip, addresses.company, addresses.country, password, tags[], or note[].

header, footer, general, errorMessage, reCaptcha, afterSubmit

Sezione	Campo	Tipo	Note
header	active	booleano	Mostra o nasconde l’intestazione.
header	title	stringa, max 255
header	description	stringa
footer	description	stringa
footer	previousText, nextText, submitText, resetButtonText	stringa	Etichette dei pulsanti.
footer	resetButton, submitFullWidth	booleano
footer	submitAlignment	stringa	left, center o right.
general	customerTaxExempt	booleano
general	customerProcess	stringa	review-approving (approvazione manuale) o approving (automatica).
general	customerTags	array	Tag applicati alle persone approvate.
errorMessage	required, invalidName, invalidEmail, invalidURL, invalidPhone, invalidNumber, invalidPassword, confirmPasswordNotMatch, customerAlreadyExists, fileSizeLimit, fileNotAllowed, requiredCaptcha, shopifyInvalidPhone, shopifyPhoneHasAlready, shopifyInvalidProvice, otherError	stringa	Testo personalizzato per ogni errore di convalida.
reCaptcha	enable	booleano
afterSubmit	action	stringa	clearForm, redirectToPage o hideForm.
afterSubmit	message, redirectUrl	stringa

Risposta

200 – Success restituisce il record creato. Consulta l’esempio in Recupera un Registration Form più sotto per la struttura della risposta.

Aggiorna un Registration Form

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

Stesse intestazioni di Crea. Invia solo i campi che vuoi modificare: title, status e secret_configs (l’oggetto di configurazione completo, nella stessa struttura restituita da GET, sotto la chiave configs) sono tutti facoltativi. I campi non specificati mantengono il valore attuale. Questa API richiede l’autorizzazione Update.

Recupera un Registration Form

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

Stesse intestazioni di Crea, nessun corpo della richiesta. Questa API richiede l’autorizzazione View.

Esempio di 200 – Success:

{
  "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 }
    ]
  }
}

Elimina un Registration Form

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

Stesse intestazioni di Crea. Passa un parametro ids, un elenco di ID dei moduli da eliminare separati da virgola (come parametro della query string o come campo del corpo JSON), ad esempio ids=1,2,3. Questa API richiede l’autorizzazione Delete.

200 – Success:

{
  "success": true
}

Risposte di errore

Tutti e 4 gli endpoint condividono le stesse risposte di errore del resto della Public API: consulta API pubbliche per 401 Unauthorized, 403 Forbidden e 429 Too Many Requests.