Pular para o conteúdo principal

Boas práticas

Fluxo recomendado​

1. (opcional) GET /v1/history?q=<pergunta>   → já existe resposta guardada?
2. POST /v1/ask                              → só se não houver (gasta LLM)
3. executar sql + params no seu banco         (usuário somente leitura)
4. POST /v1/feedback                         → 👍 / 👎 do usuário

Checklist​

  • A chamada ao Datafala sai do seu backend; a API key nunca vai ao navegador ou ao app.
  • O SQL é executado com um usuário somente leitura, com acesso só às tabelas cadastradas e tempo máximo por consulta.
  • params é passado sempre ao driver, mesmo vazio.
  • end_user é enviado em todas as perguntas, gerado com HMAC e um segredo fixo do servidor.
  • Se o sistema é multiempresa, há RLS, views filtradas ou acesso restrito (veja Escopo de dados).
  • O timeout do cliente HTTP em /v1/ask é de pelo menos 60 s, e um timeout não é repetido automaticamente.
  • Erros são tratados pelo code, com Retry-After respeitado em 429 e 503.
  • O request_id (ou o header X-Request-ID) é registrado nos seus logs.
  • O usuário pode dar 👍 / 👎, enviado a /v1/feedback.

Economize tokens​

  • Reaproveite antes de gerar. Perguntas repetidas podem vir de /v1/history?q= ou do seu próprio cache por request_id.
  • Cuidado com datas relativas ao reaproveitar: os params guardados são os do dia da pergunta.
  • Mostre a explanation ao usuário. Ela ajuda a perceber quando a consulta não é o que ele queria, e o 👎 vira sinal para o administrador melhorar contexto e exemplos.