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/id-v3/reference
- 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]
v0.1.0

Zarv ID v3 — API de Enriquecimento​

Download OpenAPI Document

Enriquecimento de CPF e CNPJ: a partir de um documento e de um perfil, a Zarv consulta os datasets do perfil e devolve, por módulo, os dados exatamente como os datasets os publicam — sem regras, score ou análise por IA.

Todas as rotas usam token Bearer JWT; veja Autenticação. O callback assinado está em Webhook e o formato de cada módulo em Datasets.

Documentos. CPF ou CNPJ, incluindo o CNPJ alfanumérico de 2026 (ex.: 12ABC34501DE35); pontuação e caixa são ignoradas. As respostas trazem o documento normalizado completo.

Servers​

https://services.zarv.comProdução

Callback​

Segredo de assinatura do callback do workspace.

Operations​

GET/api/v3/callback-secret

Consultar o segredo de assinatura do callback​

GET
/api/v3/callback-secret

Cada callback é assinado com X-Zarv-Signature: sha256=<hex>, o HMAC-SHA256 deste segredo sobre "{X-Zarv-Timestamp}.{corpo}". Veja Webhook.

Authorizations​

bearerAuth

Token de acesso obtido em POST /api/v1/authentication. Veja Autenticação.

Type
HTTP (bearer)

Responses​

O segredo, em hexadecimal.

application/json
JSON
{
  
"secret": "string"
}

Playground​

Authorization

Samples​

Enriquecimentos​

Criação, consulta e listagem de enriquecimentos.

Operations​

GET/api/v3/enrichmentsPOST/api/v3/enrichmentsGET/api/v3/enrichments/{id}GET/api/v3/enrichments/{id}/modules/{module}

Listar enriquecimentos​

GET
/api/v3/enrichments

Mais recentes primeiro. Os itens são resumos, sem modules e sem data.

from, to, document, profileId e entity são opcionais e se combinam (todos precisam valer). Eles não vão dentro do nextCursor: repita os mesmos filtros em todas as páginas da mesma listagem.

Authorizations​

bearerAuth

Token de acesso obtido em POST /api/v1/authentication. Veja Autenticação.

Type
HTTP (bearer)

Parameters​

Query Parameters

cursor

O nextCursor da página anterior.

Type
string
limit

Itens por página. Valores acima de 100 são reduzidos para 100.

Type
integer
Default
20
Minimum
1
from

Só enriquecimentos criados a partir deste instante, inclusive. RFC3339, por exemplo 2026-09-01T00:00:00-03:00.

Type
string
Format
"date-time"
to

Só enriquecimentos criados antes deste instante, exclusive. RFC3339. Para o dia 01/09 inteiro: from=2026-09-01T00:00:00-03:00&to=2026-09-02T00:00:00-03:00.

Type
string
Format
"date-time"
document

CPF ou CNPJ, com ou sem máscara, validado como na criação.

Type
string
profileId

Só enriquecimentos deste perfil.

Type
string
entity

person (CPF) ou company (CNPJ), o mesmo valor de entity na resposta. pf e pj também são aceitos.

Type
string
Valid values
"person""company""pf""pj"

Responses​

Uma página.

application/json
JSON
{
  
"items": [
  
  
{
  
  
  
"completedAt": "string",
  
  
  
"createdAt": "string",
  
  
  
"data": {
  
  
  
  
"additionalProperties": "string"
  
  
  
},
  
  
  
"deadline": "string",
  
  
  
"document": "string",
  
  
  
"entity": "string",
  
  
  
"failureReason": "string",
  
  
  
"id": "enr_0199a0b2-7c1e-7d4a-9f0e-3b1c2d4e5f60",
  
  
  
"metadata": {
  
  
  
  
"additionalProperties": "string"
  
  
  
},
  
  
  
"modules": {
  
  
  
  
"additionalProperties": {
  
  
  
  
  
"dataset": "string",
  
  
  
  
  
"nextAttemptAt": "string",
  
  
  
  
  
"status": "string"
  
  
  
  
}
  
  
  
},
  
  
  
"nextRetryAt": "string",
  
  
  
"outcome": "subject_not_found",
  
  
  
"profile": {
  
  
  
  
"id": "string",
  
  
  
  
"kind": "string",
  
  
  
  
"name": "string"
  
  
  
},
  
  
  
"recoveryRound": 0,
  
  
  
"status": "string"
  
  
}
  
],
  
"nextCursor": "string"
}

Playground​

Authorization
Variables
Key
Value

Samples​

Criar um enriquecimento​

POST
/api/v3/enrichments

Valida a requisição, resolve o perfil (do seu workspace ou um perfil global da Zarv), planeja os módulos, confere o contrato do workspace e cria o enriquecimento. Depois, a requisição espera até 25 segundos por um status terminal:

  • terminou a tempo: 200 com o corpo completo e os dados de todos os módulos em data;
  • não terminou: 202 com {id, status}; se houver callback, ele é entregue quando o enriquecimento terminar;
  • mesma Idempotency-Key e mesmo corpo (a chave não expira): 200 com o corpo do GET quando o enriquecimento já terminou, 202 com {id, status} enquanto ainda roda (um callback enviado junto é rearmado);
  • mesma Idempotency-Key com corpo diferente: 422 idempotency_key_reused.

O processamento continua mesmo que o cliente feche a conexão. Uma resposta não terminal traz Retry-After: consulte GET /api/v3/enrichments/{id} depois desse intervalo, ou espere o callback.

Authorizations​

bearerAuth

Token de acesso obtido em POST /api/v1/authentication. Veja Autenticação.

Type
HTTP (bearer)

Parameters​

Header Parameters

Idempotency-Key

Chave de idempotência, até 255 caracteres (ex.: um UUID). A chave não expira: a mesma chave com o mesmo corpo sempre devolve o mesmo enriquecimento, sem nova cobrança. Para uma consulta nova, use uma chave nova.

Type
string
Max Length
255

Request Body​

application/json
JSON
{
  
"callback": {
  
  
"headers": {
  
  
  
"additionalProperties": "string"
  
  
},
  
  
"url": "string"
  
},
  
"document": "12.abc.345/01de-35",
  
"metadata": {
  
  
"additionalProperties": "string"
  
},
  
"options": {
  
  
"deadline": "2h",
  
  
"modules": {
  
  
  
"additionalProperties": {
  
  
  
}
  
  
}
  
},
  
"profileId": "string"
}

Responses​

Terminou dentro da espera síncrona, ou replay idempotente de um enriquecimento já terminado.

application/json
JSON
{
  
"completedAt": "string",
  
"createdAt": "string",
  
"data": {
  
  
"additionalProperties": "string"
  
},
  
"deadline": "string",
  
"document": "string",
  
"entity": "string",
  
"failureReason": "string",
  
"id": "enr_0199a0b2-7c1e-7d4a-9f0e-3b1c2d4e5f60",
  
"metadata": {
  
  
"additionalProperties": "string"
  
},
  
"modules": {
  
  
"additionalProperties": {
  
  
  
"dataset": "string",
  
  
  
"nextAttemptAt": "string",
  
  
  
"status": "string"
  
  
}
  
},
  
"nextRetryAt": "string",
  
"outcome": "subject_not_found",
  
"profile": {
  
  
"id": "string",
  
  
"kind": "string",
  
  
"name": "string"
  
},
  
"recoveryRound": 0,
  
"status": "string"
}

Playground​

Authorization
Headers
Body

Samples​

Consultar um enriquecimento​

GET
/api/v3/enrichments/{id}

A raiz do enriquecimento: status, resultado e o estado de cada módulo. Enquanto o status não é terminal, a resposta traz Retry-After. Use include para trazer os dados dos módulos já concluídos em data.

Authorizations​

bearerAuth

Token de acesso obtido em POST /api/v1/authentication. Veja Autenticação.

Type
HTTP (bearer)

Parameters​

Query Parameters

include

data inclui os dados de todos os módulos concluídos; uma lista separada por vírgulas (ex.: profile,finance) inclui só esses módulos.

Type
string

Responses​

O enriquecimento.

application/json
JSON
{
  
"completedAt": "string",
  
"createdAt": "string",
  
"data": {
  
  
"additionalProperties": "string"
  
},
  
"deadline": "string",
  
"document": "string",
  
"entity": "string",
  
"failureReason": "string",
  
"id": "enr_0199a0b2-7c1e-7d4a-9f0e-3b1c2d4e5f60",
  
"metadata": {
  
  
"additionalProperties": "string"
  
},
  
"modules": {
  
  
"additionalProperties": {
  
  
  
"dataset": "string",
  
  
  
"nextAttemptAt": "string",
  
  
  
"status": "string"
  
  
}
  
},
  
"nextRetryAt": "string",
  
"outcome": "subject_not_found",
  
"profile": {
  
  
"id": "string",
  
  
"kind": "string",
  
  
"name": "string"
  
},
  
"recoveryRound": 0,
  
"status": "string"
}

Playground​

Authorization
Variables
Key
Value

Samples​

Consultar os dados de um módulo​

GET
/api/v3/enrichments/{id}/modules/{module}

O data.{módulo} de um módulo concluído, no formato publicado pelo dataset. O formato de cada dataset está em Datasets.

Authorizations​

bearerAuth

Token de acesso obtido em POST /api/v1/authentication. Veja Autenticação.

Type
HTTP (bearer)

Responses​

Os dados do módulo.

application/json
JSON
{
  
"additionalProperties": "string"
}

Playground​

Authorization

Samples​

Perfis​

Perfis disponíveis para o workspace e o dataset que cada módulo usa.

Operations​

GET/api/v3/profilesGET/api/v3/profiles/{id}

Listar perfis​

GET
/api/v3/profiles

Os perfis ativos do seu workspace, de todos os tipos. O campo profile.kind diz o tipo de cada um: um enriquecimento só roda perfis enrichment. Use ?kind=enrichment para listar só os que servem em POST /api/v3/enrichments. Cada item tem o mesmo formato de GET /api/v3/profiles/{id}: o perfil, a entidade que ele atende e o dataset de cada módulo. A lista não é paginada.

Authorizations​

bearerAuth

Token de acesso obtido em POST /api/v1/authentication. Veja Autenticação.

Type
HTTP (bearer)

Parameters​

Query Parameters

kind

Só perfis deste tipo: enrichment ou verification. Sem o parâmetro, lista todos.

Type
string
Valid values
"enrichment""verification"

Responses​

Os perfis do workspace.

application/json
JSON
{
  
"items": [
  
  
{
  
  
  
"entity": "string",
  
  
  
"modules": {
  
  
  
  
"additionalProperties": {
  
  
  
  
  
"dataset": "string"
  
  
  
  
}
  
  
  
},
  
  
  
"profile": {
  
  
  
  
"id": "string",
  
  
  
  
"kind": "string",
  
  
  
  
"name": "string"
  
  
  
}
  
  
}
  
]
}

Playground​

Authorization
Variables
Key
Value

Samples​

Consultar um perfil​

GET
/api/v3/profiles/{id}

O perfil (com o tipo em profile.kind), a entidade que ele atende (person para CPF, company para CNPJ) e, em modules, o dataset que cada módulo usa, no mesmo formato de modules na resposta do enriquecimento. Veja o formato de cada dataset em Datasets.

Authorizations​

bearerAuth

Token de acesso obtido em POST /api/v1/authentication. Veja Autenticação.

Type
HTTP (bearer)

Responses​

O perfil.

application/json
JSON
{
  
"entity": "string",
  
"modules": {
  
  
"additionalProperties": {
  
  
  
"dataset": "string"
  
  
}
  
},
  
"profile": {
  
  
"id": "string",
  
  
"kind": "string",
  
  
"name": "string"
  
}
}

Playground​

Authorization

Samples​

Powered by VitePress OpenAPI