Fazer uma consulta
A rota, os tipos de campo, os formatos aceitos, o PDF da certidão e o tempo de resposta.
Como fazer uma consulta
Toda consulta é um POST na URL do produto, com um corpo JSON:
POST /v1/{produto}/consultas
Content-Type: application/jsonA consulta é síncrona: a resposta chega na mesma conexão, já com o resultado. A exceção é o órgão que não responde: a consulta volta em_processamento ("Aguardando retorno"), sem cobrança, e é refeita sozinha em 1, 5, 10, 15, 20, 30 e 60 minutos. O desfecho chega pelo webhook, e o detalhe se busca pelo id com GET /v1/{produto}/consultas/{id}. Não repita a consulta enquanto ela estiver na fila.
A validação de documento médico também volta em_processamento quando chegam muitos documentos de uma vez: cada um espera a vez de ser lido (até 30 dias) e o desfecho chega do mesmo jeito, pelo webhook.
Campos obrigatórios e complementares
Cada produto documenta três tipos de campo:
| Tipo | O que significa |
|---|---|
| Obrigatório | Sem ele a consulta é recusada com 422 e nada é cobrado. |
| Um de | Informe um dos campos do grupo — por exemplo, cpf ou cnpj. Os dois juntos também são recusados. |
| Complementar | Não é exigido. Quando você tem, envie: a fonte usa para achar a pessoa certa (homônimos, bases incompletas) e o resultado fica mais preciso. |
Campo que o produto não usa é ignorado — não gera erro e não vai para a fonte. Por isso você pode enviar sempre o mesmo conjunto de dados do seu cadastro.
Formatos aceitos
| Dado | Aceita | Exemplo |
|---|---|---|
| CPF | Com ou sem máscara | 000.000.001-91 ou 00000000191 |
| CNPJ | Numérico ou alfanumérico, com ou sem máscara | 11.222.333/0001-81, 12.ABC.345/01DE-35 |
| Data | DD/MM/AAAA ou AAAA-MM-DD; nunca no futuro | 05/08/1996 |
| UF | Sigla, maiúscula ou minúscula | SP, sp |
| CEP | 8 dígitos, com ou sem hífen | 01310-100 |
| Placa | Antiga ou Mercosul, com ou sem hífen | ABC-1234, ABC1D23 |
| Arquivo | Base64, com ou sem prefixo data:...;base64, | iVBORw0KGgo... |
| Competência | AAAA-MM ou MM/AAAA; nunca no futuro | 2026-08 |
Campos comuns a todos os produtos
| Campo | Tipo | Descrição |
|---|---|---|
referencia | texto, até 80 | Seu identificador (matrícula, número do pedido, id do cadastro). Volta igual na resposta e no webhook, e aparece no histórico do portal. |
incluirPdf | booleano | Nos produtos que emitem certidão em arquivo: true devolve o PDF em base64. Veja PDF das certidões. |
Tamanho do corpo
Até 8 KB. Os produtos que recebem arquivo aceitam mais: 8 MB em documento-validacao, 28 MB em documento-medico e 64 KB nas APIs do eSocial (certificado A1). Corpo acima do limite ou JSON malformado responde 400.
PDF das certidões
Nos produtos que emitem certidão em arquivo, envie "incluirPdf": true para receber o PDF em detalhe.certidao.pdfBase64.
const pdf = Buffer.from(resposta.detalhe.certidao.pdfBase64, "base64");
fs.writeFileSync(`certidao-${resposta.id}.pdf`, pdf);- O arquivo vem dentro da resposta, em base64. Não há link para baixar depois.
- Se o órgão não entregar o arquivo naquele momento, a certidão vem normalmente, sem
pdfBase64— onumeroserve para conferir no site do órgão. - O PDF não fica guardado no NexusQuery. Salve no seu sistema se precisar.
- Sem
incluirPdf, a resposta é menor e mais rápida.
Cada produto informa na página dele se entrega PDF (sob pedido) ou não entrega. Nenhum produto manda o arquivo sem incluirPdf: true.
Tempo de resposta
As consultas vão a sistemas de órgãos públicos em tempo real, e alguns levam dezenas de segundos. Cada produto tem um tempo máximo, informado na página dele — passou dele, a consulta não é cobrada: quando a falha é de transporte ela vai para a fila (em_processamento) e é refeita sozinha; quando não há o que esperar, termina na hora (indisponivel ou pedido_recusado).
| Tempo máximo | Produtos |
|---|---|
| 30 s | cpf-dados, cnpj-receita, ncm, cep |
| 60 s | historico-academico-medicina, cnes-profissional, documento-validacao, esocial-encargos-empresa, esocial-encargos-trabalhador, esocial-tabelas, esocial-cat, esocial-aso, esocial-riscos, esocial-afastamentos, esocial-trabalhador, esocial-desligamentos, esocial-remuneracao |
| 90 s | enderecos-pessoas-ligadas-empresa, relacionamentos-empresa |
| 120 s | processos-socios |
| 180 s | tse-local-votacao, status-cpf, bacen-sancoes, comprot, dados-profissionais, turnover-profissional, historico-escolar, premios-certificacoes, veiculos-da-pessoa, probabilidade-negativacao, risco-financeiro, devedores-governo, kyc-compliance, kyc-familiares, dados-registro, informacoes-financeiras, financeiro-familiares, risco-financeiro-familiar, beneficios-sociais, beneficios-sociais-familiares, propensao-apostas, sociodemografico, servidor-publico, propriedade-industrial, exposicao-esportiva, licencas-autorizacoes, terras-indigenas, reserva-legal, areas-embargadas-icmbio, areas-protecao-ambiental, relacionamentos-economicos, relacionamentos-pessoais, risco-ip, situacao-cnpj, optante-simples, simples-mei, inscricao-municipal, sintegra, acordos-sindicais, propriedade-industrial-empresa, propriedade-industrial-funcionarios, propriedade-industrial-socios, kyc-compliance-empresa, kyc-socios, kyc-grupo-economico, comportamento-financeiro-digital-empresa, cobranca-empresa, dados-registro-empresa, evolucao-empresa, processos-socios-distribuicao, reputacao-empresa, premios-certificacoes-empresa, devedores-governo-empresa, mercado-financeiro-empresa, obras-civis-empresa, projetos-publicos, habilitacao-comex, processos-judiciais, processos-familiares, processos-cade, sed-concluintes, historico-placa, detran-multas, rntrc, crm, conselhos-de-classe, nfe, cte, ficha-tecnica-produto, imagens-produto, municipios-cep, estatisticas-empresas-cep |
| 240 s | mandado, antecedentes, antecedentes-pc, tse-quitacao, tse-crimes-eleitorais, cpf-comprovante, cgu-negativa, cnj-negativa, pgfn, debitos-trabalhistas, debitos-estaduais, ibama-regularidade, ibama-negativa, ibama-embargos, cadin, fgts, pcd-reabilitados, kyc-funcionarios, processos-distribuicao, processos-familiares-distribuicao, processo-por-numero, acoes-judiciais, acoes-trabalhistas, tj-certidao, tjmsp-certidao, stm-certidao, mpf-certidao, protestos, crm-certidao, certificado-acls-pals-atls |
| 300 s | documento-medico |
Configure o timeout do seu cliente HTTP acima do tempo máximo do produto (sugestão: tempo máximo + 10 s). Timeout menor corta a conexão antes da resposta — e a consulta pode ter sido concluída e cobrada do nosso lado.