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.

Hosts

Todas as integrações usam os hosts de produção abaixo.

Produto	Host
API (Zarv ID v2 e v3)	`https://services.zarv.com`
Collector	`https://collector.zarv.com`
SDK web	`https://js.zarv.com`

Carregue sempre https://js.zarv.com/sdk.js, inclusive em localhost. Para testar sem tocar em dados reais, use uma campanha/bot de teste — quem separa os mundos é a chave pública, não o host.

Autenticação

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

Zarv ID v2 e v3 (`services.zarv.com`)

Usuário e senha trocados por um Bearer JWT 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:

json

{
  "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/id-v2-api.json — Zarv ID v2 (legado com perfil, rotas /api/v2/...).
/openapi/id-v3-api.json — Zarv ID v3 (enriquecimento de CPF e CNPJ, rotas /api/v3/..., mesmo Bearer JWT do Zarv ID). Formato dos dados de cada módulo em Datasets.
/openapi/collector-api.json — Collector (ingestão de eventos e telemetria).

SDK web

Um único loader serve dois produtos:

html

<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). Uma chamada por publicKey; para mais de um agente na página, veja Vários chats na mesma página.
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 v2 e v3 (services.zarv.com) usam usuário e senha trocados por um Bearer JWT; 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.

Setup para agentes de código ​

Hosts ​

Autenticação ​

Zarv ID v2 e v3 (services.zarv.com) ​

Collector (collector.zarv.com) ​

Specs OpenAPI ​

SDK web ​

Armadilhas ​

Edge Agent ​