Checklist de homologação de um fluxo de KYC antes do go-live

Existe uma distância grande entre "a integração funciona" e "a integração está pronta". A primeira frase costuma significar que o caminho feliz passou: um cadastro de teste entrou, a decisão voltou, o sistema gravou. A segunda significa que os caminhos infelizes também foram exercitados, porque é neles que o dinheiro e a reputação se perdem: o webhook que chega duas vezes, o upload que cai no meio, o usuário que envia a foto errada, o provedor de dados que responde fora do ar.

Homologar um fluxo de conheça seu cliente, o KYC (do inglês know your customer), é percorrer essa lista de caminhos infelizes de forma deliberada, antes que o tráfego real os percorra por acidente. Este artigo organiza a homologação em seis blocos, cada um com os testes que separam a demo do sistema de produção. Para quem está chegando ao assunto agora, o conceito geral está no artigo sobre o que é KYC; aqui o foco é a véspera do go-live.

Todos os desfechos, não só a aprovação

Uma verificação de identidade tem mais desfechos do que aprovado e reprovado. Existe a revisão manual, existe o pedido de recaptura de um documento ilegível, existe a sessão abandonada no meio. O sistema integrador precisa ter comportamento definido e testado para cada um: o que a interface mostra, o que o suporte enxerga, o que acontece com o cadastro que ficou pendente por horas.

O ambiente de teste do fornecedor precisa permitir provocar cada desfecho de forma determinística, sem depender de sorte. Na UNIFOKAL, por exemplo, o sandbox produz decisões determinísticas a partir do dado de entrada, justamente para que o integrador consiga roteirizar aprovação, recusa e revisão em teste automatizado. O uso correto desse ambiente, e o que ele consegue ou não simular, está detalhado no artigo sobre sandbox antes de produção.

Webhooks: assinatura, repetição e ordem

O canal que entrega a decisão é assíncrono, pelas razões de arquitetura do artigo sobre latência de verificação, e isso cria três testes obrigatórios. Primeiro, a assinatura: o receptor deve validar o código de autenticação da mensagem, tipicamente um HMAC como o definido na RFC 2104, e o teste de homologação inclui enviar um payload com assinatura inválida e comprovar que ele é rejeitado. Segundo, a repetição: entrega de webhook tem reenvio automático, então o mesmo evento pode chegar mais de uma vez, e o consumidor precisa ser idempotente, processando a segunda chegada sem duplicar efeito. Terceiro, a ordem: eventos podem chegar fora de ordem, e o consumidor deve decidir pelo estado mais recente, não pelo último a chegar.

O teste que quase ninguém faz e todo mundo deveria: derrubar o endpoint receptor de propósito durante uma verificação e observar o comportamento de reentrega até a recuperação. O desenho completo do receptor está no artigo sobre webhooks seguros em KYC.

Upload de mídia: limites e quedas de rede

A captura de documento e selfie é a etapa com mais variação de ambiente: aparelho antigo, rede móvel instável, arquivo maior que o esperado. A homologação precisa exercitar os limites publicados pelo fornecedor: enviar um arquivo acima do tamanho máximo e conferir a recusa com mensagem tratável; deixar uma URL de upload expirar e conferir que o fluxo pede outra em vez de travar; interromper a conexão no meio do envio e conferir a retomada. O desenho de upload direto para armazenamento, com URL pré-assinada e limite imposto pelo servidor, está no artigo sobre upload seguro de mídia.

Recaptura: a rejeição técnica não é o fim

Foto tremida, documento cortado, reflexo em cima do dado importante: parte das capturas falha por qualidade, não por fraude, e o fluxo precisa devolver o usuário para uma segunda tentativa do módulo específico que falhou, sem refazer o processo inteiro. Os testes: provocar uma rejeição de qualidade e conferir que o pedido de recaptura chega com o motivo certo; conferir que somente o módulo rejeitado é refeito; conferir o teto de tentativas e o desfecho quando ele é atingido. A lógica desse circuito está no artigo sobre fluxo de recaptura em verificação.

Dados de teste: CPF real não entra em homologação

Homologação se faz com dado sintético, nunca com CPF, documento ou rosto de pessoa real, nem de funcionário. A Lei Geral de Proteção de Dados, a LGPD (Lei 13.709/2018), lista no artigo 6º, inciso III, o princípio da necessidade: tratamento limitado ao mínimo necessário para a finalidade. Testar software não exige dado pessoal verdadeiro, então usar dado verdadeiro em teste é tratamento sem necessidade, além de espalhar dado sensível por logs, gravações de tela e bases de homologação que raramente têm o mesmo controle do ambiente produtivo. O ambiente de teste do fornecedor deve aceitar identificadores fictícios; se não aceitar, isso é um achado da homologação.

O dia do corte

Com os blocos acima verdes, resta o plano do dia: monitoramento com alerta para taxa de erro e tempo de decisão, painel acompanhado nas primeiras horas, e um caminho de reversão ensaiado, o que inclui saber o que acontece com as verificações em andamento se a integração for desligada no meio. Vale escrever o critério de sucesso antes de ligar: qual taxa de conclusão do funil é esperada, qual taxa de recaptura é tolerável, quem decide a reversão. Sem critério prévio, qualquer número parece aceitável no entusiasmo do lançamento.

Um fluxo de KYC homologado assim não elimina surpresas, mas transforma a maioria delas em cenário já ensaiado. A diferença aparece na primeira madrugada difícil: quem testou o caminho infeliz executa um plano; quem testou só o caminho feliz improvisa. E o que a homologação não pegar por ser obrigação de processo, não de código, a fiscalização pega depois, como mostra o artigo sobre erros de KYC que reprovam em auditoria.

Fontes citadas

• RFC 2104, HMAC: Keyed-Hashing for Message Authentication, IETF: rfc-editor.org/rfc/rfc2104
• RFC 9110, HTTP Semantics, IETF, semântica de métodos e códigos de estado usada no desenho de reenvio e idempotência: rfc-editor.org/rfc/rfc9110
• Lei 13.709/2018 (LGPD), artigo 6º, inciso III, princípio da necessidade, disponível no portal do Planalto: planalto.gov.br