Generar SQL: POST /v1/ask

POST https://app.datafala.com.br/v1/ask

Recibe una pregunta en lenguaje natural y devuelve un SELECT validado por el SQL Guard, con los valores en params. Cada llamada hace de 1 a 2 llamadas al LLM de tu tenant (la segunda es una corrección automática cuando el primer SQL es rechazado).

Solicitud

Headers:

Authorization: Bearer tsk_1a2b3c4d_...
Content-Type: application/json
Accept-Language: es        (opcional)

Cuerpo:

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

Campo	Tipo	Obligatorio	Descripción
question	string	sí	La pregunta, de hasta 2.000 caracteres.
end_user	string	sí*	Identificador opaco de la persona que preguntó, de 16 a 128 caracteres (A-Z, a-z, 0-9, _, -). Consulta Identificador del usuario final. *Obligatorio para la mayoría de los clientes.
max_rows	entero	no	Máximo de filas, ≥ 1. Por defecto 100, techo 1.000. La API aplica un LIMIT al SQL; las agregaciones que devuelven una sola fila quedan sin LIMIT.
locale	string	no	Idioma de message y explanation: pt-BR, en o es. Variantes como en-US o es-419 caen en el idioma principal (en, es). Precedencia: este campo → header Accept-Language → idioma por defecto del tenant (configurado en el panel) → pt-BR.

Los campos desconocidos se rechazan con 422 invalid_request. El cuerpo completo puede tener hasta 96 KiB.

Respuesta 200

{
  "sql": "SELECT count(*) AS total FROM public.pedidos WHERE criado_em >= %(start)s AND criado_em < %(end)s",
  "params": { "start": "2026-10-22", "end": "2026-10-23" },
  "dialect": "postgres",
  "tables": ["public.pedidos"],
  "explanation": "Cuenta los pedidos creados ayer.",
  "locale": "es",
  "request_id": "req_0f3c9a7d2b6e4f1a8c5d0e9b7a6f3c21"
}

Campo	Tipo	Descripción
sql	string	Un único SELECT, en el dialecto de tu schema, con placeholders %(nombre)s.
params	objeto	Valores de los placeholders: string, número, booleano o null. Puede ser {}.
dialect	string	postgres, mysql o firebird.
tables	lista de strings	Tablas usadas por la consulta.
explanation	string o null	Explicación breve de lo que hace la consulta, en el idioma resuelto.
locale	string	Idioma usado en la respuesta.
request_id	string	req_ + 32 caracteres hexadecimales. Úsalo para enviar feedback y buscar la respuesta en el historial.

El mismo request_id viene en el header X-Request-ID de toda respuesta, incluidas las de error.

Sobre el SQL devuelto

• Los nombres de tablas y columnas son los de tu base de datos, exactamente como están en el DDL registrado.
• El texto del usuario nunca se concatena al SQL: valores como nombres, fechas y términos de búsqueda llegan en params.
• Todo % que no es placeholder sale escapado como %% (por ejemplo LIKE 'A%%'), al estilo de los drivers de Python. Por eso pasa siempre params al driver, incluso vacío. Consulta Ejecutar el SQL.
• Las fechas relativas ("ayer", "el mes pasado") se resuelven en el momento de la pregunta, con la fecha de hoy enviada al LLM.

Errores comunes

HTTP	code	Qué hacer
400	end_user_required	Envía end_user.
401	invalid_api_key	Corrige la clave.
409	schema_not_configured, llm_not_configured	El administrador debe terminar la configuración en el panel.
422	no_answer	El schema no permite responder; pide al usuario que reformule.
422	sql_rejected	El SQL generado no pasó el Guard, incluso tras la corrección automática.
429	rate_limited	Espera el tiempo del header Retry-After.
502	llm_error	Fallo en el proveedor de LLM; consulta details.reason.

La lista completa está en Errores.

Latencia

Una pregunta suele tardar unos segundos, y hasta el doble cuando se ejecuta la corrección automática. Configura el timeout de lectura de tu cliente HTTP en al menos 60 segundos y no repitas automáticamente un POST /v1/ask que dio timeout, porque cada intento gasta tokens de tu LLM.

Ejemplo

curl -sS -X POST "https://app.datafala.com.br/v1/ask" \
  -H "Authorization: Bearer $DATAFALA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"question": "Top 5 clientes por facturación en 2026", "end_user": "'"$END_USER"'", "max_rows": 5}'

Más ejemplos en Ejemplos de integración.