Emitir uma NFCe

A NFCe é o documento fiscal usado em operações de varejo presencial (substitui o cupom fiscal). Não exige transporte, é mais simples que a NFe, e geralmente é autorizada em segundos.

Fluxo

1. Emitir a NFCe

   curl -X POST $BASE/nfce/emissao \
     -H "Authorization: Token $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "serie": "65",
       "cfop": "5102",
       "numero-origem": "VENDA-2026-00100",
       "tp_pagamento": "credito",
       "porcentagem-desconto": "5",
       "cliente": "12345678901",
       "itens": [
         { "produto": "SKU-001", "quantidade": "1", "valor-unitario": "59.90" }
       ]
     }'

2. Consultar pelo recibo

   curl $BASE/nfce/cupom/{recibo} \
     -H "Authorization: Token $TOKEN"

3. Pegar DANFE NFCe e XML

   Quando status: "004", data.sefaz traz url-danfe e url-xml.

Tipos de pagamento

Valor tp_pagamento	Significa
dinheiro	Pagamento em espécie
credito (ou crédito)	Cartão de crédito
debito (ou débito)	Cartão de débito
outros	PIX, vale-refeição, transferência, etc.

A API também aceita o código numérico SEFAZ diretamente (mais avançado). Para casos comuns, use as strings acima.

Variações comuns

Sem identificar o cliente (consumidor final)

{
  "serie": "65",
  "cfop": "5102",
  "tp_pagamento": "dinheiro",
  "itens": [ ... ]
}

Pode omitir o campo cliente para emissões de balcão sem identificação.

Com taxa de serviço (restaurantes)

{
  "serie": "65",
  "cfop": "5102",
  "tp_pagamento": "credito",
  "porcentagem-taxa-servico": "10",
  "itens": [ ... ]
}

Com taxa de entrega (delivery)

{
  "serie": "65",
  "cfop": "5102",
  "tp_pagamento": "credito",
  "valor-taxa-entrega": "8.50",
  "itens": [ ... ]
}

Alterar antes de emitir

Você pode editar uma NFCe que ainda não foi submetida para emissão:

curl -X PUT $BASE/nfce/{id} \
  -H "Authorization: Token $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... mesmo formato do emissao ... }'

NFCes já em emissão ou com timer ativo (emissão iminente) não podem ser editadas.

Cancelamento

NFCe tem prazo de cancelamento muito menor que NFe (geralmente alguns minutos após autorização — varia por estado). Veja Cancelar uma NFe para a sintaxe (mesma estrutura, com endpoint POST /nfce/cancelamento).

Erros comuns

Mensagem	Causa
Campo nfce@serie inválido.	Série não numérica ou > 999
tp_pagamento ignorado	Use valor exato em minúsculas: dinheiro, credito, debito, outros
status: "900" com cst	CST do produto incompatível com NFCe — revise configurações fiscais
status: "900" com sefaz.codigo 217/105	Não é erro — SEFAZ lenta/instável, ainda processando. Continue consultando o mesmo recibo, não reemita. Veja SEFAZ lenta ou instável

Diferenças NFCe vs NFe

Aspecto	NFe (55)	NFCe (65)
Uso	B2B e B2C com entrega	Varejo presencial
Transporte	Detalhado	Não exige
Faturas	Suporta	Não suporta
Notas referenciadas	Sim	Não
DANFE	A4 completo	DANFE NFCe (cupom estilo PDV)
Prazo de cancelamento	~24h	~minutos
Identificação do cliente	Sempre obrigatória	Opcional (consumidor final)