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/json

A 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:

TipoO que significa
ObrigatórioSem ele a consulta é recusada com 422 e nada é cobrado.
Um deInforme um dos campos do grupo — por exemplo, cpf ou cnpj. Os dois juntos também são recusados.
ComplementarNã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

DadoAceitaExemplo
CPFCom ou sem máscara000.000.001-91 ou 00000000191
CNPJNumérico ou alfanumérico, com ou sem máscara11.222.333/0001-81, 12.ABC.345/01DE-35
DataDD/MM/AAAA ou AAAA-MM-DD; nunca no futuro05/08/1996
UFSigla, maiúscula ou minúsculaSP, sp
CEP8 dígitos, com ou sem hífen01310-100
PlacaAntiga ou Mercosul, com ou sem hífenABC-1234, ABC1D23
ArquivoBase64, com ou sem prefixo data:...;base64,iVBORw0KGgo...
CompetênciaAAAA-MM ou MM/AAAA; nunca no futuro2026-08

Campos comuns a todos os produtos

CampoTipoDescrição
referenciatexto, até 80Seu identificador (matrícula, número do pedido, id do cadastro). Volta igual na resposta e no webhook, e aparece no histórico do portal.
incluirPdfbooleanoNos 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 — o numero serve 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áximoProdutos
30 scpf-dados, cnpj-receita, ncm, cep
60 shistorico-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 senderecos-pessoas-ligadas-empresa, relacionamentos-empresa
120 sprocessos-socios
180 stse-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 smandado, 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 sdocumento-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.