Usando Postman

O Postman permite testar as chamadas HTTP do Datafala antes de integrar a API ao seu sistema. Você pode importar os endpoints descritos nesta documentação e configurar uma API key para as requisições autenticadas.

Importar os endpoints

O contrato OpenAPI do Datafala está disponível em:

https://datafala.com.br/openapi/swagger.json

No Postman:

1. Selecione Import.
2. Escolha importar por Link.
3. Informe a URL do OpenAPI acima e confirme.
4. Salve a collection gerada.

O contrato inclui somente os endpoints descritos na Referência da API, e pode ser atualizado junto com a documentação.

Configurar variáveis

Crie um Environment no Postman com estas variáveis:

Variável	Valor inicial	Uso
baseUrl	https://app.datafala.com.br	URL base da API.
apiKey	sua chave tsk_...	Chave do tenant, marcada como secreta/sensível no Postman.
endUser	identificador opaco estável	Usada no corpo de /v1/ask quando exigida pelo tenant.

Nas requests da collection, configure a URL como {{baseUrl}} seguida pelo caminho do endpoint. Nas chamadas /v1/*, envie o header:

Authorization: Bearer {{apiKey}}

Não compartilhe nem versione o valor da API key. Ela é exibida uma única vez quando criada e deve ficar protegida como segredo.

Fazer uma pergunta

Use POST {{baseUrl}}/v1/ask, selecione Body → raw → JSON e envie:

{
  "question": "Quantos pedidos foram feitos ontem?",
  "end_user": "{{endUser}}",
  "max_rows": 100,
  "locale": "pt-BR"
}

O campo end_user é obrigatório para tenants que o exigem. Consulte o guia de identificador do usuário final para gerar um valor opaco e estável; não envie nome, e-mail ou outro dado pessoal.

Uma resposta bem-sucedida contém o SQL validado, os parâmetros nomeados, as tabelas usadas e um request_id. O Datafala não executa o SQL nem acessa o banco do cliente: execute a consulta no seu backend com as permissões adequadas.

Consultar histórico e enviar feedback

Todas as operações abaixo usam Authorization: Bearer {{apiKey}}:

Método	URL	Descrição
GET	{{baseUrl}}/v1/history?limit=10	Lista as respostas recentes.
GET	{{baseUrl}}/v1/history/{{requestId}}	Recupera uma resposta pelo request_id.
POST	{{baseUrl}}/v1/feedback	Envia uma avaliação para uma resposta.

Para enviar feedback, adicione requestId como variável e use corpo JSON:

{
  "request_id": "{{requestId}}",
  "rating": "good"
}

rating aceita good ou bad; o comentário opcional pode ser enviado no campo comment. A resposta de sucesso é 204 No Content.

Verificar a saúde do serviço

Os endpoints de saúde não exigem API key:

GET {{baseUrl}}/healthz
GET {{baseUrl}}/readyz

/healthz verifica se o processo está ativo. /readyz verifica se a API consegue acessar o próprio banco.

Erros comuns

• 401 invalid_api_key: confira se a API key está correta, ativa e enviada como Bearer token.
• 400 end_user_required: envie um identificador end_user estável.
• 409 schema_not_configured ou llm_not_configured: o administrador do tenant precisa concluir a configuração no painel.
• 422 no_answer ou sql_rejected: reformule a pergunta de acordo com os dados cadastrados no schema.
• 429 rate_limited: aguarde o período indicado no header Retry-After antes de repetir.
• 502 llm_error: confira a configuração ou disponibilidade do provedor de LLM.

Veja a lista completa na Referência de erros. Para chamadas POST /v1/ask, configure um timeout de pelo menos 60 segundos e não repita automaticamente uma requisição que expirou.