> ## 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 formularios

> Referencia interna para la API de Forms: formulario CRUD, manejo de envío de chat/widget, administración de respuestas e integración del creador de formularios.

> **Documentación interna para desarrolladores.** Esta página cubre la API de Forms: creación de formularios, incorporación de widgets de chat, procesamiento de envíos y el esquema del generador de formularios. No está destinado a usuarios finales.

***

## Mapa de ruta

| Método   | Punto final                       | Archivo de controlador                | Descripción                             |
| -------- | --------------------------------- | ------------------------------------- | --------------------------------------- |
| `GET`    | `/api/forms`                      | `forms/route.ts`                      | Listar todos los formularios            |
| `POST`   | `/api/forms`                      | `forms/route.ts`                      | Crear un formulario                     |
| `GET`    | `/api/forms/[formId]`             | `forms/[formId]/route.ts`             | Obtener formulario por ID               |
| `PATCH`  | `/api/forms/[formId]`             | `forms/[formId]/route.ts`             | Formulario de actualización             |
| `DELETE` | `/api/forms/[formId]`             | `forms/[formId]/route.ts`             | Eliminar formulario                     |
| `POST`   | `/api/forms/[formId]/chat`        | `forms/[formId]/chat/route.ts`        | Enviar formulario de respuesta vía chat |
| `GET`    | `/api/forms/[formId]/submissions` | `forms/[formId]/submissions/route.ts` | Lista de envíos de formularios          |

***

## Patrón de autenticación

Los formularios tienen **patrones de acceso dual**:

**Autenticado (panel de control):**
***CÓDIGO\_BLOQUE\_0***

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

* `POST /api/forms/[formId]/chat` se puede llamar sin autenticación
* Protegido por el secreto `formId` (firmado por HMAC si es necesario)

***

## Esquema de formulario

Los formularios se definen como un esquema JSON almacenado en el 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;
  };
}
```

***

## Punto final de envío de chat

El punto final `POST /api/forms/[formId]/chat` procesa el envío de un formulario a través de la 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
```

Esto potencia la experiencia conversacional del widget de formulario.

***

## Envíos

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

Los envíos se almacenan como blobs JSON; la estructura exacta depende del esquema de campo del formulario.

***

## Índices Prisma utilizados

| Mesa             | Índice           | Utilizado por                   |
| ---------------- | ---------------- | ------------------------------- |
| `Form`           | `organizationId` | Formularios de lista            |
| `FormSubmission` | `formId`         | Listar envíos por formulario    |
| `FormSubmission` | `contactId`      | Historial de envío de contactos |

***

## Problemas conocidos / Problemas

* **Punto final del chat público:** El `formId` es el único secreto que protege los envíos de formularios públicos. Para formularios confidenciales, considere agregar la firma HMAC o reCAPTCHA.
* **Evolución del esquema JSON de envío:** Si los campos del formulario cambian después de que existen los envíos, los envíos antiguos pueden tener campos que ya no coincidan con el esquema actual. La interfaz de usuario debe manejar correctamente los campos faltantes.
* **Tiempo de espera de procesamiento de IA:** el punto final de envío del chat llama a la IA, lo que puede tardar hasta 30 segundos en el caso de formularios complejos. Configure el tiempo de espera de la función Next.js adecuado.
* **Entrega de webhook:** El webhook externo al enviar se activa y olvida. Implemente la lógica de reintento en `@zappway/lib/webhooks` si se requiere confiabilidad.