Migrar da API de KYC antiga para a /kyc/v1

A API antiga de KYC (POST /customer/v1/kyc/create) não tem camada de compatibilidade na Zabit v3. Na virada do seu workspace para o v3, a troca de rota e de chave é um gesto só — não há um período em que as duas convivem. Este guia é o mapa dessa troca.

Contrato de referência: a API pública de KYC (/kyc/v1, M2M) e a seção Chaves de API do app, onde você gera a chave (sessão humana).

1. Para quem é e o que muda

	API antiga	/kyc/v1
Rota para abrir KYC	POST /customer/v1/kyc/create	POST /kyc/v1/dossiers
Corpo	{ "document": "...", "documentType": "CPF|CNPJ" }	{ "document": "...", "subtype": "kyc", "name"?, "profile_code"?, "reporting_entity_id"? } — sem documentType: PF/PJ é detectado pela quantidade de dígitos (11 = CPF, 14 = CNPJ)
Resposta de abertura	201 síncrono, {"_id": "..."}	202 assíncrono, o dossiê inteiro (status: "processing")
Como chega o resultado	na própria resposta	GET /kyc/v1/dossiers/{id} ou webhook onboarding.kyc.completed
Credencial	chave da API antiga	chave nova, gerada por você na tela do workspace

O corpo ganhou subtype no lugar de documentType porque o "tipo de KY" do workspace (cliente, colaborador, parceiro, fornecedor, …) é configurável — não é mais um enum fixo de quatro valores. Se o seu workspace só usa o tipo padrão, informe "subtype": "kyc" (é o default) ou omita o campo.

2. A chave antiga não migra

A credencial da API antiga não é copiada para o v3 — não existe porque o valor de uma chave, no v3, nunca é recuperável depois da criação (só o hash é guardado). Não há "converter" nem "reativar" a chave velha. Por isso a troca de chave e de rota acontece no mesmo gesto: quando você passa a chamar /kyc/v1 com a chave nova, a chamada antiga já deve estar desligada do seu lado.

3. Teste antes no ambiente de desenvolvimento

Antes da virada, gere uma chave e faça as primeiras chamadas no ambiente de desenvolvimento (prod), não em produção:

• Endereço (placeholder): https://<host-do-ambiente-de-desenvolvimento>
• Use um workspace de teste, separado do seu workspace de produção.
• Com o bureau em modo de teste (fixture), abrir um dossiê não gera custo real e os códigos de erro são os mesmos de produção — é o lugar certo para validar o parsing da resposta e do webhook antes do dia da virada.

4. Gere a chave nova

Na tela Chaves de API · KYC do seu workspace:

1. Dê um nome para a chave (ex.: integracao-app-cadastro — ajuda a identificar qual sistema a usa quando for revogar).
2. Defina o limite diário dessa chave. É obrigatório: uma chave sem limite diário configurado não abre dossiê (403 quota_not_configured) — não existe "chave sem limite" por omissão.
3. Copie o valor agora. É a única vez que ele aparece — depois de fechar o diálogo, nem você nem o suporte Zabit conseguem ver o valor de novo. Perdeu? Revogue a chave e gere outra.
4. O escopo da chave nasce recortado pelas rotas do plano de API do seu workspace (abrir, consultar e listar dossiê). Se o seu plano excluir alguma rota, a chave nasce sem ela — a própria tela mostra quais rotas estão incluídas.

Envie a chave no cabeçalho x-api-key em toda chamada a /kyc/v1/*.

5. Troque a chamada

Antes (API antiga):

curl -sS -X POST https://<host-antigo>/customer/v1/kyc/create \
  -H "x-api-key: <chave-antiga>" \
  -H "content-type: application/json" \
  -d '{"document": "12345678900", "documentType": "CPF"}'
# 201 { "_id": "5f2e1a..." }

Depois (/kyc/v1):

curl -sS -X POST https://<host>/kyc/v1/dossiers \
  -H "x-api-key: <chave-nova>" \
  -H "content-type: application/json" \
  -d '{"document": "12345678900"}'
# 202 { "id": "c9166a7a-...", "document_type": "PF", "subtype": "kyc", "status": "processing", ... }

Mapeamento campo a campo do corpo:

Campo antigo	Campo novo	Nota
document	document	só os dígitos contam; formatação é ignorada
documentType	—	removido; PF/PJ é detectado pela quantidade de dígitos
—	subtype	opcional, default kyc — o tipo de KY do seu workspace
—	name	opcional; se ausente, o bureau preenche
—	profile_code	opcional; perfil de consulta (quais dados a consulta pede — e quanto custa). Ausente = o perfil default do workspace
—	reporting_entity_id	opcional; a entidade obrigada dona do dossiê, se o seu workspace tiver mais de uma

origin não é um campo do corpo — a borda carimba a origem como api automaticamente, e um valor enviado pelo chamador é ignorado.

Repetir o POST abre outro dossiê. A rota não é idempotente: duas chamadas com o mesmo documento abrem duas fotos, com id diferentes. Se o seu sistema reenvia por timeout, confira antes se já existe um dossiê recente para aquele documento (seção 6) em vez de reenviar direto.

6. Receba o resultado

A abertura responde 202 com o dossiê em status: "processing" — a consulta ao bureau roda fora do request. Duas formas de saber quando terminou:

• Polling — GET /kyc/v1/dossiers/{id} até status virar vigente (concluído) ou error (falha terminal). Funciona, mas é o modo caro de esperar.
• Webhook (recomendado) — assine o evento onboarding.kyc.completed e receba o resultado sem ficar consultando. Veja Receber webhooks da Zabit para o contrato do lado do receptor (assinatura, retry, idempotência).

Para listar o que sua chave já abriu: GET /kyc/v1/dossiers com limit (até 200) e offset para paginar, subtype para recortar por população, q para buscar por documento ou nome, e created_after/created_before (data-hora ISO 8601) para recortar pela data de abertura do dossiê. Listar e consultar não consomem cota — só abrir dossiê consome.

Checar KYC vigente antes de criar

Antes de abrir um dossiê (que é uma consulta paga), confira se o documento já tem um KYC válido com POST /kyc/v1/current-dossier/lookup. O documento vai no corpo, nunca na URL, e a chamada não consome cota:

curl -s -X POST "https://api.v3.zabit.com.br/kyc/v1/current-dossier/lookup" \
  -H "x-api-key: zbt_SUA_CHAVE" -H "content-type: application/json" \
  -d '{"document": "12345678909", "subtype": "kyc"}'

O campo situacao diz o que fazer: valido (reaproveite o dossier_id devolvido), vencido (abra um novo), em_andamento (aguarde), nenhum (abra o primeiro) ou erro. Detalhes na referência.

7. Erros e limites

HTTP	code	O que significa	O que fazer
401	unauthorized	x-api-key ausente, desconhecida ou token de serviço inválido	confira o cabeçalho e a chave
403	forbidden	chave revogada, desabilitada, ou sem o escopo necessário	gere outra chave, ou confira o escopo
403	quota_not_configured	a chave não tem limite diário configurado	configure o limite diário na chave (seção 4)
403	route_not_in_plan	o plano de API do seu workspace não inclui esta rota	fale com o administrador do workspace ou com o suporte Zabit
422	invalid_params / invalid_params	documento malformado, ou parâmetro de paginação fora de faixa	confira o corpo/query enviado
429	quota_exceeded	a chave estourou o limite diário dela	volta a valer no dia seguinte (UTC)
429	kyc_creation_limit_reached	o workspace estourou o limite de criação — diário ou mensal, somando tela, importação e esta API	details.periodo diz qual dos dois; details.volta_a_valer_em diz quando; um administrador pode ajustar o limite em Onboarding › Limites de criação
503	unavailable	indisponibilidade transitória	tente de novo com backoff

Duas notas de custo: (1) quando o freio do workspace recusa (429 kyc_creation_limit_reached), a unidade de cota da chave já foi consumida — não há estorno; (2) revogar ou desabilitar uma chave tem efeito em até 300 segundos (5 minutos) — é o tempo de cache do token de serviço, não um atraso de propagação de dados.

8. No dia da virada do seu workspace

• Chave nova gerada e testada no ambiente de desenvolvimento (seção 3).
• Chamada trocada: POST /customer/v1/kyc/create → POST /kyc/v1/dossiers, corpo no formato novo (seção 5), publicada no seu sistema.
• Webhook onboarding.kyc.completed cadastrado (ou o polling por GET implementado).
• Limites de criação conferidos em Onboarding › Limites de criação — o teto do workspace soma tela, importação e API.
• A chamada para a API antiga desligada do seu lado — a partir da virada, o legado deixa de atender o seu workspace.

9. Perguntas frequentes

E o documentType? Não existe mais. PF (CPF, 11 dígitos) e PJ (CNPJ, 14 dígitos) são detectados pela quantidade de dígitos do document enviado.

Posso ter uma chave por sistema integrador? Sim, até o limite de chaves ativas do plano do seu workspace (a tela mostra quantas estão em uso).

Por que 202 e não 201? Porque abrir um dossiê dispara uma consulta paga ao bureau, que roda fora do request. 201 síncrono exigiria o chamador esperar a consulta terminar; 202 devolve a foto em processing na hora e o resultado chega por GET ou webhook.

Onde vejo o que foi criado pela API, separado do que veio da tela? GET /kyc/v1/dossiers lista os dossiês da sua chave; internamente cada dossiê guarda origin: "api" (a tela grava "ui", a importação em lote grava "import").