FormFlow
FormFlow e Doc Analyzer
FormFlow
FormFlow e Doc Analyzer
Guia prático para escolher, chamar e combinar captura estruturada e análise de diálogo
Este guia resume quando usar FormFlow ou Doc Analyzer e aponta o endpoint certo para cada cenário de integração.
Autenticação
Authorization: Bearer {{TOKEN}}
Content-Type: application/json
Em produção, o gateway injeta contexto de host quando aplicável. Em desenvolvimento, o backend pode aceitar hostId no body para testes.
Bases URL
| Recurso | Base |
|---|---|
| FormFlow (público) | {{BASE_URL}}/api/externalAPIs/public/formFlow |
| Doc Analyzer (público) | {{BASE_URL}}/api/externalAPIs/public/docAnalyzer |
| FormFlow v4 (lote síncrono + custo) | {{BASE_URL}}/api/v4/formFlow |
O que cada recurso resolve
| Área | O que é | Quando usar |
|---|---|---|
| FormFlow | Camada de formulários e captura estruturada ligada a leads, conversas e avatares | Quando precisa definir campos, montar catálogos e ler ou gravar valores capturados |
| Doc Analyzer | Análise de diálogo com saída estruturada baseada em schema ou catálogo | Quando precisa extrair JSON rapidamente sem montar todo o pipeline de captura |
Como escolher
| Necessidade | Caminho sugerido |
|---|---|
| Persistir valores no modelo oficial de formulários e leads | Capturar a partir de Conversas |
| Processar lote com resposta síncrona e custo detalhado | FormFlow v4 - batchAnalyzeDialogue |
| Extrair JSON estruturado para integrar em outro sistema | Doc Analyzer - analyzeDialogue |
| Processar muitas conversas sem segurar a requisição | Doc Analyzer - batchAnalyzeDialogue |
| Gerar schema e instruções a partir de texto livre | Doc Analyzer - buildInstructionFromNatural |
Endpoints recomendados
FormFlow
- Buscar campos
- Buscar catálogos
- Schema de catálogo
- Buscar valores
- Schema de captura por conversa
- Capturar a partir de conversas
- FormFlow v4 - batchAnalyzeDialogue
Doc Analyzer
Exemplo rápido
curl -X POST "{{BASE_URL}}/api/externalAPIs/public/docAnalyzer/analyzeDialogue" \
-H "Authorization: Bearer {{TOKEN}}" \
-H "Content-Type: application/json" \
-d '{
"instructions": "Extraia nome e intencao do cliente.",
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"nome": { "type": "string" },
"intencao": { "type": "string" }
},
"required": ["nome"]
},
"dialogue": [
{ "role": "user", "content": "Sou a Ana e quero um orcamento." }
]
}'
Resposta
{
"data": {
"nome": "Ana",
"intencao": "orcamento"
},
"error": null,
"rawResult": {},
"metrics": {
"elapsedMs": 0
},
"formDataRecorded": null
}
Campos da Resposta
data
object
Objeto estruturado conforme o schema enviado ou o schema do catálogo.
error
string | null
Mensagem de erro quando a análise falha.
metrics
object
formDataRecorded
object | null
Resultado de persistência no FormFlow quando recordFormData estiver habilitado.
Erros
| Código | Descrição |
|---|---|
400 | Body inválido ou combinação de parâmetros inconsistente |
401 | Token inválido ou ausente |
500 | Erro interno do servidor |