A Depuração de Integrações Didit: Erros Comuns e Estratégias (PT-PT)

Problemas de Chave API e AutenticaçãoGaranta que as suas chaves API estão corretamente configuradas e as variáveis de ambiente devidamente definidas, pois as falhas de autenticação são um obstáculo inicial comum para qualquer integração API.

Limite de Taxa e ThrottlingImplemente um tratamento robusto de limite de taxa com backoff exponencial e monitorize os cabeçalhos X-RateLimit para evitar interrupções de serviço e garantir a estabilidade da aplicação.

Gestão do Ciclo de Vida da SessãoCompreenda o ciclo de vida completo das sessões de verificação Didit, desde a criação e atualizações de estado até à recuperação da decisão, para acompanhar com precisão o progresso da verificação do utilizador.

Abordagem Didit Focada no ProgramadorA Didit oferece documentação abrangente, sandboxes instantâneas e APIs limpas, simplificando significativamente o processo de depuração e reduzindo a complexidade da integração para os programadores.

Integrar a verificação de identidade na sua aplicação é um passo crítico para a segurança e conformidade. No entanto, como qualquer sistema complexo, a integração com uma plataforma de identidade como a Didit pode apresentar desafios de depuração únicos. Este guia foi concebido para ajudar os programadores a identificar e resolver problemas comuns, garantindo um processo de integração suave e eficiente com os poderosos serviços de verificação de identidade da Didit.

Compreender a Autenticação e Configuração da API

Um dos pontos de partida mais frequentes para problemas de integração reside na autenticação e configuração da API. Chaves API mal configuradas, variáveis de ambiente incorretas ou restrições de acesso à rede podem levar a erros de autenticação frustrantes.

Problemas Comuns:

• Chave API Incorreta: Certifique-se de que a chave API utilizada nos seus pedidos corresponde à fornecida na sua Consola de Negócios Didit. Lembre-se de que as chaves API são sensíveis a maiúsculas e minúsculas.
• Problemas com Variáveis de Ambiente: Se estiver a armazenar a sua chave API numa variável de ambiente (por exemplo, DIDIT_API_KEY), verifique novamente se está corretamente carregada e acessível pela sua aplicação em tempo de execução.
• Permissões: Verifique se a chave API tem as permissões necessárias para as operações que está a tentar realizar. Algumas operações podem exigir âmbitos específicos.
• Restrições de Rede: Firewalls ou servidores proxy podem, por vezes, bloquear chamadas API de saída. Certifique-se de que o seu servidor tem acesso irrestrito aos endpoints da API da Didit.

Estratégias de Resolução de Problemas:

• Verificar Credenciais: A solução mais simples é muitas vezes a mais eficaz. Copie e cole a sua chave API diretamente da Consola de Negócios Didit para evitar erros de digitação.
• Utilize uma Ferramenta Como cURL ou Postman: Antes de integrar no seu código, teste a sua chave API com um comando cURL direto ou um pedido Postman para isolar problemas de autenticação de erros a nível da aplicação.
• Examinar Mensagens de Erro: A API da Didit fornece mensagens de erro claras. Uma resposta 401 Unauthorized ou 403 Forbidden geralmente aponta para problemas de autenticação ou permissão.
• Consultar a Documentação Didit: A Referência da API da Didit fornece informações detalhadas sobre métodos de autenticação e cabeçalhos esperados.

Gerir Limites de Taxa e Throttling da API

Para manter a estabilidade e o uso justo, a Didit, como a maioria dos fornecedores robustos de API, implementa limites de taxa. Não ter em conta estes limites pode levar a interrupções temporárias do serviço e erros 429 Too Many Requests.

Problemas Comuns:

• Pedidos em Excesso: Enviar um grande número de pedidos num curto período, especialmente para operações que consomem muitos recursos, como criar sessões ou recuperar decisões, pode rapidamente atingir os limites. Por exemplo, POST /v2/session/ tem um limite de 600 pedidos por minuto, enquanto GET /v2/session/<id>/decision/ está limitado a 100 pedidos por minuto para evitar polling excessivo.
• Ignorar Cabeçalhos de Limite de Taxa: Não monitorizar os cabeçalhos X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset pode levar a throttling inesperado.
• Falta de Backoff Exponencial: Sem uma estratégia de backoff exponencial, tentar novamente imediatamente após um erro 429 provavelmente resultará em falhas contínuas.

Estratégias de Resolução de Problemas:

• Monitorizar Cabeçalhos: Sempre analise e responda aos cabeçalhos de limite de taxa fornecidos nas respostas da API da Didit. Isso permite que a sua aplicação se auto-limite proactivamente.
• Implementar Backoff Exponencial: Quando receber uma resposta 429, espere um tempo crescente antes de tentar novamente o pedido. Um padrão comum é 5s → 10s → 20s → 40s.
• Operações em Lote: Sempre que possível, agrupe certas operações ou desenhe o seu fluxo de trabalho para reduzir a frequência das chamadas à API.
• Limitação de Taxa Distribuída: Se tiver várias instâncias da aplicação, considere um mecanismo centralizado de limitação de taxa para evitar exceder os limites globais de instâncias separadas.

Gerir Ciclos de Vida de Sessões de Verificação

O processo de verificação de identidade da Didit gira em torno de sessões. Compreender como criar, gerir e recuperar resultados destas sessões é fundamental. Os problemas surgem frequentemente de uma má compreensão dos estados da sessão ou de um tratamento inadequado dos fluxos de verificação assíncronos.

Problemas Comuns:

• Criação de Sessão Incorreta: Não fornecer todos os parâmetros necessários ao chamar didit_create_session ou usar um ID de fluxo de trabalho inválido pode impedir que uma sessão comece corretamente.
• Polling Demasiado Frequente: Chamar repetidamente didit_get_session_decision sem atrasos adequados pode atingir os limites de taxa e desperdiçar recursos.
• Não Gerir Todos os Resultados da Sessão: Uma sessão pode ter vários estados (por exemplo, pending, approved, declined, resubmission_requested), e a sua aplicação deve estar preparada para lidar com cada um.
• Má Configuração do Webhook: Depender apenas do polling em vez de webhooks para atualizações de sessão pode introduzir latência e complexidade. Se estiver a usar webhooks, certifique-se de que estão configurados corretamente e que o seu endpoint está acessível e responsivo.

Estratégias de Resolução de Problemas:

• Rever a Configuração do Fluxo de Trabalho: Use didit_get_workflow para inspecionar a configuração dos seus fluxos de trabalho de verificação, garantindo que se alinham com os seus passos de verificação esperados (por exemplo, Verificação de ID, Vivacidade Passiva e Ativa, Correspondência Facial 1:1).
• Utilizar os Webhooks da Didit: Configure webhooks para receber atualizações em tempo real sobre as alterações de estado da sessão. Esta é a forma mais eficiente de gerir resultados de verificação assíncronos. Valide a sua assinatura de webhook para garantir a autenticidade dos pedidos recebidos.
• Registar IDs de Sessão: Sempre registe o session_id da Didit quando uma sessão é criada. Este ID é crucial para depuração e recuperação de informações detalhadas mais tarde usando ferramentas como didit_get_session_decision.
• Testar Casos Limite: Simule vários resultados, incluindo verificações bem-sucedidas, rejeições e casos que exijam nova submissão, para garantir que a sua aplicação lida com todas as possibilidades de forma elegante.

Como a Didit Ajuda

A Didit foi concebida a pensar nos programadores, oferecendo um conjunto de funcionalidades que simplificam significativamente a integração e a depuração. A nossa plataforma de identidade modular e nativa de IA fornece ferramentas robustas para prevenir e resolver problemas comuns de integração.

• Design Focado no Programador: A Didit oferece um sandbox instantâneo, documentação pública abrangente e APIs limpas, tornando mais fácil começar e resolver problemas. A nossa abordagem API-first significa que pode gerir todos os aspetos da verificação de identidade programaticamente.
• Arquitetura Modular: As nossas primitivas de identidade componíveis, incluindo Verificação de ID (OCR, MRZ, códigos de barras), Vivacidade Passiva e Ativa, Correspondência Facial 1:1 e Rastreio AML, permitem construir e testar fluxos de verificação incrementalmente, isolando potenciais problemas em módulos específicos.
• Fluxos de Trabalho Orquestrados: A Consola de Negócios sem código permite configurar e testar fluxos de trabalho KYC complexos visualmente, reduzindo a hipótese de erros lógicos na sua integração.
• Integração de Agente de IA (Servidor MCP): A Didit foi construída para a era dos agentes. O nosso servidor Model Context Protocol (MCP) permite que agentes de codificação de IA interajam diretamente com a plataforma, automatizando tarefas como registo de contas, configuração de fluxos de trabalho e gestão de sessões, reduzindo ainda mais os erros manuais e acelerando a depuração.
• KYC Core Gratuito: Comece a verificar identidades sem custos iniciais, permitindo testes e depuração extensivos num ambiente de produção sem barreiras financeiras. O nosso modelo de pagamento por verificação bem-sucedida, sem taxas de configuração, garante que só paga pelo que utiliza.
• Relatórios de Erros Detalhados: As APIs da Didit fornecem mensagens de erro claras e acionáveis, guiando-o diretamente para a causa raiz do problema.

Pronto para Começar?

Pronto para ver a Didit em ação? Obtenha uma demonstração gratuita hoje.

Comece a verificar identidades gratuitamente com o nível gratuito da Didit.