Formulários

Formulários permitem solicitar dados estruturados durante uma operação ou como uma ordem independente.

Para coletar dados junto de uma cobrança, envie o formulário no campo form de Criar pagamento em vez de usar esta rota.

Headers

Nome	Descrição	Valor
`Authorization`	Token JWT da loja.	`Bearer {token}`
`ocp-apim-subscription-key`	Gateway Token recebido na criação da loja.	`{subscription-key}`
`Content-Type`	Formato do corpo da requisição.	`application/json`

Mais detalhes sobre os tokens em Autenticação.

Criar formulário

POST https://api.smarttef.mobi/commands/form/create

{
  "order_type": "NRM",
  "form_name": "cadastro-cliente",
  "extras": {
    "CNPJ": "12612554000131"
  },
  "form": [
    {
      "field": "Email",
      "type": "EMAIL",
      "needed": true
    },
    {
      "field": "Observação",
      "type": "TEXTO"
    }
  ]
}

Campo	Obrigatório	Descrição
`cnpj`	Não	CNPJ da loja, somente dígitos. Quando omitido, a API usa o CNPJ do token. Quando enviado, precisa ser igual ao CNPJ do token.
`order_type`	Não	`NRM` deixa o card na lista geral e `CRD_UNICO` abre direto no destino.
`serial_pos`	Condicional	Serial do POS que receberá o formulário quando `order_type` for `CRD_UNICO`. Não pode ser enviado junto com `user_id`.
`user_id`	Condicional	Operador que receberá o formulário quando `order_type` for `CRD_UNICO`. Não pode ser enviado junto com `serial_pos`.
`form_name`	Não	Nome de referência do formulário.
`fill_out_type`	Não	`REQUEST_COMUM_FORM` ou `REQUEST_MANDATORY_FORM`.
`extras`	Não	Dados complementares enviados pelo ERP.
`has_details`	Não	Permite abrir a tela de detalhes do card.
`form[].field`	Sim	Nome do campo exibido ao operador.
`form[].value`	Não	Valor inicial do campo. O POS devolve o valor preenchido.
`form[].type`	Não	`TEXTO`, `NUMBER`, `DATA`, `CPF`, `CNPJ`, `CEP` ou `EMAIL`. Padrão `TEXTO`.
`form[].needed`	Não	Torna o preenchimento do campo obrigatório. Padrão `false`.

Regras de formulário

Tema	Regra
Direcionamento	Para `CRD_UNICO`, envie exatamente um entre `user_id` e `serial_pos`. Os dois nunca podem ser enviados juntos.
Obrigatoriedade	Basta um campo com `needed: true` para a API definir `fill_out_type` como `REQUEST_MANDATORY_FORM`. Enviar `REQUEST_MANDATORY_FORM` sem nenhum campo obrigatório é recusado.
Duplicidade	`form_name` precisa ser único entre os formulários da loja que estejam em `PDT` ou `PROC`.
Conclusão	Campos obrigatórios devem retornar preenchidos como string não vazia.

Retorno da criação

{
  "form_identifier": "01970d18-aac3-7ff4-ba76-78e785409d09",
  "form_status": "PDT",
  "order_type": "NRM",
  "form_url": "https://storage.blob.com/smart-tef/cadastro-cliente",
  "form_name": "cadastro-cliente",
  "fill_out_type": "REQUEST_MANDATORY_FORM"
}

Campo	Descrição
`form_identifier`	Identificador único do formulário, gerado pela API.
`form_status`	Status atual do card.
`order_type`	Tipo do card, único ou normal.
`form_url`	URL do JSON do formulário armazenado.
`form_name`	Nome de referência informado na criação.
`fill_out_type`	`REQUEST_COMUM_FORM` ou `REQUEST_MANDATORY_FORM`.

Veja o contrato completo em Criar formulário.

Consultar formulário

POST https://api.smarttef.mobi/pooling/form/get

{
  "form_identifier": "01970d18-aac3-7ff4-ba76-78e785409d09"
}

Campo	Tipo	Obrigatório	Descrição
`form_identifier`	`string`	Sim	Identificador do formulário devolvido na criação.

A resposta é um objeto único, não uma lista. Se o formulário não existir na loja, a API responde 404.
As respostas preenchidas pelo operador ficam no JSON apontado por form_url. O corpo devolve o estado do card.
A consulta funciona tanto para formulários independentes quanto para formulários vinculados a um pagamento.

Exemplo de retorno de consulta

{
  "form_identifier": "01970d18-aac3-7ff4-ba76-78e785409d09",
  "cnpj": "22140418000160",
  "create_at": "2026-02-25T15:38:04.603Z",
  "update_at": "2026-02-25T15:41:12.117Z",
  "order_type": "NRM",
  "form_status": "CNC",
  "serial_pos": "",
  "user_id": 24,
  "type": "FORM",
  "controle_versao": "2.14.0",
  "conn_type": "WIFI",
  "batt_level": "87",
  "charging": false,
  "location": {
    "lat": "",
    "long": ""
  },
  "reason": null,
  "form_name": "cadastro-cliente",
  "order_target": "USR",
  "package_name": "br.com.poscontrole.smarttef",
  "store_id": 1,
  "form_url": "https://storage.blob.com/smart-tef/cadastro-cliente",
  "fill_out_type": "REQUEST_MANDATORY_FORM",
  "agregate": "NONE",
  "order_target_initial": "USR",
  "serial_pos_initial": "",
  "user_id_initial": 24,
  "extras": {
    "CNPJ": "12612554000131"
  },
  "has_details": false
}

Campos de retorno

Campo	Descrição
`form_identifier`	Identificador único do formulário.
`cnpj`	CNPJ da loja.
`create_at`	Data de criação, no fuso de São Paulo.
`update_at`	Data da última atualização, no fuso de São Paulo.
`order_type`	`CRD_UNICO` ou `NRM`.
`form_status`	Status atual do card.
`serial_pos`	Serial do POS de destino.
`user_id`	Operador de destino.
`type`	Tipo do card. Para formulário, será `FORM`.
`controle_versao`	Versão do app Smart TEF instalada no terminal que atendeu o card.
`conn_type`	Tipo de conexão do terminal no momento da atualização.
`batt_level`	Percentual de bateria do terminal.
`charging`	Indica se o terminal estava no carregador.
`location.lat`	Latitude do terminal.
`location.long`	Longitude do terminal.
`reason`	Motivo da rejeição informado pelo POS, quando houver.
`form_name`	Nome de referência do formulário.
`order_target`	Destino atual do card: `USR`, `POS` ou `NONE`.
`package_name`	Pacote do app que processou o formulário.
`store_id`	Identificador interno da loja.
`form_url`	URL do JSON com os campos e as respostas do formulário.
`fill_out_type`	`REQUEST_COMUM_FORM` ou `REQUEST_MANDATORY_FORM`.
`agregate`	Vínculo do formulário: `NONE` (independente), `PAYMENT` ou `PRINT`.
`order_target_initial`	Destino original do card: `USR`, `POS` ou `NONE`.
`serial_pos_initial`	Destino original em POS.
`user_id_initial`	Destino original em operador.
`extras`	Campos extras enviados pelo ERP.
`has_details`	Indica se a tela de detalhes pode ser aberta.

Veja o contrato completo em Consultar formulário.

Cancelar formulário pendente

POST https://api.smarttef.mobi/commands/form/status/cancelar

{
  "form_identifier": "01970d18-aac3-7ff4-ba76-78e785409d09"
}

O cancelamento só se aplica a formulários ainda pendentes. Depois que o preenchimento estiver em processamento, acompanhe o resultado pela consulta.

Retorno do cancelamento

{
  "form_identifier": "01970d18-aac3-7ff4-ba76-78e785409d09",
  "form_status": "CAN_ERP",
  "order_type": "NRM"
}

Campo	Descrição
`form_identifier`	Identificador único do formulário.
`form_status`	Status atual do card.
`order_type`	Tipo do card, único ou normal.

Veja o contrato completo em Cancelar formulário pendente.

Formulários

On this page