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

# API de formulários

> Referência interna para a API Forms — formulário CRUD, tratamento de envio de chat/widget, gerenciamento de respostas e integração do construtor de formulários.

> **Documentação interna para desenvolvedores.** Esta página aborda a API Forms: criação de formulário, incorporação de widget de bate-papo, processamento de envio e esquema do construtor de formulário. Não se destina a usuários finais.

***

## Mapa de rotas

| Método   | Ponto final                       | Arquivo manipulador                   | Descrição                              |
| -------- | --------------------------------- | ------------------------------------- | -------------------------------------- |
| `GET`    | `/api/forms`                      | `forms/route.ts`                      | Listar todos os formulários            |
| `POST`   | `/api/forms`                      | `forms/route.ts`                      | Crie um formulário                     |
| `GET`    | `/api/forms/[formId]`             | `forms/[formId]/route.ts`             | Obter formulário por ID                |
| `PATCH`  | `/api/forms/[formId]`             | `forms/[formId]/route.ts`             | Formulário de atualização              |
| `DELETE` | `/api/forms/[formId]`             | `forms/[formId]/route.ts`             | Excluir formulário                     |
| `POST`   | `/api/forms/[formId]/chat`        | `forms/[formId]/chat/route.ts`        | Enviar resposta do formulário via chat |
| `GET`    | `/api/forms/[formId]/submissions` | `forms/[formId]/submissions/route.ts` | Listar envios de formulários           |

***

## Padrão de autenticação

Os formulários têm **padrões de acesso duplo**:

**Autenticado (painel):**

```ts theme={null}
withPermissionRoute(req, { permission: 'forms.manage' }, handler)
```

**Público (widget incorporado):**

* `POST /api/forms/[formId]/chat` pode ser chamado sem autenticação
* Protegido pelo sigilo `formId` (assinado pelo HMAC, se necessário)

***

## Esquema de formulário

Os formulários são definidos como um esquema JSON armazenado no campo `config`:

```ts theme={null}
interface FormConfig {
  fields: FormField[];
  submitButtonText: string;
  successMessage: string;
  agentId?: string;      // AI to process submission
  webhookUrl?: string;   // External webhook on submit
}

interface FormField {
  id: string;
  type: 'text' | 'email' | 'phone' | 'select' | 'multiselect' | 'textarea' | 'number';
  label: string;
  placeholder?: string;
  required: boolean;
  options?: string[];    // for select/multiselect
  validation?: {
    pattern?: string;    // regex
    min?: number;
    max?: number;
  };
}
```

***

## Ponto final de envio de bate-papo

O endpoint `POST /api/forms/[formId]/chat` processa o envio de um formulário por meio da IA:

```ts theme={null}
// Input: form field responses
// Processing:
// 1. Validate all required fields
// 2. Create Contact from submission data (if email/phone provided)
// 3. Create Conversation linked to the form
// 4. Pass responses to assigned AI Employee
// 5. AI generates a personalized response
// 6. Return AI response + conversationId
```

Isso potencializa a experiência de conversação do widget de formulário.

***

## Envios

```ts theme={null}
// GET /api/forms/[formId]/submissions
// Returns all submissions for a form
// Each submission: { id, contactId, data: JSON, createdAt }
```

Os envios são armazenados como blobs JSON — a estrutura exata depende do esquema de campo do formulário.

***

## Índices Prisma usados

| Tabela           | Índice           | Usado por                     |
| ---------------- | ---------------- | ----------------------------- |
| `Form`           | `organizationId` | Formulários de lista          |
| `FormSubmission` | `formId`         | Listar envios por formulário  |
| `FormSubmission` | `contactId`      | Histórico de envio do contato |

***

## Problemas conhecidos/pegadinhas

* **Endpoint de bate-papo público:** O `formId` é o único segredo que protege os envios de formulários públicos. Para formulários confidenciais, considere adicionar assinatura HMAC ou reCAPTCHA.
* **Evolução do esquema JSON de envio:** Se os campos do formulário mudarem após a existência dos envios, os envios antigos poderão ter campos que não correspondem mais ao esquema atual. A UI deve lidar com os campos ausentes normalmente.
* **Tempo limite de processamento da IA:** o endpoint de envio do chat chama a IA, o que pode levar até 30 segundos para formulários complexos. Configure o tempo limite da função Next.js apropriado.
* **Entrega do webhook:** O webhook externo ao enviar é disparar e esquecer. Implemente a lógica de nova tentativa em `@zappway/lib/webhooks` se a confiabilidade for necessária.