APIs para o formulário de cadastro

Esta página descreve a API pública para gerenciar formulários de cadastro — os formulários de inscrição que seus clientes de atacado enviam. As 4 operações usam a mesma URL base, os mesmos cabeçalhos e a mesma autenticação descritos em APIs públicas.

Nota

O layout de campos de um formulário de cadastro (elements) pode ficar complexo. Antes de montar uma requisição do zero, recomendamos usar GET em um formulário que você criou no app para ver um exemplo real da estrutura esperada e, depois, ajustar apenas o que for necessário.

Criar um formulário de cadastro

Endpoint

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

Cabeçalhos da requisição

Cabeçalho	Descrição	Obrigatório
X-SAMITA-API-KEY	Chave de API fornecida no app Wholesale	Sim
X-SAMITA-SHOP-URL	Domínio da loja Shopify no formato xxx.myshopify.com	Sim
CONTENT-TYPE	Deve ser application/json	Sim

Esta API exige a permissão Create na chave de API.

Corpo da requisição

Campos de nível superior:

Campo	Tipo	Obrigatório	Descrição
title	string	Recomendado	O nome do formulário no app.
status	boolean	Recomendado	Indica se o formulário está ativo.
shopify_integration	object	Sim	Controla como os envios se conectam aos clientes da Shopify — veja abaixo.
elements	array	Sim	Os campos do formulário, em ordem de exibição — veja abaixo.
header	object	Não	Texto de cabeçalho exibido no topo do formulário.
footer	object	Não	Botões e texto de rodapé exibidos na parte inferior do formulário.
general	object	Não	Comportamento de aprovação e tags de cliente padrão.
errorMessage	object	Não	Texto personalizado de erro de validação.
reCaptcha	object	Não	Indica se o reCAPTCHA é obrigatório neste formulário.
afterSubmit	object	Não	O que acontece depois que um cliente envia o formulário.

shopify_integration

Campo	Tipo	Observações
ifExist	string (obrigatório)	returnError, continueAndUpdate ou continueAndIgnoreError — o que acontece se o e-mail enviado já tiver uma conta de cliente.
showMessage	boolean	Exibe uma mensagem orientando o cliente a fazer login.
messageRedirectToLogin	string	Texto dessa mensagem.
sendEmailInvite	boolean	Envia o e-mail de ativação de conta da Shopify.
acceptsMarketing	boolean	Inscreve o novo cliente nos e-mails de marketing.

elements (array de objetos de campo)

Todo elemento precisa de um type — os tipos mais comuns incluem text, email, phone, password, number, name, url, checkbox, radio, country, datetime, file, hidden, heading, paragraph, devider, and html.

Campo	Tipo	Aplica-se a	Observações
type	string (obrigatório)	todos	Tipo do elemento.
columnWidth	number (obrigatório, exceto devider)	todos	33.33, 50 ou 100.
label / placeholder / description	string	tipos de entrada	Rótulos do campo.
required	boolean (obrigatório para heading, paragraph, devider, html)	esses tipos	Indica se o campo deve ser preenchido.
hasConfirm, labelConfirm, placeholderConfirm, descriptionConfirm	—	password	Adiciona um campo de confirmação de senha.
options, defaultOptions, defaultOption, defaultSelected	—	checkbox, radio, country	Configuração da lista de opções.
inlineOption	number (obrigatório)	checkbox, radio	20, 25, 33.33, 50 ou 100.
heading / text	string	heading / paragraph	Conteúdo exibido.
html	string	html	Bloco de HTML bruto.
allowed-multiple	boolean	file	Permite o envio de vários arquivos.
allowed-extension	array	file	Qualquer um 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	qualquer	Associa este campo a uma propriedade de cliente da 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

Seção	Campo	Tipo	Observações
header	active	boolean	Mostra/oculta o cabeçalho.
header	title	string, máx. 255
header	description	string
footer	description	string
footer	previousText, nextText, submitText, resetButtonText	string	Rótulos dos botões.
footer	resetButton, submitFullWidth	boolean
footer	submitAlignment	string	left, center ou right.
general	customerTaxExempt	boolean
general	customerProcess	string	review-approving (aprovação manual) ou approving (automática).
general	customerTags	array	Tags aplicadas aos clientes aprovados.
errorMessage	required, invalidName, invalidEmail, invalidURL, invalidPhone, invalidNumber, invalidPassword, confirmPasswordNotMatch, customerAlreadyExists, fileSizeLimit, fileNotAllowed, requiredCaptcha, shopifyInvalidPhone, shopifyPhoneHasAlready, shopifyInvalidProvice, otherError	string	Texto personalizado para cada erro de validação.
reCaptcha	enable	boolean
afterSubmit	action	string	clearForm, redirectToPage ou hideForm.
afterSubmit	message, redirectUrl	string

Resposta

200 – Success retorna o registro criado. Veja o exemplo em Obter um formulário de cadastro, abaixo, para conhecer a estrutura da resposta.

Atualizar um formulário de cadastro

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

Mesmos cabeçalhos da criação. Envie apenas os campos que deseja alterar — title, status e secret_configs (o objeto de configuração completo, no mesmo formato retornado pelo GET, sob a chave configs) são todos opcionais. Os campos não informados mantêm o valor atual. Esta API exige a permissão Update.

Obter um formulário de cadastro

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

Mesmos cabeçalhos da criação, sem corpo na requisição. Esta API exige a permissão View.

Exemplo 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 }
    ]
  }
}

Excluir um formulário de cadastro

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

Mesmos cabeçalhos da criação. Informe um parâmetro ids — uma lista de IDs de formulários a excluir separados por vírgula (como parâmetro de query string ou campo do corpo JSON), por exemplo ids=1,2,3. Esta API exige a permissão Delete.

200 – Success:

{
  "success": true
}

Respostas de erro

Os 4 endpoints compartilham as mesmas respostas de erro do restante da API pública — veja APIs públicas para 401 Unauthorized, 403 Forbidden e 429 Too Many Requests.