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": "drivers_license: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.

Uma subdivisão precisa nomear seu país. Enviar issuingState sem issuingCountry faz a requisição ser recusada, seja qual for o tipo de documento, porque PA sozinho pode ser Pennsylvania ou Pará, e a resposta nomearia uma jurisdição que você nunca informou. ssn e itin são exceção — o país deles nunca está em dúvida. Não enviar nenhum dos dois é permitido e retorna valid: null — não verificável, e não inválido. Nada infere o país: um passaporte ou carteira de identidade sem ele também 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:

Um false exige prova. A CNH, o CPF, o DNI/NIE, o SSN e o ITIN carregam uma, e um valor que nenhuma jurisdição poderia emitir — pontuação num número de habilitação, uma forma fora da genérica ICAO para um passaporte — é refutado na cara.

Um número de habilitação ou passaporte que apenas não corresponde a nenhuma das formas que mantemos para sua jurisdição retorna null, não false. Essas tabelas reconhecem formas; não as verificam, e são incompletas de maneiras que documentos reais continuam encontrando. Maryland emite um número prefixado por MD ao lado do antigo, e Massachusetts um prefixo de duas letras; cada um faltava até uma habilitação genuína ser rejeitada por ele. Responder false ali dizia ao integrador que um documento válido era inválido.

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

Toda regra nomeia o documentType a que pertence, então o prefixo corresponde ao tipo por igualdade de string. A única exceção é um valor reservado de sandbox, prefixado com reserved: e com o tipo no segundo segmento — veja Sandbox e Dados de Teste.

Erros

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