API 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

​

Patrón de autenticación

• 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

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

// 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

​

Envíos

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

​

Índices Prisma utilizados

​

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.