Requisitos técnicos: servidor, rede, segurança, frontend

Runtime e linguagem — independente de linguagem; qualquer coisa que faça HTTP+JSON de saída (Node.js, Python, PHP 7.4+, Go, Java/Kotlin, Ruby, .NET). Cliente HTTP padrão + JSON, sem SDK. UTF-8 em tudo (conversas multilíngues, cirílico, CJK).

Rede (crítico) — HTTPS de saída, porta 443 para o nosso domínio de API (adicione à allowlist se o egress for restrito); DNS funcionando; TLS 1.2+ com validação de certificado (CA pública — não desative a verificação); atrás de um proxy corporativo, configure HTTPS_PROXY. Não são necessárias portas de entrada nem IP estático.

Recursos do servidor — desprezíveis: uma requisição JSON por turno, ~1 conexão de saída e alguns KB por mensagem. Inferência do LLM, catálogo e vetores ficam do nosso lado — nenhuma GPU/RAM/disco do seu.

Chaves e segredos — Authorization: Bearer <key>. Mantenha a chave em env / um cofre de segredos (Vault, Secrets Manager, K8s secrets); nunca no repositório, no código do cliente, em logs ou URLs. As chaves de sandbox e de produção são diferentes.

Timeouts e resiliência — latência limitada pelo LLM: 0,8–3 s (raramente 5–8). Timeout do cliente ≥ 10 s. Fail-soft é obrigatório: em caso de erro, timeout ou ad:null, exiba a resposta sem o card. Repita apenas em erro de rede/5xx, no máximo 1 vez com backoff; nunca repita 429 ou ad:null. Opcionalmente, encaminhe o IP do usuário final (X-Forwarded-For) e o session_id para limites justos.

Frontend / renderização do card — navegadores evergreen (últimas 2 versões), Safari mobile 15+, Chrome Android; ES2017+, fetch. Forneça um contêiner no fluxo da resposta. Obrigatório: rótulo visível "Sponsored", rel="sponsored noopener", target="_blank". Clique somente pelo nosso /c/{token} — sem reescrever, sem envolver no seu próprio redirecionamento.

CSP (se habilitado) — connect-src: domínio da API; script-src: domínio do ads.js (modo B); img-src: domínios de CDN dos lojistas ou https: — caso contrário, as imagens dos produtos não serão renderizadas.

Limites e dados — corpo da requisição ≤ 256 KB (últimos ~8–12 turnos); uma chamada /api/chat por turno; geo em ISO alpha-2. Nenhum PII é necessário. Rate limit por chave/IP e um teto diário de gastos estão ativos desde o primeiro dia — veja Ganhos e limites.