Como integrar uma API de KYC: do sandbox à produção

Integrar uma API de KYC são sete etapas: obter credencial de sandbox, modelar o fluxo, criar a verificação, capturar documento e selfie no cliente, tratar o retorno assíncrono, mapear os estados e homologar antes de virar a chave para produção.

O que atrasa uma integração não é o código da chamada. É a decisão de arquitetura tomada no segundo dia e descoberta no vigésimo: onde o cadastro fica travado enquanto a verificação corre, quem é o dono do identificador, o que acontece se o webhook chegar duas vezes.

Os exemplos deste guia usam a API REST da Shiel ID, descrita na documentação da API da Shiel ID. Em outro fornecedor, os nomes de endpoint e campo mudam, mas as decisões de arquitetura são as mesmas.

Etapa 1: credencial, ambiente de teste e separação de segredos

Peça duas credenciais desde o início, sandbox e produção, e trate as duas como segredo de infraestrutura, nunca como variável no repositório. O sandbox precisa produzir os três desfechos com dados sintéticos: aprovado, reprovado e pendente. Se ele só devolve aprovado, você tem demonstração, não sandbox.

Confirme também três coisas antes de escrever qualquer linha: método de autenticação, limite de requisições por minuto e política de retentativa aceita pelo fornecedor. Na API da Shiel ID, a autenticação é HTTP Basic: usuário e senha codificados em base64 no cabeçalho Authorization.

Etapa 2: modelar o fluxo antes de chamar qualquer endpoint

Desenhe o estado do cadastro no seu banco antes de desenhar a chamada. Uma verificação é uma máquina de estados que vive fora do seu processo, e o cadastro precisa refletir isso sem depender de resposta síncrona.

O modelo mínimo tem três campos próprios: status interno do cadastro, identificador externo da verificação e carimbo da última atualização recebida. Guarde também a versão da política aplicada, porque quando a regra mudar você vai precisar saber sob qual critério cada cadastro antigo passou.

Decida aqui o que fazer com o usuário enquanto a verificação corre. Bloquear tudo, liberar leitura e travar transação ou liberar com limite reduzido são escolhas de produto, e mudar isso depois custa refatoração.

Etapa 3: criar a verificação

Na API da Shiel ID, a primeira chamada é POST /getNewHashKYC, que cria a sessão de onboarding e devolve uma hash. Os parâmetros vão na query string, e os módulos e regras da jornada vêm da customização feita no dashboard. Para pessoa física, o CPF esperado é obrigatório:

POST https://api.shielid.com/api/getNewHashKYC?userId=<id do cadastro no seu sistema>&personType=pf&documentType=brazilian&documentExpected=<CPF esperado>&returnUrl=<endereço de retorno após o KYC>
Authorization: Basic <base64 de usuario:senha>

Um trecho da resposta, com os campos que a integração usa:

{
  "hash": "<hash da sessão>",
  "userId": "<id do cadastro no seu sistema>",
  "type": "kyc",
  "status": "created",
  "personType": "pf",
  "url": "<link da jornada hospedada em shielid.com/kyc>"
}

A resposta completa traz ainda success, hashChecker, steps, currentStep, checkDocument, validateData, documentExpected e returnUrl.

Dois cuidados. Envie em userId o seu identificador de cadastro, com até 48 caracteres, porque é ele que amarra o retorno ao registro certo quando o webhook chegar; se ele não for enviado, a API gera um, e você precisa guardar o valor devolvido. E grave a hash como identificador externo da verificação, sem reaproveitar a url de uma sessão em outro cadastro. Para empresa, personType=pj abre a jornada em que os documentos da empresa são enviados para extrair os sócios, e cada sócio faz o próprio KYC.

Etapa 4: captura de documento e selfie no cliente

A captura acontece no navegador ou no aplicativo, com SDK do fornecedor ou componente próprio. Na Shiel ID, ela acontece na jornada hospedada aberta pela url da sessão, e ao final o usuário volta para o endereço informado em returnUrl. Se o SDK já envia a mídia direto, evite a cópia intermediária no seu servidor: cada cópia é mais um lugar onde dado biométrico precisa de base legal, retenção e descarte definidos.

Três decisões técnicas aparecem aqui com frequência:

• Permissão de câmera negada, que precisa de caminho alternativo previsto e não de uma tela morta.
• Qualidade mínima de imagem, validada no cliente para reduzir chamada descartada.
• Orientação do documento e leitura de frente e verso, que muda conforme o tipo aceito.

A captura é onde o usuário percebe a fricção. Ela é prova de que a validação está acontecendo, então o trabalho não é removê-la, é torná-la previsível: instrução clara, feedback imediato, número de tentativas definido.

Etapa 5: tratamento assíncrono e webhook

Verificação é assíncrona por natureza: documento precisa ser lido, biometria comparada, e parte dos casos vai para análise humana. Nunca trave uma requisição do seu front esperando o desfecho.

Na Shiel ID, a URL que recebe o retorno é registrada em POST /setWebhook, e URLs adicionais podem ser incluídas com /addOptionalWebhook. O webhook informa o status da hash: created, started, approved, rejected ou pending. No status approved, o payload traz type, document, com o tipo do documento (como CNH), o resultado de spoofing e as imagens de frente e verso, e face, com o resultado de spoofing e as imagens das capturas.

Quatro regras que evitam quase todo incidente de produção nessa camada:

1. Não libere o cadastro só com base no corpo recebido. Endpoint público sem verificação de origem é porta aberta para aprovação forjada: antes de liberar, confira o status da hash em GET /getHashData.
2. Trate o recebimento como idempotente. O mesmo evento pode chegar duas vezes, e o segundo processamento não pode reverter nem duplicar nada.
3. Ignore eventos fora de ordem usando o carimbo de tempo. Um evento antigo não pode sobrescrever um estado mais novo.
4. Mantenha uma rotina de reconciliação que consulta por identificador os cadastros parados há mais tempo que o esperado. Webhook se perde. Na Shiel ID, essa consulta é GET /getHashData, que devolve currentStep, status, score e os carimbos createdTimestamp e finishedTimestamp.

Etapa 6: mapear os estados de retorno

O erro mais comum de integração é reduzir tudo a aprovado e reprovado. Na API da Shiel ID, a hash pode estar em cinco status, e cada um pede uma ação no seu sistema.

• created. O que significa: Sessão criada, jornada ainda não iniciada pelo usuário. Ação no seu sistema: Manter cadastro travado e exibir o link da jornada.
• started. O que significa: Jornada iniciada pelo usuário. Ação no seu sistema: Manter travado, sem novo pedido ao usuário.
• pending. O que significa: Verificação ainda sem desfecho final. Ação no seu sistema: Manter travado, com prazo definido na sua política e comunicação ao usuário.
• approved. O que significa: Critérios atendidos. Ação no seu sistema: Liberar conforme a política de produto e registrar a versão da política.
• rejected. O que significa: Critério não atendido. Ação no seu sistema: Negar com motivo genérico ao usuário e motivo detalhado no log interno.

Falha técnica de chamada e sessão abandonada não aparecem como status e precisam de regra do seu lado: retentativa com recuo exponencial e alerta para erro de chamada, sem penalizar o usuário, e nova sessão para cadastro parado em created ou started além do prazo, sem duplicar o cadastro no seu sistema.

Registre o motivo do desfecho, não só o desfecho. É esse registro que permite demonstrar depois como o cadastro foi validado.

Etapa 7: homologação e virada para produção

Antes de virar a chave, rode um roteiro fechado: aprovação limpa, reprovação por divergência, caso pendente, sessão abandonada, webhook duplicado, webhook fora de ordem e indisponibilidade do fornecedor.

Defina o comportamento de degradação. Se a API não responder por dez minutos, o cadastro entra em fila ou é negado? Essa é uma decisão de risco, não de engenharia, e precisa estar escrita antes do primeiro incidente.

E planeje a etapa que quase ninguém planeja: chamar a verificação de novo depois. Troca de titularidade, mudança de dispositivo, retorno de conta inativa e operação atípica pedem reverificação. Se o seu modelo guarda uma única verificação por cadastro, refazer isso mais tarde vira migração. Guarde verificações como histórico desde o primeiro dia. Na API da Shiel ID, esse retorno pode usar POST /getNewTransactionKYC, que cria uma validação facial associada ao último KYC aprovado do usuário. As etapas que a Shiel ID opera estão nas soluções da Shiel ID, com detalhamento em prova de vida por API e em webhook de verificação.

O que fazer agora

1. Peça ao fornecedor as credenciais de sandbox e confirme por escrito que o ambiente produz aprovado, reprovado e pendente com dados sintéticos.
2. Modele no seu banco os três campos mínimos (status interno, identificador externo e carimbo da última atualização) e a versão da política aplicada.
3. Implemente o webhook com verificação de origem, conferência do status por consulta e idempotência antes de implementar a tela de captura.
4. Escreva o roteiro de homologação com os sete casos citados e rode todos antes da virada.
5. Defina e documente o comportamento de degradação para indisponibilidade do fornecedor.

Perguntas frequentes

Quanto tempo leva para integrar uma API de KYC? A chamada básica sai em poucos dias. O prazo é definido pelo tratamento assíncrono, pelo mapeamento de estados e pela homologação. Tratar webhook e fila de exceção desde o início encurta o caminho até produção.

Preciso guardar a imagem do documento e a selfie? Guarde apenas o que tiver base legal, prazo de retenção e rotina de descarte definidos. Sempre que o SDK do fornecedor envia a mídia diretamente, evitar a cópia intermediária no seu servidor reduz superfície de exposição.

O que fazer quando o webhook não chega? Mantenha uma rotina de reconciliação que consulta o estado por identificador para cadastros parados além do prazo esperado. Webhook é o caminho normal, consulta por identificador é a rede de segurança. Na Shiel ID, essa consulta é GET /getHashData.

Posso aprovar o cadastro enquanto a verificação ainda está pendente? Pode, desde que seja uma decisão explícita de produto com limite associado, e não um efeito colateral do código. Deixe registrado qual limite vale para cadastro pendente e o que muda quando o desfecho chega.

Os nomes de campo deste artigo são os reais? Sim, para a API da Shiel ID: os exemplos seguem a documentação pública da API. Em outro fornecedor, os nomes de endpoint, campo e status mudam e estão na documentação dele.

Para avaliar como isso se aplica à sua operação, fale com o time comercial da Shiel ID.