Consultando uma emissão de NFS-e

Há duas consultas diferentes, e confundi-las custa cota.

O que você quer	Rota	Consome cota
saber como ficou a emissão que você pediu	GET /v1/nfse/consultar/{job_id}	não
perguntar à prefeitura o que ela tem	POST /v1/nfse/consultar-sefaz	sim
idem, por RPS, no GovDigital	GET /v1/nfse/{cpf_cnpj}/consultar-rps	sim

Pelo job_id — o caminho normal

curl -s https://api.conota.dev/v1/nfse/consultar/$JOB_ID \
  -H "X-API-Key: $CONOTA_API_KEY"

Lê o que já guardamos. É o que você usa para acompanhar uma emissão, e não consome cota — pode consultar à vontade enquanto espera.

A resposta traz os dois eixos de estado — o do processamento e o fiscal. Ver Status das emissões.

Perguntando à prefeitura

POST /v1/nfse/consultar-sefaz

{ "cpf_cnpj": "11222333000181", "chave_acesso": "..." }

Esta consome cota de NFS-e

Ela sai da nossa base e vai falar com o provedor — Padrão Nacional por API, municípios próprios pelo ACBr. Por isso é cobrada como uma operação, e não como leitura.

Use quando precisa da verdade da prefeitura: conferir se uma nota que sumiu do seu lado existe lá, ou reconciliar depois de uma indisponibilidade. Para acompanhar emissão do dia a dia, use a consulta por job_id.

Em lote

A rota de lote é a mesma para todos os documentos — até 200 ids, e lê o que já guardamos:

POST /v1/jobs/consultar-lote

Id inexistente ou de outra conta volta como "status": "nao_encontrado" — sem 404.

Quando o job_id se perdeu

GET /v1/jobs/localizar?ref=os_4471

Também aceita período, CNPJ do prestador, documento do tomador e valor — ver Referência externa.

A NFS-e demora mais, e falha diferente

Prefeitura não é SEFAZ

A autorização de NFS-e depende do sistema do município, e a variação é grande: alguns respondem em segundos, outros levam minutos e alguns saem do ar sem aviso.

Isso torna o webhook mais útil aqui que na NF-e — ver Webhooks — e torna o job_id mais importante ainda: é ele que liga o que você pediu ao que a prefeitura respondeu, mesmo dias depois.

Consultar não é o mesmo que ter o documento

Depois de autorizada, o XML e o DANFSe saem por Arquivos.