APIs de Registration Form

Esta página describe la Public API para gestionar Registration Forms, los formularios de registro que envía tu clientela mayorista. Las 4 operaciones comparten la misma URL base, los mismos encabezados y la misma autenticación que se describen en Public APIs.

Nota

La disposición de los campos de un Registration Form (elements) puede ser compleja. Antes de crear una solicitud desde cero, te recomendamos usar GET sobre un formulario existente que hayas creado en la aplicación para ver un ejemplo real de la estructura esperada y ajustar solo lo que necesites.

Crear un Registration Form

Endpoint

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

Encabezados de la solicitud

Encabezado	Descripción	Obligatorio
X-SAMITA-API-KEY	Clave de API proporcionada en la aplicación Wholesale	Sí
X-SAMITA-SHOP-URL	Dominio de la tienda de Shopify con el formato xxx.myshopify.com	Sí
CONTENT-TYPE	Debe ser application/json	Sí

Esta API requiere el permiso Create en la clave de API.

Cuerpo de la solicitud

Campos de nivel superior:

Campo	Tipo	Obligatorio	Descripción
title	string	Recomendado	El nombre del formulario en la aplicación.
status	boolean	Recomendado	Si el formulario está activo.
shopify_integration	object	Sí	Controla cómo se conectan los envíos con los clientes de Shopify; consulta más abajo.
elements	array	Sí	Los campos del formulario, en el orden en que se muestran; consulta más abajo.
header	object	No	Texto de encabezado que se muestra en la parte superior del formulario.
footer	object	No	Botones y texto de pie que se muestran en la parte inferior del formulario.
general	object	No	Comportamiento de aprobación y etiquetas de cliente predeterminadas.
errorMessage	object	No	Texto personalizado de los errores de validación.
reCaptcha	object	No	Si se exige reCAPTCHA en este formulario.
afterSubmit	object	No	Qué ocurre después de que alguien envía el formulario.

shopify_integration

Campo	Tipo	Notas
ifExist	string (obligatorio)	returnError, continueAndUpdate o continueAndIgnoreError: qué ocurre si el correo enviado ya tiene una cuenta de cliente.
showMessage	boolean	Muestra un mensaje que indica a la persona que inicie sesión en su lugar.
messageRedirectToLogin	string	Texto de ese mensaje.
sendEmailInvite	boolean	Envía el correo de activación de cuenta de Shopify.
acceptsMarketing	boolean	Suscribe al nuevo cliente a los correos de marketing.

elements (array de objetos de campo)

Cada elemento necesita un type. Entre los tipos habituales están text, email, phone, password, number, name, url, checkbox, radio, country, datetime, file, hidden, heading, paragraph, devider y html.

Campo	Tipo	Se aplica a	Notas
type	string (obligatorio)	todos	Tipo de elemento.
columnWidth	number (obligatorio salvo devider)	todos	33.33, 50 o 100.
label / placeholder / description	string	tipos de entrada	Etiquetado del campo.
required	boolean (obligatorio para heading, paragraph, devider, html)	esos tipos	Si el campo debe rellenarse.
hasConfirm, labelConfirm, placeholderConfirm, descriptionConfirm	—	password	Agrega un campo de confirmación de contraseña.
options, defaultOptions, defaultOption, defaultSelected	—	checkbox, radio, country	Configuración de la lista de opciones.
inlineOption	number (obligatorio)	checkbox, radio	20, 25, 33.33, 50 o 100.
heading / text	string	heading / paragraph	Contenido que se muestra.
html	string	html	Bloque de HTML sin procesar.
allowed-multiple	boolean	file	Permite subir varios archivos.
allowed-extension	array	file	Cualquiera de: 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	cualquiera	Asigna este campo a una propiedad del cliente de Shopify: email, phone, first_name, last_name, addresses.address1, addresses.address2, addresses.city, addresses.province, addresses.zip, addresses.company, addresses.country, password, tags[] o note[].

header, footer, general, errorMessage, reCaptcha, afterSubmit

Sección	Campo	Tipo	Notas
header	active	boolean	Muestra u oculta el encabezado.
header	title	string, máx. 255
header	description	string
footer	description	string
footer	previousText, nextText, submitText, resetButtonText	string	Etiquetas de los botones.
footer	resetButton, submitFullWidth	boolean
footer	submitAlignment	string	left, center o right.
general	customerTaxExempt	boolean
general	customerProcess	string	review-approving (aprobación manual) o approving (automática).
general	customerTags	array	Etiquetas que se aplican a los clientes aprobados.
errorMessage	required, invalidName, invalidEmail, invalidURL, invalidPhone, invalidNumber, invalidPassword, confirmPasswordNotMatch, customerAlreadyExists, fileSizeLimit, fileNotAllowed, requiredCaptcha, shopifyInvalidPhone, shopifyPhoneHasAlready, shopifyInvalidProvice, otherError	string	Texto personalizado para cada error de validación.
reCaptcha	enable	boolean
afterSubmit	action	string	clearForm, redirectToPage o hideForm.
afterSubmit	message, redirectUrl	string

Respuesta

200 – Success devuelve el registro creado. Consulta el ejemplo en Obtener un Registration Form más abajo para ver la estructura de la respuesta.

Actualizar un Registration Form

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

Mismos encabezados que en Create. Envía solo los campos que quieras cambiar: title, status y secret_configs (el objeto de configuración completo, con la misma estructura que devuelve GET, bajo la clave configs) son opcionales. Los campos que no indiques conservan su valor actual. Esta API requiere el permiso Update.

Obtener un Registration Form

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

Mismos encabezados que en Create, sin cuerpo de solicitud. Esta API requiere el permiso View.

Ejemplo de 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 }
    ]
  }
}

Eliminar un Registration Form

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

Mismos encabezados que en Create. Pasa un parámetro ids, una lista separada por comas de los ID de los formularios que quieres eliminar (como parámetro de la cadena de consulta o como campo del cuerpo JSON), por ejemplo ids=1,2,3. Esta API requiere el permiso Delete.

200 – Success:

{
  "success": true
}

Respuestas de error

Los 4 endpoints comparten las mismas respuestas de error que el resto de la Public API; consulta Public APIs para 401 Unauthorized, 403 Forbidden y 429 Too Many Requests.