API pour Registration Form

Cette page présente l’API publique de gestion des Registration Forms, les formulaires d’inscription que soumettent vos clients grossistes. Les 4 opérations partagent la même URL de base, les mêmes en-têtes et la même authentification, décrits dans API publiques.

Note

La disposition des champs (elements) d’un Registration Form peut devenir complexe. Avant de construire une requête de zéro, nous vous recommandons d’utiliser GET sur un formulaire existant créé dans l’application pour voir un exemple réel de la structure attendue, puis de n’ajuster que ce dont vous avez besoin.

Créer un Registration Form

Point de terminaison

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

En-têtes de la requête

En-tête	Description	Obligatoire
X-SAMITA-API-KEY	Clé d’API fournie dans l’application Wholesale	Oui
X-SAMITA-SHOP-URL	Domaine de la boutique Shopify au format xxx.myshopify.com	Oui
CONTENT-TYPE	Doit être application/json	Oui

Cette API nécessite l’autorisation Create sur la clé d’API.

Corps de la requête

Champs de premier niveau :

Champ	Type	Obligatoire	Description
title	chaîne	Recommandé	Le nom du formulaire dans l’application.
status	booléen	Recommandé	Indique si le formulaire est actif.
shopify_integration	objet	Oui	Contrôle la façon dont les soumissions sont reliées aux clients Shopify (voir ci-dessous).
elements	tableau	Oui	Les champs du formulaire, dans l’ordre d’affichage (voir ci-dessous).
header	objet	Non	Texte d’en-tête affiché en haut du formulaire.
footer	objet	Non	Boutons et texte de pied de page affichés en bas du formulaire.
general	objet	Non	Comportement d’approbation et tags clients par défaut.
errorMessage	objet	Non	Texte personnalisé des erreurs de validation.
reCaptcha	objet	Non	Indique si reCAPTCHA est exigé sur ce formulaire.
afterSubmit	objet	Non	Ce qui se passe après la soumission par un client.

shopify_integration

Champ	Type	Remarques
ifExist	chaîne (obligatoire)	returnError, continueAndUpdate ou continueAndIgnoreError : ce qui se passe si l’adresse e-mail soumise correspond déjà à un compte client.
showMessage	booléen	Affiche un message invitant le client à se connecter à la place.
messageRedirectToLogin	chaîne	Texte de ce message.
sendEmailInvite	booléen	Envoie l’e-mail d’activation de compte de Shopify.
acceptsMarketing	booléen	Inscrit le nouveau client aux e-mails marketing.

elements (tableau d'objets de champ)

Chaque élément nécessite un type. Les types courants incluent text, email, phone, password, number, name, url, checkbox, radio, country, datetime, file, hidden, heading, paragraph, devider et html.

Champ	Type	S’applique à	Remarques
type	chaîne (obligatoire)	tous	Type d’élément.
columnWidth	nombre (obligatoire sauf pour devider)	tous	33.33, 50 ou 100.
label / placeholder / description	chaîne	types de saisie	Libellés du champ.
required	booléen (obligatoire pour heading, paragraph, devider, html)	ces types	Indique si le champ doit être rempli.
hasConfirm, labelConfirm, placeholderConfirm, descriptionConfirm	—	password	Ajoute un champ de confirmation du mot de passe.
options, defaultOptions, defaultOption, defaultSelected	—	checkbox, radio, country	Configuration de la liste de choix.
inlineOption	nombre (obligatoire)	checkbox, radio	20, 25, 33.33, 50 ou 100.
heading / text	chaîne	heading / paragraph	Contenu affiché.
html	chaîne	html	Bloc HTML brut.
allowed-multiple	booléen	file	Autorise le téléversement de plusieurs fichiers.
allowed-extension	tableau	file	Une ou plusieurs valeurs parmi : 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	chaîne	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	chaîne	tous	Associe ce champ à une propriété du client Shopify : email, phone, first_name, last_name, addresses.address1, addresses.address2, addresses.city, addresses.province, addresses.zip, addresses.company, addresses.country, password, tags[] ou note[].

header, footer, general, errorMessage, reCaptcha, afterSubmit

Section	Champ	Type	Remarques
header	active	booléen	Affiche ou masque l’en-tête.
header	title	chaîne, 255 caractères max.
header	description	chaîne
footer	description	chaîne
footer	previousText, nextText, submitText, resetButtonText	chaîne	Libellés des boutons.
footer	resetButton, submitFullWidth	booléen
footer	submitAlignment	chaîne	left, center ou right.
general	customerTaxExempt	booléen
general	customerProcess	chaîne	review-approving (approbation manuelle) ou approving (automatique).
general	customerTags	tableau	Tags appliqués aux clients approuvés.
errorMessage	required, invalidName, invalidEmail, invalidURL, invalidPhone, invalidNumber, invalidPassword, confirmPasswordNotMatch, customerAlreadyExists, fileSizeLimit, fileNotAllowed, requiredCaptcha, shopifyInvalidPhone, shopifyPhoneHasAlready, shopifyInvalidProvice, otherError	chaîne	Texte personnalisé pour chaque erreur de validation.
reCaptcha	enable	booléen
afterSubmit	action	chaîne	clearForm, redirectToPage ou hideForm.
afterSubmit	message, redirectUrl	chaîne

Réponse

200 – Success renvoie l’enregistrement créé. Consultez l’exemple sous Get a Registration Form ci-dessous pour la structure de la réponse.

Mettre à jour un Registration Form

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

Mêmes en-têtes que pour la création. N’envoyez que les champs à modifier : title, status et secret_configs (l’objet de configuration complet, avec la même structure que celle renvoyée par GET, sous la clé configs) sont tous facultatifs. Les champs non précisés conservent leur valeur actuelle. Cette API nécessite l’autorisation Update.

Obtenir un Registration Form

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

Mêmes en-têtes que pour la création, sans corps de requête. Cette API nécessite l’autorisation View.

Exemple de réponse 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 }
    ]
  }
}

Supprimer un Registration Form

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

Mêmes en-têtes que pour la création. Transmettez un paramètre ids, une liste d’identifiants de formulaires à supprimer séparés par des virgules (en paramètre de la chaîne de requête ou en champ du corps JSON), par exemple ids=1,2,3. Cette API nécessite l’autorisation Delete.

200 – Success :

{
  "success": true
}

Réponses d’erreur

Les 4 points de terminaison partagent les mêmes réponses d’erreur que le reste de l’API publique. Consultez API publiques pour 401 Unauthorized, 403 Forbidden et 429 Too Many Requests.