Atendimento

NFC-e

NFC-e modelo 65 por código de produto, contingência offline automática e DANFCe.

A NFC-e (modelo 65) usa o mesmo motor e as mesmas convenções da NF-e, com itens enviados só pelo código do catálogo e contingência offline automática. Toda rota exige X-Emitente-Id e o produto NFCE contratado. NFC-e não aparece em /nfe, e vice-versa. Não há carta de correção.

O emitente precisa de CNPJ, inscrição estadual, certificado A1, uma série NFCE e o CSC do ambiente.

Emissão

POST /api/v1/nfce
X-Emitente-Id: 8b3c1f0e-5d2a-4a1b-9c3d-2e1f0a9b8c7d
Idempotency-Key: 5c2e8a1f-9d4b-4f7e-a3c6-1b8d0e2f4a6c

{
  "consumidor": { "cnpjCpf": "52998224725" },
  "itens": [
    { "produto": "7891000315507", "quantidade": "2" },
    { "codigo": "AVULSO", "descricao": "Pao de queijo", "ncm": "19059090", "quantidade": "3", "valorUnitario": "2.50" }
  ],
  "pagamentos": [{ "forma": "DINHEIRO", "valor": "50.00" }]
}

A resposta 202 já traz a chaveAcesso e o qrCode. POST /nfce/calculo devolve a prévia (tributos e itens já completados), sem gravar nem numerar; nela, pagamentos é opcional.

CampoObservação
serieOpcional
naturezaOperacaoPadrão "Venda ao consumidor"
presencaPRESENCIAL (padrão) ou ENTREGA_DOMICILIO, que exige consumidor.endereco
consumidorOpcional ("CPF na nota"): cnpjCpf e, se quiser, nome, email, endereco (só na UF do emitente)
pagamentosObrigatório, sem SEM_PAGAMENTO; o excedente vira troco
informacoesAdicionaisOpcional

Itens

De 1 a 990, de duas formas. O campo informado sempre prevalece sobre o cadastro.

  • Por código — {produto, quantidade, valorUnitario?, desconto?}, com produto igual ao código ou GTIN do catálogo: descrição, NCM, CEST, CFOP, preço e tributação vêm do cadastro. GTIN brasileiro fora do catálogo: descrição, NCM e CEST vêm do cadastro de GTIN da SEFAZ, e valorUnitario é obrigatório. Não encontrado: 400 em itens[i].produto.
  • Completo — os campos do item da NF-e (codigo, descricao, ncm, valorUnitario...). Sem icms, vale o perfil fiscal do emitente.

Automações: sem cest, a nota usa o único CEST do NCM; o CFOP do catálogo ou do perfil vira 5405 em CST 60 / CSOSN 500; IBS/CBS como na NF-e.

Regras da NFC-e (400 no campo): CFOP 5101, 5102, 5103, 5104, 5115, 5405, 5656, 5667 ou 5933; sem IPI, DIFAL, frete ou seguro no item e sem ICMS-ST retido (CST 10/30/70, CSOSN 201/202/203).

Erros do POST: os da NF-e e 422 perfil-fiscal-ausente (regime normal, item sem tributação e sem perfil).

A NFC-e

Além dos campos da NF-e, a NFC-e traz tipoEmissao (NORMAL ou CONTINGENCIA_OFFLINE), qrCode (v3, NT 2025.001), urlChave, contingencia (em, justificativa, prazoTransmissao) e os itens já completados.

RotaResposta
GET /nfce/{id}a NFC-e, com regularizacao
GET /nfce/{id}/xmlnfeProc; 409 nfce-nao-autorizada sem protocolo (inclui CONTINGENCIA ainda não autorizada)
GET /nfce/{id}/danfce?largura=80PDF em bobina de 80 ou 58 mm; liberado em AUTORIZADA, CANCELADA e CONTINGENCIA
GET /nfcepágina; filtros status, emissaoDe, emissaoAte, consumidor, q
GET /nfce/resumo/mensal?de=&ate=como o da NF-e

Contingência offline

Se a SEFAZ não responder em 10 segundos, a NFC-e é reemitida offline automaticamente, com novo número e nova chave (tpEmis 9), e vai para CONTINGENCIA. O DANFCe já pode ser impresso e entregue ao consumidor.

Depois, o servidor:

  1. transmite a nota até AUTORIZADA (ou REJEITADA), avisando pelo webhook;
  2. regulariza a tentativa online abandonada, listada em regularizacao ([{numero, chaveAcesso, situacao}], com situacao PENDENTE, CANCELADA ou INUTILIZADA): se ela chegou a ser autorizada, é cancelada por substituição (evento 110112); se não existe na SEFAZ, o número é inutilizado.

O seu sistema não precisa fazer nada: use sempre a chave e o número da nota devolvidos no GET. Número de tentativa ainda pendente não pode ser inutilizado à mão (422 faixa-em-uso).

Cancelamento, eventos e inutilização

  • POST /nfce/{id}/cancelamento com {justificativa}: 200 NFC-e CANCELADA (evento 110111). O prazo é o da UF, conferido pela SEFAZ (em geral 30 minutos).
  • GET /nfce/{id}/eventos e GET /nfce/{id}/eventos/{eventoId}/xml: cancelamento e cancelamento por substituição.
  • POST /nfce/{id}/sincronizar: reconsulta a situação na SEFAZ.
  • POST /nfce/inutilizacao e GET /nfce/inutilizacoes: como na NF-e, na série NFC-e.

Nesta página