POST persiste e enfileira a nota, retornando 201 com a situação pendente. O que muda é o destino fiscal e como o resultado é acompanhado. Cada tipo de nota tem seu próprio ciclo abaixo.
NF-e — Nota de Produto
Emissão é assíncrona
POST /notas não emite a NF-e de forma síncrona. A nota é persistida e enfileirada para autorização junto à SEFAZ; a resposta é 201 Created com situacao: "pendente". O uuid e a chave_acesso já voltam estáveis nessa resposta (são gerados na criação).
Para acompanhar o resultado, há duas opções:
Polling
Consulte
GET /notas/{uuid} até a situacao mudar.Webhooks
Assine os eventos
nfe_*. Veja Webhooks.O próximo webhook após
nfe_solicitacao_autorizacao é o veredito terminal (nfe_autorizada, nfe_rejeitada ou nfe_denegada). Não existe evento intermediário em_processamento.Estados (situacao)
| Estado | Significado |
|---|---|
pendente | Criada e enfileirada; ainda não transmitida. |
em_processamento | Lote enviado, aguardando o protocolo da SEFAZ. |
autorizada | Autorizada pela SEFAZ. XML e DANFE disponíveis. |
rejeitada | Rejeitada pela SEFAZ (veja a mensagem de erro). |
denegada | Denegada pela SEFAZ. |
cancelada | Cancelamento autorizado (evento 110111). |
inutilizada | Numeração inutilizada. |
Cancelamento
DELETE /notas/{uuid}/cancel solicita o cancelamento (evento 110111) de uma nota autorizada, com justificativa de 15–255 caracteres. O processamento é assíncrono: retorna 202 e o resultado chega via webhook (nfe_cancelamento_autorizado / nfe_cancelamento_rejeitado) ou polling.
Inutilização é síncrona
POST /inutilizacoes (inutilização de faixa de numeração) é a única operação que chama a SEFAZ de forma inline — uma chamada SOAP curta, veredito imediato: retorna 200 (inutilizada) ou 422 (rejeitada).
Documentos
Após a autorização, baixe os documentos fiscais pelas rotas autenticadas:GET /notas/{uuid}/xml— XML autorizado (nfeProc),application/xml.GET /notas/{uuid}/danfe— DANFE,application/pdf(gerado sob demanda no primeiro acesso).
NFS-e — Nota de Serviço
Emissão é assíncrona (via RPS)
POST /notas não emite a NFS-e de forma síncrona. A nota é persistida e um RPS (Recibo Provisório de Serviços) é gerado e enfileirado para envio em lote à prefeitura. A resposta é 201 Created com rps.situacao: "pendente" e nfse.situacao: "pendente". O id já volta estável nessa resposta.
A resposta tem duas máquinas de estado: o RPS é o veículo (o envio do recibo à prefeitura) e a NFS-e é o resultado (a nota de serviço efetivamente emitida). Em uso normal acompanhe
nfse.situacao; consulte rps.situacao para diagnosticar uma falha de envio.Polling
Consulte
GET /notas/{id} até nfse.situacao virar emitida (com nfse.numero e codigo_verificacao) ou o RPS falhar (rps.situacao: "processado_com_erro").A API de NFS-e não emite webhooks (diferente da NF-e) — acompanhe por polling. As notificações por e-mail da conta seguem normalmente.
Estados da NFS-e (nfse.situacao)
| Estado | Significado |
|---|---|
pendente | Criada e enfileirada; aguardando emissão pela prefeitura. |
emitida | Emitida pela prefeitura. nfse.numero e codigo_verificacao disponíveis. |
cancelada | Cancelamento autorizado pela prefeitura. |
substituida | Substituída por outra nota. |
Estados do RPS (rps.situacao)
Diagnóstico do envio do lote à prefeitura:
| Estado | Significado |
|---|---|
pendente | Ainda não transmitido. |
nao_recebido | Lote não recebido pela prefeitura. |
nao_processado | Recebido; processamento ainda pendente. |
processado_com_erro | Rejeitado pela prefeitura (veja a mensagem de erro). |
processado_com_sucesso | Lote processado; a NFS-e foi emitida. |
Cancelamento
DELETE /notas/{id}/cancel solicita o cancelamento de uma nota emitida, com motivo_cancelamento obrigatório. O processamento é assíncrono: retorna 202 e a nfse.situacao passa a cancelada quando a prefeitura confirma — acompanhe por polling. Apenas notas com nfse.situacao: "emitida" podem ser canceladas (422 caso contrário).
A NFS-e não tem inutilização de faixa nem download de XML/DANFE — a comprovação da nota é o
codigo_verificacao, conferível no portal da prefeitura.