Validador de Número de Documento

Verifique se um número de documento é bem-formado para sua jurisdição, antes de criar uma sessão ou enviar uma verificação. Nada é armazenado e nenhuma verificação é consumida.

Endpoint: POST /v1/validators/document-number
Autenticação: Token Bearer com o escopo sessions

Uma verificação de formato sem estado contra o mesmo registro que o pipeline de verificação usa. Nada é armazenado e nenhuma verificação é consumida — mas ela recebe identificadores governamentais, portanto é atribuída a um tenant como todos os outros endpoints aqui. Útil para validar a entrada no seu próprio formulário antes de criar uma sessão.

curl --request POST \
  --url https://{FQDN}/v1/validators/document-number \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
  "documentType": "drivers_license",
  "number": "31612967",
  "issuingCountry": "USA",
  "issuingState": "PA"
}'

{
  "documentType": "drivers_license",
  "issuingCountry": "USA",
  "issuingState": "PA",
  "valid": true,
  "rule": "dl:USA:PA",
  "detail": "document number matches the PA license format"
}

O número enviado nunca é devolvido na resposta. A resposta informa a jurisdição aplicada, não o identificador que você enviou.

O Que Está Coberto

Os 11 países adicionais de passaporte, como o issuingCountry que você envia: ARG, AUS, CHN, DEU, FRA, GBR, IND, ITA, JPN, NLD, RUS.

Tudo o que não está marcado com ✓ — dentro ou fora da tabela — retorna valid: null, nunca false. Trate null como "não sabemos": aceite, e não interprete como aprovação nem reprovação.

CNH, CPF e DNI/NIE são verificados com aritmética real de dígitos verificadores, então uma transposição de dígitos é detectada — ao contrário das tabelas de carteiras de motorista, que verificam apenas o formato, porque essas jurisdições não publicam dígito verificador.

Informando a Jurisdição

issuingCountry é o país — um código ISO 3166-1 alpha-3, um nome de país ou um alias comum. issuingState é uma subdivisão dentro daquele país — um estado dos EUA ou uma província ou território do Canadá — e apenas carteiras de motorista a utilizam.

Sempre envie issuingCountry. Uma carteira enviada sem ele assume USA para que integrações anteriores ao issuingCountry continuem funcionando, mas depender desse fallback é justamente como uma carteira não americana acaba verificada contra o formato de um estado dos EUA. Nada mais infere o país: um passaporte ou carteira de identidade sem ele retorna valid: null.

ssn e itin existem apenas no validador. Não são tipos de documento capturáveis — você não pode criar uma sessão para eles — mas as regras estruturais são úteis quando você os coleta nos seus próprios formulários.

Interpretando a Resposta

valid é deliberadamente de três valores:

null é a resposta honesta para uma jurisdição sem regra, e é por isso que as lacunas de cobertura abaixo são seguras em vez de silenciosamente erradas.

rule nomeia a regra aplicada, para que você saiba qual jurisdição respondeu:

Erros

O segundo merece atenção se você integrou antes de issuingCountry existir: issuingState costumava carregar o país para passaportes e carteiras de identidade. Enviá-lo dessa forma agora é um erro explícito em vez de um null silencioso, porque um null interpretado como aprovação é a falha pior.

Próximos Passos

• Sessões de Verificação — criando uma sessão, e o prefill que usa essa mesma verificação
• Sandbox e Dados de Teste — números reservados que retornam um veredito escolhido sob demanda