Comprovante de endereço
O móduloaddress_ocr lê o comprovante de endereço que o titular envia e devolve o endereço impresso nele. Valem conta de luz, água, gás, telefone ou internet, fatura ou extrato bancário, contrato de aluguel e documento de órgão público. Além do endereço, ele responde duas perguntas que a leitura sozinha não responde: o comprovante é recente? e o nome dele é o mesmo do documento de identidade lido neste fluxo?
Um passo novo no widget, e zero código a mais do seu lado. O titular envia um PDF ou uma foto, de até 4 MB, na mesma jornada em que fotografa o documento e faz a selfie. Do PDF vale a primeira página: é nela que o comprovante precisa trazer o nome, o endereço e a data de emissão, e o widget avisa isso na tela de envio. O arquivo não passa pelo seu front nem chega ao seu backend, e a mídia fica no painel com acesso restrito por papel, como as demais.
Dependências e preço. Ele exige cpf_ocr e face no mesmo flow, porque o nome cruzado é o que foi lido do documento de identidade: sem eles não há contra o que cruzar. Por isso o número que importa é o do conjunto, e não o do módulo sozinho: o flow mínimo com este módulo (cpf_ocr + face + address_ocr) custa R$ 3,60 por verificação, e é esse o valor que entra na sua fatura. O unitário de cada módulo está na tabela de preços, lida do mesmo catálogo.
checks o módulo aparece com vocabulário próprio, e não com o pass/fail dos módulos de identidade: verified (extraiu, está no prazo e o nome cruzou), mismatch (o cruzamento de nome reprovou) e pending (toda a família de indeterminado, com o motivo fino em data.reason). Aqui não há lista consultada, há um documento conferido, e o vocabulário diz isso.
A recência é regra do produto, não detalhe. Um comprovante vale por até 90 dias contados da emissão. A idade em dias vem no payload (issue_age_days) para você aplicar uma régua mais apertada se a sua política pedir: a nossa é o teto, nunca o piso.
Os motivos, e o que fazer com cada um. Eles vêm em reason dentro do data do check, e se dividem em dois grupos com ações opostas. Pedem o reenvio do arquivo, e nunca são veredito contra o titular: address_not_found (o endereço não foi localizado no comprovante), address_doc_expired (o comprovante passou dos 90 dias) e address_doc_unreadable (o arquivo não pôde ser lido). Levam a revisão humana, com a evidência na mão de quem revisa: name_mismatch (o nome do comprovante diverge do nome do documento), identity_name_unavailable (o nome do documento não estava disponível para o cruzamento) e injection_suspected_text (o arquivo pede conferência humana antes de qualquer cruzamento) e address_doc_reused (o mesmo arquivo de comprovante já foi enviado por outro titular da sua conta; nunca compara com outras contas). Quando o módulo segura a verificação, o decision_reason dela é address_proof_review.
Opcional: o endereço que você já tem em cadastro. Na criação da sessão, do seu servidor, você pode enviar expected_address e ligar o sinal address_match. Ele aceita só CEP e UF, de propósito: é o recorte que responde “é o mesmo endereço?” sem que você precise nos mandar a rua e o número do titular. Sem o campo, o sinal sai unknown, que não é mismatch e muito menos match: é “não havia com o que comparar”.
expected_address num flow que não tem address_ocr é 422 expected_address_not_supported, nunca aceito e ignorado. CEP ou UF fora do formato é 400 validation_error com o campo nomeado.
Em sandbox nada é lido: o desfecho vem do sufixo do documento. 01 devolve o reenvio por endereço não localizado, 02 o nome divergente (que vai para revisão) e qualquer outro sufixo aprova. Com expected_address na sessão, o address_match do sandbox também vem do sufixo: 83 devolve mismatch e os demais match. Sem o campo, unknown, como em produção.
Quando o fluxo também tem a consulta cadastral de endereços, o data traz declared_address_match: o CEP e a UF do comprovante contra os endereços dessa consulta, com cep_match, uf_match, mismatch ou unknown quando falta um dos lados. É informação para você e nunca reprova a verificação.
Em todo comprovante o data traz também cep_consistency: o CEP lido conferido contra uma base de endereços, com ok (o CEP está na base, na mesma UF do comprovante), uf_mismatch (está na base, em outra UF), cep_not_in_base ou unknown (não houve conferência, por exemplo quando o CEP não foi lido). Fora da base não quer dizer inexistente: CEP novo ou de grande usuário pode faltar nela. É informação para a sua política, e nunca muda o desfecho da verificação.
Fonte da base de CEP: IBGE, Cadastro Nacional de Endereços para Fins Estatísticos (CNEFE), Censo Demográfico 2022.