Começar
Integrar / SDKs
Verificação de utilizadores
Verificação de empresas
Monitorização de transações
Registo de alteraçõesvin ou bank_account_number, por isso as páginas de serviço que os enviam mostram apenas cURL.
Instalação
Configuração
Todos os SDKs leem as mesmas variáveis de ambiente, pelo que um cliente criado sem opções fica pronto a utilizar. Os ambientes de execução edge não têm ambiente de processo: nesses casos, passe a chave de API ao cliente Node.js como opção.
Tudo o que pode definir através do ambiente também pode ser passado ao cliente, juntamente com o URL base, o tempo limite, as novas tentativas, os cabeçalhos predefinidos e o seu próprio cliente HTTP. Crie um cliente por processo e partilhe-o: ele mantém um pool de ligações e é seguro para utilizar a partir de várias threads ou tarefas.
Os métodos
account (registo programático: registar, iniciar sessão, organizações e aplicações) chamam https://apx.didit.me/auth/v2 e nunca enviam a sua chave de API. Inicie sessão com account.login e, depois, passe o token de acesso devolvido ao cliente como o seu token de conta.
O que faz cada SDK
- Recursos e métodos. As chamadas seguem os recursos da API:
client.<resource>.<method>(...), por exemplosessions.create,sessions.retrieve_decisionoutransactions.create, com a capitalização própria de cada linguagem. Os IDs de caminho são argumentos posicionais; o corpo e os parâmetros de consulta são um único conjunto de campos com nome. Python, Node.js, PHP e Ruby usam os nomes de campo da própria API (workflow_id); Go, Java e .NET usam a capitalização da sua linguagem (WorkflowID,workflowId,WorkflowId). - Listas. Os métodos de listagem percorrem todos os resultados por si (
limiteoffsetinternamente) e também expõem cada página comcount,next,previouseresults. Em Ruby,auto_paging_eachpercorre todas as páginas, e ototal_count, onext_urle oprevious_urlde uma página correspondem aocount, aonexte aopreviousda API. - Ficheiros. Os envios (imagens de documentos, selfies, comprovativos de morada, importações) aceitam um caminho, bytes ou um stream. Os downloads (PDF de sessões, relatórios) devolvem bytes ou um stream, nunca JSON analisado.
- Compatibilidade futura. Um campo de resposta ou um valor de enumeração que a versão do SDK ainda não conhece é mantido e legível, nunca um erro, para que uma adição à API não quebre uma integração em produção.
- Webhooks.
webhooks.verifyverifica os cabeçalhosX-Signature-V2eX-Signaturee a marca temporal de uma entrega com o seu segredo de webhook, e devolve um evento tipado. Aceita uma lista de segredos enquanto faz a rotação de um deles. Veja Webhooks para o esquema de assinatura. - Autenticação. Um auxiliar
Authenticationverifica os tokens de acesso e de ID que o seu emissor de Authentication assina, e chama os seus endpoints de token, de sessão e de autenticação step-up. Nunca utiliza a sua chave de API.
Erros, novas tentativas e tempos limite
Todos os erros derivam de
DiditError. Em Go, todos os erros implementam a interface didit.Error e são tipos de ponteiro, como *didit.NotFoundError. Java, PHP e .NET usam o sufixo habitual Exception e escrevem API como Api: DiditException, ApiStatusException, NotFoundException.
Os SDK voltam a tentar um pedido que falhou até 2 vezes, com recuo exponencial a partir de 0,5 segundos (jitter total, com no máximo 8 segundos) e respeitando o Retry-After. Os pedidos GET, HEAD, PUT e DELETE são repetidos em caso de erros de ligação, tempos limite, 408, 429 e 5xx. Os pedidos POST e PATCH são repetidos apenas em caso de 429 ou quando a ligação falhou antes de o pedido ser enviado, para que uma nova tentativa nunca crie uma segunda sessão ou transação. O tempo limite predefinido é de 60 segundos. Cada resposta expõe também o estado HTTP bruto, os cabeçalhos e o ID do pedido. Consulte Limites de pedidos para os limites por trás do 429.
Versionamento e suporte
- Os SDK seguem o versionamento semântico, com uma regra para alterações da API. Uma alteração que espelha a API da Didit é uma versão menor, mesmo que possa quebrar código tipado (um campo cujo tipo mudou, um campo que passou a poder ser nulo, ou um endpoint, campo ou valor de enumeração removido). A API já se comporta dessa forma para todos os clientes, por isso uma versão anterior do SDK não é mais segura. As notas de versão listam essas alterações em “Alterações à API que podem quebrar código tipado”.
- Uma versão principal destina-se apenas a uma alteração ao design do próprio SDK: um método ou recurso renomeado ou removido enquanto a API o mantém, uma alteração à configuração do cliente, aos erros, às novas tentativas, à paginação ou ao comportamento da verificação de webhooks, ou a remoção do suporte a uma versão de runtime. Quando um endpoint sai da API ou um método é renomeado, o método antigo mantém-se durante pelo menos mais uma versão menor, marcado como obsoleto, para que o seu código continue a compilar enquanto migra para o novo. Cada linguagem mantém o seu próprio número de versão: Node.js, PHP e Ruby estão na 2.x e as restantes na 1.x, porque essas três lançaram uma alteração da API como versão principal antes de esta regra ser aplicada.
- Os SDK são gerados a partir do contrato da API publicado (
openapi-25.jsoneopenapi-auth.json), e os seus métodos de Didit Authentication são verificados em relação aopenapi-authentication.json. Os SDK verificam os três todos os dias, pelo que um novo endpoint ou campo chega numa versão regular dos sete SDK. - Cada SDK suporta a versão mínima de runtime indicada na tabela e todas as versões mais recentes. Os seus testes são executados na versão mínima e em cada versão mais recente, ou em cada versão de suporte prolongado (LTS) no caso de Node.js e Java.
- O
CHANGELOG.mdde cada repositório lista as alterações de cada versão. - Comunique um problema de segurança de forma privada através dos avisos de segurança do repositório do SDK ou enviando-o para support@didit.me.