---
url: https://developers.zarv.com/setup.md
description: >-
  Integre a Zarv com Claude Code, Codex ou Cursor: aponte o agente para o
  llms.txt e use os hosts, a autenticação e o loader do SDK documentados.
---

# 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.

```sh
curl -X POST "https://services.zarv.com/api/v1/authentication" \
  -H "Content-Type: application/json" \
  -d '{"username": "seu.email@zarv.com", "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](/api/id-v2/authentication).

### 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](/api/collector/authentication).

## 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`](/openapi/id-v2-api.json) — Zarv ID v2 (legado com
  perfil, rotas `/api/v2/...`).
* [`/openapi/id-v3-api.json`](/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](/api/id-v3/datasets/).
* [`/openapi/collector-api.json`](/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](/sdk/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](/sdk/chat#varios-chats-na-mesma-pagina).
* **[Smartflow](/sdk/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](/edge-agent/).