Developers

Aparência

Vai integrar a API REST da Zarv com ajuda de IA? Copie a instrução que aponta o modelo para esta documentação.
Ver a instrução
Você vai integrar a API REST da Zarv. Use a documentação oficial como fonte da verdade.

- Página desta integração: https://developers.zarv.com/api/limits
- Autenticação Bearer JWT e hosts: https://developers.zarv.com/setup
- Índice das APIs: https://developers.zarv.com/api
- Índice da documentação em markdown: https://developers.zarv.com/llms.txt
- Documentação completa em um arquivo: https://developers.zarv.com/llms-full.txt

Os specs OpenAPI publicados são a fonte da verdade para rotas e schemas — use o spec da API que você escolher antes de escrever qualquer request.

Antes de escrever qualquer código, leia a página desta integração. Siga exatamente os nomes de campos, endpoints, callbacks e formatos que estiverem documentados — não invente parâmetros nem endpoints, e não deduza comportamento a partir de outras APIs que você conhece. Se algo de que você precisa não estiver na documentação, diga que não está em vez de supor.

Minha tarefa: [ex.: escolher a API certa e fazer a primeira chamada autenticada]

Limites de uso ​

As rotas de verificação aplicam um limite de taxa por workspace.

RotasLimiteRajada
/api/v2/verifications/*50 requisições por segundo100 requisições

O limite é a taxa sustentada: 50 requisições a cada segundo, continuamente. A rajada é quanto você pode disparar de uma vez, partindo do repouso — até 100 requisições simultâneas passam, e a partir daí a taxa volta a valer.

O limite é por workspace ​

A contagem usa o workspace do seu token, e não o endereço IP nem o usuário. Duas consequências:

  • Todas as suas máquinas compartilham a mesma cota. Se você roda a integração em vários servidores, some o tráfego de todos.
  • O consumo de um cliente não afeta o de outro. Cada workspace tem sua própria cota.

O que você recebe ao exceder ​

Status 429 Too Many Requests. A requisição não é processada nem cobrada.

Não há bloqueio nem punição: assim que a taxa cair, as requisições voltam a passar no mesmo instante.

Como trabalhar dentro do limite ​

Trate o 429 com espera crescente. Ao receber 429, espere antes de tentar de novo, dobrando o intervalo a cada nova falha (por exemplo 1s, 2s, 4s, 8s). Repetir imediatamente não adianta.

Use o endpoint de lote para volume. Para verificar muitos documentos, prefira POST /api/v2/verifications/batch a disparar uma requisição por documento.

Reutilize o token de acesso. Ele vale 6 minutos. Renove pelo endpoint de refresh em vez de reenviar usuário e senha a cada chamada.

Webhooks não contam. Os callbacks que a Zarv envia ao seu endpoint não passam por esse limite — ele vale só para as requisições que você faz à API.

Se o seu volume for maior ​

50 requisições por segundo atendem com folga o uso normal. Se a sua integração precisar de mais, fale com o time da Zarv antes de subir o volume em produção.

Atualizado em: