Pular para o conteúdo principal

Início rápido

Em cinco passos você gera uma chave, confere que a API responde, abre um dossiê de KYC, lê o resultado e lista o que já foi aberto. Os exemplos usam o ambiente de produção (prod).

ItemValor
Base da API (prod)https://api.v3.zabit.com.br
Autenticaçãoheader x-api-key com a sua chave
FormatoJSON (content-type: application/json)
Se a API não responder da sua rede

Alguns ambientes só aceitam chamadas de endereços IP liberados. Se healthz não responde da sua rede (ou o playground do site falha antes de chegar à API), peça a liberação do IP de saída da sua rede ao seu contato na Zabit. Isso vale para curl, para o seu código e para o navegador.

Prefira testar sem sair do site

Cada endpoint da Referência tem um playground: informe a chave na aba Authorization e envie a chamada direto do navegador. A chave fica só na sessão da aba (sessionStorage) e só é enviada ao host da API.

1. Gere a sua chave​

A chave é criada por você, não pelo suporte, na tela de Chaves de API do workspace, no app da Zabit (prod).

  • O valor completo (começa com zbt_) aparece uma única vez, na criação. Copie e guarde num cofre de segredos — não dá para recuperá-lo depois; se perder, gere outra.
  • Para abrir dossiês a chave precisa ter um teto diário configurado. Sem teto, a abertura é recusada (403 quota_not_configured) — veja Autenticação e chaves.
  • O plano de API do workspace define quais rotas a chave alcança.

Nos exemplos abaixo, zbt_SUA_CHAVE é um marcador: troque pelo valor que você copiou.

export ZABIT_API=https://api.v3.zabit.com.br
export ZABIT_KEY=zbt_SUA_CHAVE

2. Confira que a API responde​

GET /kyc/v1/healthz não exige chave:

curl -s "$ZABIT_API/kyc/v1/healthz"
{"status":"ok","service":"kyc-public"}

Agora confirme que a chave é aceita listando dossiês (leitura, não consome cota):

curl -s "$ZABIT_API/kyc/v1/dossiers?limit=1" -H "x-api-key: $ZABIT_KEY"

200 com items e page (total, limit, offset) = chave válida. 401 = chave ausente ou desconhecida (veja Erros).

3. Abra um dossiê de KYC​

curl -s -X POST "$ZABIT_API/kyc/v1/dossiers" \
  -H "x-api-key: $ZABIT_KEY" \
  -H "content-type: application/json" \
  -d '{"document": "12345678909", "name": "Maria Exemplo"}'
  • document: CPF (11 dígitos) ou CNPJ (14). A formatação é ignorada.
  • subtype (opcional, padrão kyc): o tipo de KY do seu workspace.
  • name (opcional): o bureau preenche se você omitir.

A resposta é 202 Accepted, não 201: a consulta ao bureau é assíncrona. O corpo traz o dossiê em processing:

{
  "id": "0b6f1c1e-3f6e-4a53-9f43-2c1f1d5f9a10",
  "document_type": "PF",
  "subtype": "kyc",
  "status": "processing",
  "origin": "api",
  "created_at": "2026-10-05T12:00:00Z"
}

Guarde o id. Ele identifica essa consulta (uma "foto"), não a pessoa: consultar o mesmo CPF de novo gera outro id.

Cada abertura consome 1 da cota diária da chave

Abrir dossiê dispara consulta paga de bureau. Repetir o POST abre outro dossiê e consome outra unidade de cota — a menos que você envie o header Idempotency-Key: com ele, repetir o mesmo pedido devolve o dossiê já aberto, sem cota extra. Veja Idempotência. Ler e listar não consomem cota.

Quer saber antes se já existe um KYC válido para o documento? Use POST /kyc/v1/current-dossier/lookup — é leitura, não consome cota:

curl -s -X POST "$ZABIT_API/kyc/v1/current-dossier/lookup" \
  -H "x-api-key: $ZABIT_KEY" -H "content-type: application/json" \
  -d '{"document": "12345678909"}'

situacao vem como nenhum, valido, vencido, em_andamento ou erro.

4. Consulte o resultado​

curl -s "$ZABIT_API/kyc/v1/dossiers/0b6f1c1e-3f6e-4a53-9f43-2c1f1d5f9a10" \
  -H "x-api-key: $ZABIT_KEY"

O campo status começa em processing (e pode passar por em_reconsulta, numa nova consulta) e termina em vigente (coleta concluída; o detalhe traz risk_level e as seções) ou error (falha terminal; veja error_category e error_code). Enquanto estiver em andamento, repita a consulta com intervalo crescente — ou, melhor, receba o evento onboarding.kyc.completed por webhook em vez de fazer polling.

404 significa que o dossiê não existe ou não pertence ao workspace da chave (os dois casos são indistinguíveis de propósito).

5. Liste os dossiês​

curl -s "$ZABIT_API/kyc/v1/dossiers?limit=20&offset=0" -H "x-api-key: $ZABIT_KEY"

Filtros: subtype, q (documento ou nome), report_id, created_after, created_before. Detalhes em Paginação.

Próximos passos​