Usar Postman

Postman permite probar las llamadas HTTP de Datafala antes de integrar la API en tu sistema. Puedes importar los endpoints descritos en esta documentación y configurar una API key para las solicitudes autenticadas.

Importar los endpoints

El contrato OpenAPI de Datafala está disponible en:

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

En Postman:

1. Selecciona Import.
2. Elige importar por Link.
3. Introduce la URL de OpenAPI de arriba y confirma.
4. Guarda la colección generada.

El contrato incluye solo los endpoints descritos en la Referencia de la API, y puede actualizarse junto con la documentación.

Configurar variables

Crea un Environment en Postman con estas variables:

Variable	Valor inicial	Uso
baseUrl	https://app.datafala.com.br	URL base de la API.
apiKey	tu clave tsk_...	Clave del tenant, marcada como secreta/sensible en Postman.
endUser	identificador opaco estable	Se usa en el cuerpo de /v1/ask cuando el tenant lo exige.

En las solicitudes de la colección, configura la URL como {{baseUrl}} seguido de la ruta del endpoint. En las llamadas /v1/*, envía el header:

Authorization: Bearer {{apiKey}}

No compartas ni versiones el valor de la API key. Se muestra una sola vez al crearla y debe mantenerse protegida como secreto.

Hacer una pregunta

Usa POST {{baseUrl}}/v1/ask, selecciona Body → raw → JSON y envía:

{
  "question": "¿Cuántos pedidos se hicieron ayer?",
  "end_user": "{{endUser}}",
  "max_rows": 100,
  "locale": "es"
}

El campo end_user es obligatorio para los tenants que lo exigen. Consulta la guía del identificador del usuario final para generar un valor opaco y estable; no envíes nombre, correo u otro dato personal.

Una respuesta exitosa contiene el SQL validado, los parámetros con nombre, las tablas usadas y un request_id. Datafala no ejecuta el SQL ni accede a la base de datos del cliente: ejecuta la consulta en tu backend con los permisos adecuados.

Consultar el historial y enviar feedback

Todas las operaciones siguientes usan Authorization: Bearer {{apiKey}}:

Método	URL	Descripción
GET	{{baseUrl}}/v1/history?limit=10	Lista las respuestas recientes.
GET	{{baseUrl}}/v1/history/{{requestId}}	Recupera una respuesta por su request_id.
POST	{{baseUrl}}/v1/feedback	Envía una valoración para una respuesta.

Para enviar feedback, agrega requestId como variable y usa un cuerpo JSON:

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

rating acepta good o bad; el comentario opcional puede enviarse en el campo comment. La respuesta de éxito es 204 No Content.

Verificar la salud del servicio

Los endpoints de salud no requieren API key:

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

/healthz verifica que el proceso esté activo. /readyz verifica que la API pueda acceder a su propia base de datos.

Errores comunes

• 401 invalid_api_key: revisa que la API key sea correcta, esté activa y se envíe como token Bearer.
• 400 end_user_required: envía un identificador end_user estable.
• 409 schema_not_configured o llm_not_configured: el administrador del tenant debe terminar la configuración en el panel.
• 422 no_answer o sql_rejected: reformula la pregunta de acuerdo con los datos registrados en el schema.
• 429 rate_limited: espera el período indicado en el header Retry-After antes de repetir.
• 502 llm_error: revisa la configuración o la disponibilidad del proveedor de LLM.

Consulta la lista completa en la Referencia de errores. Para las llamadas POST /v1/ask, configura un timeout de al menos 60 segundos y no repitas automáticamente una solicitud que expiró.