Contrato da API: POST /api/chat

Autenticação: header Authorization: Bearer <partner key>. Sandbox e produção usam chaves e URLs base diferentes (emitidas no onboarding).

Uma chamada por turno da conversa, síncrona com a resposta do assistente. Corpo ≤ 256 KB — envie os últimos ~8–12 turnos, não o histórico inteiro.

Requisição

{
  "messages": [ {"role":"user","content":"preciso de uma mochila para notebook"} ],
  "geo": "BR",
  "session_id": "abc123",
  "lang": "pt"
}

• messages[] — obrigatório; histórico da conversa, papéis user / assistant.
• geo — obrigatório; país do usuário, ISO-3166 alpha-2 (MY, ID, BR…). O inventário e as taxas dependem dele.
• session_id — opcional; estável por sessão do usuário, para limites justos por usuário e antifraude.
• lang — opcional; dica do idioma da interface.
• Header opcional X-Forwarded-For com o IP do usuário final para limites por usuário. Nenhum dado pessoal (PII) é exigido.

Resposta 200

{
  "reply": "…texto do assistente, sempre exibido…",
  "ad": {
    "type": "product",
    "title": "…", "desc": "…", "price": "MYR 129",
    "image": "https://cdn…/p.jpg",
    "sponsored": true,
    "click_url": "https://api.indoleads.ai/c/<token>"
  },
  "intent": { "show_ad": true, "confidence": 0.72, "category": "…" }
}

• reply — sempre renderize.
• ad — objeto ou null (sem intenção comercial). type: product | offer | coupon (tem code) | banner. Renderize title, desc, price, image; faça o link para click_url com rel="sponsored noopener" target="_blank" e um rótulo Sponsored (Patrocinado) visível. Nunca reescreva nem envolva o click_url.
• intent — para a sua análise.

Códigos de status

Latência: limitada pelo LLM — 0,8–3 s, raramente 5–8 s. Defina o timeout do cliente ≥ 10 s. Em caso de erro/timeout/ad:null, exiba a resposta sem card — os anúncios nunca devem quebrar o chat.