Saltar al contenido principal

Buenas prácticas

Flujo recomendado​

1. (opcional) GET /v1/history?q=<pregunta>   → ¿ya existe una respuesta guardada?
2. POST /v1/ask                              → solo si no existe (gasta LLM)
3. ejecutar sql + params en tu base de datos  (usuario de solo lectura)
4. POST /v1/feedback                         → 👍 / 👎 del usuario

Lista de verificación​

  • La llamada a Datafala sale de tu backend; la API key nunca llega al navegador ni a la app.
  • El SQL se ejecuta con un usuario de solo lectura, con acceso solo a las tablas registradas y tiempo máximo por consulta.
  • params se pasa siempre al driver, incluso vacío.
  • end_user se envía en todas las preguntas, generado con HMAC y un secreto fijo del servidor.
  • Si el sistema es multiempresa, hay RLS, vistas filtradas o acceso restringido (consulta Alcance de datos).
  • El timeout de tu cliente HTTP en /v1/ask es de al menos 60 s, y un timeout no se repite automáticamente.
  • Los errores se tratan por el code, con Retry-After respetado en 429 y 503.
  • El request_id (o el header X-Request-ID) se registra en tus logs.
  • El usuario puede dar 👍 / 👎, enviado a /v1/feedback.

Ahorra tokens​

  • Reutiliza antes de generar. Las preguntas repetidas pueden venir de /v1/history?q= o de tu propia caché por request_id.
  • Cuidado con las fechas relativas al reutilizar: los params guardados son los del día de la pregunta.
  • Muestra la explanation al usuario. Le ayuda a notar cuando la consulta no es lo que quería, y el 👎 se convierte en señal para que el administrador mejore el contexto y los ejemplos.