API 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

​

Padrão de autenticação

withPermissionRoute(req, { permission: 'forms.manage' }, handler)

• 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

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

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

​

Envios

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

​

Índices Prisma usados

​

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.