Setup para agentes de código

Se você usa um agente de código — Claude Code, OpenAI Codex, Cursor — não precisa copiar nada desta página. Cole a URL abaixo no seu agente e ele lê a documentação inteira sozinho:

https://developers.zarv.com/llms.txt

Colar https://developers.zarv.com também funciona: cada página carrega um ponteiro para a versão em Markdown. Para o conteúdo completo numa única requisição, use https://developers.zarv.com/llms-full.txt.

O restante desta página é o essencial da integração, em formato denso — é o que o agente lê primeiro.

Ambientes

	Produção	Dev / staging
API (Zarv ID)	https://services.zarv.com	—
Collector	https://collector.zarv.com	https://collector.zarv.dev
SDK web	https://js.zarv.com	https://js.zarv.dev

O SDK detecta o ambiente pelo próprio src do script — não há nada a configurar.

Autenticação

Cada API tem seu próprio esquema — não são intercambiáveis.

Zarv ID (services.zarv.com)

OAuth2 com tokens de curta duração.

curl -X POST "https://services.zarv.com/api/v1/authentication" \
  -H "Content-Type: application/json" \
  -d '{"username": "[email protected]", "password": "sua_senha"}'

Resposta:

{
  "accessToken": "eyJhbGci...",
  "refreshToken": "eyJhbGci...",
  "token_type": "Bearer",
  "expires_in": 360,
  "refreshExpiresIn": 1800
}

Use o token em todas as requisições:

Authorization: Bearer <accessToken>

O access token expira em 360 segundos. Renove com POST /api/v1/authentication/refresh, enviando {"refreshToken": "..."}. A renovação devolve os dois tokens — guarde o novo refresh token, porque o anterior deixa de valer.

Detalhes e exemplos em outras linguagens: Autenticação.

Collector (collector.zarv.com)

HTTP Basic — sem troca de token. Codifique username:password em Base64 e envie no cabeçalho em toda requisição:

Authorization: Basic base64(username:password)

Detalhes e exemplos em outras linguagens: Autenticação.

Specs OpenAPI

São a fonte da verdade para rotas, parâmetros e schemas. Prefira lê-los a inferir endpoints da prosa:

• /openapi/zarv-api.json — Zarv ID (verificação de identidade e score).
• /openapi/collector-api.json — Collector (ingestão de eventos e telemetria).

SDK web

Um único loader serve dois produtos:

<script async src="https://js.zarv.com/sdk.js"></script>
<script>
  Zarv("chat", { publicKey: "pk-XXXXXXXX" });
</script>

• Chat — widget de conversa, via Zarv('chat', config).
• Smartflow — funnel de cadastro/KYC, via Zarv('smartflow', config), embutido inline (mount) ou em modal (mode: 'modal').

Chamadas feitas antes do bundle carregar são enfileiradas — não espere nenhum evento de "ready".

Armadilhas

• Nunca coloque username, password ou o refreshToken no navegador. O fluxo de autenticação é servidor-a-servidor.
• A publicKey do SDK (pk-<id>) é pública por design e não é credencial de API. Ela pode ser regenerada no admin Zarv; ao regenerar, a chave antiga para de funcionar imediatamente.
• O access token dura 6 minutos. Renove pelo refresh em vez de reautenticar com usuário e senha a cada requisição.
• Os esquemas de autenticação diferem por produto e não são intercambiáveis: Zarv ID (services.zarv.com) usa OAuth2 com token Bearer; Collector (collector.zarv.com) usa HTTP Basic direto, sem troca de token.

Edge Agent

Instalação on-premise para ingestão de câmeras — é operação, não código de integração. Veja Edge Agent.