> ## Documentation Index
> Fetch the complete documentation index at: https://ajuda.pandazap.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API de Formulários: envie respostas e abra atendimentos

> Use a API do PanÐá Zap para enviar as respostas de um formulário da sua empresa: o contato é achado ou criado, o atendimento é aberto no canal do formulário e a confirmação sai quando estiver ligada.

Os formulários da tela **Formulários** também podem receber respostas pela API. Use esta rota quando o formulário é preenchido em outro sistema (seu site, um app, uma landing page própria) e você quer que o PanÐá Zap trate o envio exatamente como trataria o preenchimento da página do formulário.

Todas as requisições exigem o cabeçalho `Authorization: Bearer {BearerToken}`.

***

## Enviar respostas de um formulário

```http theme={null}
POST https://{BaseUrl}/v2/api/external/{ApiID}/formSubmit
```

```json theme={null}
{
  "formId": 12,
  "answers": {
    "f_nome": "Maria Souza",
    "f_telefone": "+5511999998888",
    "f_email": "maria@exemplo.com",
    "f_assunto": "o_financeiro"
  },
  "ref": "https://www.exemplo.com.br/contato"
}
```

| Campo | Tipo | Obrigatório | Descrição |
| - | - | - | - |
| `formId` | number | Sim, ou `slug` | Número do formulário. Se vierem `formId` e `slug` juntos, vale o `formId`. |
| `slug` | string | Sim, ou `formId` | Endereço do formulário: o que vem depois de `/f/` no link. |
| `answers` | object | Sim | Respostas: a chave é a **chave do campo** e o valor é a resposta. Campo oculto também vai pela chave dele. |
| `ref` | string | Não | Endereço da página de origem. Fica guardado só com a origem e o caminho. |

O número do formulário, o endereço e as chaves dos campos aparecem na aba **Compartilhar** do formulário.

### Formato das respostas

| Tipo do campo | Valor esperado |
| - | - |
| Lista (escolha única) | id da opção (o texto da opção também é aceito) |
| Múltipla escolha | lista com os ids das opções |
| Caixa de confirmação | `true` ou `false` |
| Data | `AAAA-MM-DD` |
| Telefone | com `+` e o código do país. Sem o `+`, vale o país da Região da empresa |

### O que acontece com o envio

* **Contato:** é procurado só pela identidade do canal do formulário (o telefone em canal de WhatsApp, o e-mail em canal de e-mail). Se for achado, só os dados que estão vazios nele são completados; se não for achado, o contato é criado.
* **Etiquetas:** as etiquetas do formulário são aplicadas.
* **Atendimento:** é aberto no canal e no destino do formulário, com a oportunidade quando o formulário cria uma. Se o contato já tem atendimento aberto nesse canal, as respostas entram nele, sem mudar a fila nem o responsável.
* **Confirmação:** é enviada ao contato quando o formulário tem a confirmação ligada.

> [!NOTE]
>
> Pela API não valem as travas da página do formulário: campo-armadilha, tempo mínimo de preenchimento, limite por endereço IP e teto diário. O envio também não depende da opção **Aceitar envios de outros sites**.

### Resposta

A resposta só chega depois do processamento e traz os campos `ok`, `submissionId`, `status`, `ticketId`, `contactId` e `errorCode`.

| `status` | Significado |
| - | - |
| `processed` | Atendimento aberto ou atualizado. |
| `failed` | O envio fica em **Respostas** sem atendimento. O `errorCode` diz o motivo (ex.: `ERR_FORM_NO_CHANNEL`) e dá para refazer pelo **Tentar de novo**. |
| `skipped` | Contato bloqueado (`ERR_FORM_CONTACT_BLOCKED`). |

### Erros

| Código | Quando acontece |
| - | - |
| `404` `ERR_API_CONFIG_NOT_FOUND` | O `ApiID` da URL não existe nesta empresa. |
| `404` `ERR_FORM_NOT_FOUND` | Formulário inexistente, desativado, de outra empresa ou sem canal ativo. |
| `400` `ERR_FORM_ID_OR_SLUG_REQUIRED` | Não veio `formId` nem `slug`. |
| `402` `ERR_FEATURE_NOT_IN_PLAN` | O plano da empresa não tem Formulários. |
| `402` `ERR_TENANT_PAYMENT_BLOCKED` | Empresa bloqueada por pagamento. |
| `400` `ERR_FORM_INVALID` | Sem `details`: `answers` ausente ou fora do formato de objeto. Com `details.fields`: um código por chave de campo (`required`, `tooLong`, `invalidEmail`, `invalidPhone`, `invalidNumber`, `outOfRange`, `invalidDate`, `invalidOption` ou `mustAccept`). |
| `400` `ERR_FORM_CONTACT_REQUIRED` | Faltou o telefone ou o e-mail que o formulário exige para achar o contato. |
| `413` `ERR_FORM_TOO_LARGE` | Respostas acima de 32 KB. |

> [!TIP]
>
> Para montar e configurar o formulário (campos, destino, confirmação e o link público), veja [Formulários](https://ajuda.pandazap.com/platform/formularios.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.