Sua base de clientes
O móduloclient_source usa o que você já sabe sobre o seu cliente sem nos entregar a sua base. Você publica um endereço que responde a uma pergunta curta, e depois da prova de identidade a UNIFOKAL consulta esse endereço com o pedido assinado e com prazo. O pedido leva o reference_id e o identificador da verificação; o número do documento lido nesta verificação só vai quando você optou por recebê-lo e a prova de identidade passou.
known e unknown são a resposta da sua base sobre o titular e não mudam a decisão. review é o seu pedido de revisão: a verificação que sairia aprovada vai para revisão humana, e nunca é recusada por isso. invalid é uma resposta fora do combinado. unavailable quer dizer que não houve resposta válida: o seu endereço respondeu com erro, não respondeu no prazo ou não pôde ser alcançado, ou a consulta nem foi feita, e aí latency_ms vem null. Numa verificação já decidida, o bloco também pode vir sem resultado ou com verdict null, e com pending no resumo, quando a consulta não aconteceu antes da decisão; isso pode acontecer no primeiro webhook do modo expresso, e o segundo, com revision, traz o resultado se a consulta acontecer depois. Em todos esses casos a resposta da sua base não entrou na decisão: a verificação segue normalmente sem ela e o módulo não é cobrado. Se uma ação sensível do seu produto depende da sua base, confira o titular na sua base do jeito que o seu endereço o reconhece, pelo reference_id e, se ele recebe o documento, também pelo documento lido nesta verificação, quando o resultado não for known, unknown ou review. O resultado também pode decidir um passo seguinte do fluxo, por exemplo rodar mais uma consulta quando a sua base não conhece o titular. Só known, unknown e review servem de condição: sem um deles o resultado conta como desconhecido, e o passo que depende dele roda e é cobrado como qualquer passo executado.
Como cadastrar. No painel, em Base de clientes, informe o endereço, o prazo de resposta (de 100 a 1.500 milissegundos) e se o documento vai no pedido. Há um endereço ativo por ambiente; em produção ele precisa ser público e começar por https://. O segredo de assinatura, que começa com srcsec_, aparece uma única vez no cadastro e a cada troca. O botão de teste manda um pedido com test: true e mostra só o resultado.
O pedido. Um POST com corpo JSON e o cabeçalho X-IDSAAS-Source-Signature: t=<segundos>,v1=<hex>. A assinatura é o HMAC-SHA256, com o seu segredo srcsec_, do texto client_source.v1.<t>.<corpo>. Na troca de segredo com transição chegam duas assinaturas v1, a do segredo novo primeiro. Esse cabeçalho e esse segredo são diferentes dos do webhook, então um não vale pelo outro. Recuse pedido com o instante fora da janela de tempo e confira com os verificadores dos SDKs: verifyClientSourceSignature no TypeScript e verify_client_source_signature no Python.
known (true, false ou null quando você não sabe) e risk_hint (none ou review). Chave a mais, tipo errado, corpo acima de 2.048 bytes ou corpo que não é JSON viram invalid. Status fora de 2xx, prazo estourado e erro de rede viram unavailable. Não há nova tentativa dentro da mesma verificação, e o reprocessamento reaproveita o resultado já gravado: use o verification_id para reconhecer um pedido repetido. Se o endereço falhar seguidamente, a UNIFOKAL pausa as consultas por um instante e as verificações seguem sem ele; o painel mostra a pausa. Também há um limite de consultas simultâneas por organização: a consulta que passar dele não é feita, o resultado sai unavailable sem cobrança do módulo, a verificação segue sem a resposta da sua base e o painel mostra quando isso aconteceu. Quanto mais rápido o seu endereço responde, menos consultas ficam abertas ao mesmo tempo.