Widget ou API pura: escolhendo o modo de integração de KYC

Toda plataforma de verificação de identidade oferece, com nomes variados, os mesmos dois caminhos de integração: um widget pronto, que a sua aplicação embute e que já traz câmera, captura de documento e prova de vida resolvidas, ou a API pura, em que o seu time constrói a interface e chama os endpoints diretamente. A escolha parece estética, mas define quem escreve o código mais difícil do fluxo, onde vivem as credenciais e quem absorve cada mudança futura.

Este artigo compara os dois modos pelos critérios que importam em produção: esforço real de implementação, segurança de credenciais, política de conteúdo da página e manutenção ao longo dos anos. A resposta honesta, adiantada: não existe vencedor universal, existe adequação ao seu time e ao seu produto.

O que cada modo entrega de fato

O widget resolve o problema mais traiçoeiro da verificação remota: a captura. Câmera em navegador é um território de permissões negadas, aparelhos sem suporte, enquadramento ruim e usuários que fotografam o documento fora de foco. Um widget maduro carrega o tratamento acumulado desses casos: valida se existe um rosto real e enquadrado antes de capturar, orienta o usuário em linguagem simples e conduz a recaptura quando um módulo reprova a imagem. Construir tudo isso do zero é perfeitamente possível, e custa semanas de trabalho de interface somadas a um longo período de ajuste fino com usuários reais.

A API pura entrega o contrário: controle total. A interface é sua, o texto é seu, a jornada é sua. Para produtos com design system rígido, aplicativos nativos com bibliotecas próprias de câmera ou fluxos em que a verificação é um passo discreto dentro de uma jornada maior, chamar a API diretamente evita a costura visual de um componente de terceiro dentro da sua tela.

Segurança: onde vive cada credencial

A diferença mais importante entre os dois modos raramente aparece em demonstração comercial: é o desenho de credenciais. O ASVS (Application Security Verification Standard), padrão de verificação de segurança de aplicações mantido pela OWASP, é direto no princípio: segredo de longa duração não pertence ao lado cliente. Navegador é ambiente hostil por definição, e qualquer valor entregue a ele deve ser tratado como público.

Numa integração bem desenhada, os dois modos respeitam o princípio de formas diferentes:

• na API pura, a chave secreta vive apenas no seu servidor, e toda chamada que decide alguma coisa parte dele; o navegador conversa com o seu backend, nunca diretamente com a plataforma de verificação;
• no widget, o seu servidor cria uma sessão de verificação e recebe uma credencial de curta duração, restrita àquela sessão, e é só isso que chega ao navegador; se vazar, expira em minutos e não abre nada além da própria sessão.

Isso vale como critério de eliminação de fornecedor: se a documentação do widget manda colar uma chave de API permanente no HTML da página, o desenho está errado na raiz. Para tokens de sessão no formato JWT, a RFC 8725 do IETF, o registro de boas práticas atuais de JSON Web Token, consolida as regras que evitam os erros clássicos: expiração curta, audiência explícita e validação estrita de algoritmo. Na UNIFOKAL, por exemplo, o widget de uma linha funciona nesse modelo, com a sessão criada pelo servidor do cliente e apenas o segredo de curta duração no navegador; o custo admitido do modo widget é executar um script nosso dentro da sua página, e é para governar esse tipo de custo que existe a política da seção seguinte.

CSP: o custo de embutir script de terceiro

Embutir um widget é executar código de terceiro no seu domínio, e a ferramenta para governar isso tem especificação formal: a Content Security Policy (CSP), especificada pelo W3C, permite declarar de quais origens a página aceita carregar e executar script, para onde aceita abrir conexões e o que pode usar a câmera. Uma integração de widget séria documenta as diretivas exatas de que precisa, e nada além delas.

O modo API pura não escapa da CSP, mas muda de lado: sem script de terceiro, a política da página fica mais curta, e o tráfego sensível se concentra entre o seu backend e a plataforma. O que não muda em nenhum dos dois modos: a decisão da verificação chega por webhook assinado no seu servidor, nunca pelo navegador, porque resposta que passa pelo cliente é resposta que o cliente pode forjar.

Manutenção: quem absorve a mudança

O custo dominante de uma integração raramente é escrevê-la: é mantê-la viva enquanto tudo ao redor muda. Os dois modos distribuem esse custo de formas opostas.

No widget, as atualizações do fornecedor chegam sem deploy seu: um tipo novo de documento, uma melhoria de captura, um ajuste de acessibilidade aparecem no fluxo sem que o seu time toque em código. O risco simétrico é justamente esse: mudança visual ou de comportamento que chega sem você pedir. Avalie a política de versionamento do fornecedor, se existe canal de aviso prévio e se é possível fixar uma versão durante períodos críticos.

Na API pura, nada muda sem você mudar, o que é uma forma de estabilidade e uma forma de custo: cada melhoria do fornecedor exige seu desenvolvimento e seu deploy. Um documento novo suportado pela plataforma é, do seu lado, um projeto de interface, não uma atualização automática.

Como decidir

• Time pequeno, prazo curto, produto web: widget. O tempo economizado em captura e recaptura paga com folga a menor flexibilidade visual.
• Aplicativo nativo com biblioteca própria de câmera e design system forte: API pura. O controle vale o custo, e a captura nativa tende a superar a de navegador.
• Os dois públicos ao mesmo tempo: os modos coexistem sobre a mesma conta, widget no funil web e API no aplicativo, desde que a plataforma trate os dois como o mesmo fluxo de decisão.
• Em qualquer cenário: homologue primeiro em sandbox e trate a idempotência das chamadas e dos webhooks desde o primeiro dia, porque nenhum desses dois pontos depende do modo escolhido.

Nenhum dos modos dispensa a espinha dorsal servidor a servidor: sessão criada no backend, decisão recebida por webhook, reconciliação periódica. O modo de integração define a experiência de captura; o contrato de segurança por baixo é o mesmo.

Fontes citadas

• Application Security Verification Standard (ASVS), projeto da OWASP Foundation: owasp.org
• Content Security Policy Level 3, especificação do W3C: w3.org
• RFC 8725, JSON Web Token Best Current Practices, do IETF: rfc-editor.org