Consulta cadastral de CPF e de CNPJ
Sete módulos consultam a fonte cadastral a partir do documento já validado:cpf_status (situação na Receita e óbito), cpf_contacts (telefones e e-mails), cpf_addresses, cpf_companies (empresas no nome do titular), cnpj_registration, cnpj_realtime (cadastro em tempo real, com CNAE, porte e quadro societário) e cnpj_shareholdings (o QSA detalhado, com percentual de cada sócio). Todos exigem Documento, Face Match e Liveness no mesmo flow, e a razão é a de sempre: o CPF ou CNPJ consultado vem do documento apresentado por quem está vivo na frente da câmera, nunca de um número digitado. Sem esse portão, a plataforma viraria uma ferramenta de consulta cadastral de terceiros.
Duas armadilhas de leitura, e as duas já custaram integração alheia. A primeira: status não é a situação cadastral do titular, é o indicador de sucesso da chamada à fonte (1 quer dizer “a consulta deu certo”). A situação cadastral é situacao, e ela vem como texto no CPF ("Regular", "Titular Falecido") e como objeto no CNPJ ({ "id": 2, "nome": "Ativa", … }). A segunda: as datas do dossiê vêm no formato brasileiro DD/MM/AAAA, e não em ISO, com uma exceção que é justamente onde você não espera (veja data_entrada logo abaixo).
A chave data se comporta de dois jeitos diferentes, e vale saber qual é qual. Nos quatro tiers de CPF a chave sempre existe e vem null quando não houve enriquecimento (fonte fora, documento não encontrado, ou o portão de identidade não liberou). Nos três tiers de CNPJ a chave é omitida quando não há nem dossiê nem screening de sócios. Um parser que assume “data sempre presente” erra no CNPJ; um que assume “data ausente significa nada consta” erra nos dois.
decision_reason: "registration_source_unavailable". Recusa e bloqueio não mudam. Para o titular o código é manual_review, e reprocessar a verificação no painel refaz só a consulta que faltou.
A consulta é refeita sozinha. Quando a fonte não responde, a consulta cadastral é refeita sozinha por tempo limitado depois da decisão, sem nova ação sua nem do titular. Se a fonte voltar nesse tempo, chega um webhook novo da mesma verificação, com revision, trazendo o dado no check e sem cobrança a mais. Se não voltar, o check segue pending com gov_unavailable, e o reprocesso pelo painel continua disponível.
Nos tiers de CNPJ o dossiê vem aninhado em company, e ao lado dele pode viajar partner_screening, que é o screening do quadro societário descrito na próxima seção. Os três tiers entregam conjuntos bem diferentes: cnpj_registration é o cadastro básico pela base pública mensal da Receita, com o mês de referência da base em reference_month (a última base mensal carregada por inteiro: enquanto a atualização do mês seguinte roda, ou se ela parar no meio, um cadastro pode já vir da base seguinte, nunca de uma anterior) e a opção pelo Simples Nacional e pelo MEI (sem CNAE, sem porte e sem sócios; empresa aberta depois do retrato do mês sai pendente, nunca inexistente), cnpj_realtime é o mais completo (acrescenta natureza jurídica, CNAE, porte, Simples Nacional, regimes tributários e o QSA) e cnpj_shareholdings é o mais magro de todos, porque o produto dele é uma coisa só: o percentual de cada sócio.
company.socios, e o corte é declarado: o par truncated mais truncated_fields no topo diz exatamente o que saiu, como explicado em Webhooks. A decisão nunca é podada, e o detalhe completo continua no painel.
Em sandbox nada é consultado e o dossiê vem pronto, escolhido pelo sufixo do documento: 03 devolve a situação suspensa ou inapta e 99 o documento inexistente. Só no sandbox o dossiê carrega a chave "mock": true, que produção nunca emite: se você ramificar por ela, o código quebra na virada de ambiente.