Endpoints NFC-e
Emitir cupom fiscal, ESC/POS térmico (80mm/58mm), XML, DANFE e cancelamento.
Referência completa dos endpoints REST da NFER para emissão e gestão de NFC-e (Nota Fiscal de Consumidor Eletrônica — Modelo 65). A API oferece autorização assíncrona ultra rápida, geração nativa de comandos térmicos ESC/POS (80mm e 58mm) para impressoras de balcão e DANFE sob demanda.
Tabela Geral de Endpoints NFC-e
| Método | Endpoint | Descrição | Status HTTP |
|---|---|---|---|
| POST | /v1/nfce | Cria rascunho de cupom NFC-e (modelo 65) | 201 Created |
| POST | /v1/nfce/:id/send | Assina e envia o cupom para autorização na SEFAZ | 202 Accepted |
| GET | /v1/nfce/:id | Consulta status, chave, protocolo e dados do cupom | 200 OK |
| GET | /v1/nfce/:id/escpos | Gera comandos de impressão térmica ESC/POS (80mm/58mm) | 200 Stream / JSON |
| GET | /v1/nfce/:id/xml | Baixa o arquivo XML assinado e autorizado da NFC-e | 200 XML |
| GET | /v1/nfce/:id/danfe | Gera e baixa o PDF do cupom fiscal NFC-e | 200 PDF |
| POST | /v1/nfe/:id/cancel | Cancela a NFC-e autorizada (respeitando prazo da UF) | 202 Accepted |
| POST | /v1/nfe/inutilizar | Inutiliza numeração pulada com modelo="65" | 200 OK |
1. Criar Rascunho de NFC-e
Cria o registro do cupom fiscal, reserva o próximo número da série de NFC-e e calcula os impostos automaticamente. O destinatário é opcional para vendas anônimas.
/v1/nfceCria rascunho de cupom NFC-e modelo 65.
Parâmetros do Payload (POST /v1/nfce)
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| customer | objeto | não | Identificação do consumidor (cpfCnpj e nome). Se omitido, a nota é emitida como consumidor anônimo. |
| customerId | string (UUID) | não | ID de cliente já cadastrado no NFER. |
| naturezaOperacao | string | não (def. "VENDA AO CONSUMIDOR") | Descrição da operação fiscal. |
| serie | number | não (def. 1) | Série da NFC-e (modelo 65) cadastrada na SEFAZ. |
| indPres | number | não (def. 1) | Indicador de presença: 1 = Presencial, 4 = Delivery NFC-e, 9 = Outros. |
| indFinal | number | não (def. 1) | Consumidor final. Na NFC-e é sempre 1. |
| itens | array | sim | Lista de mercadorias vendidas (código, descrição, NCM, CFOP, quantidade, valorUnitario e perfil fiscal). |
| pagamentos | array | sim | Formas de pagamento detalhadas (ex: 01=Dinheiro, 03=Crédito, 04=Débito, 17=PIX). |
| informacoesAdicionais | string | não | Texto livre que será impresso no rodapé do cupom fiscal. |
2. Transmitir para a SEFAZ
Gera a assinatura digital do XML, calcula o QR Code com o CSC da empresa e envia para a SEFAZ em fila assíncrona. Retorna 202 Accepted imediatamente.
/v1/nfce/:id/sendEnfileira a transmissão da NFC-e à SEFAZ.
3. Impressão Térmica Direta (ESC/POS)
O NFER gera comandos binários nativos no padrão ESC/POS para impressoras não-fiscais térmicas (Epson, Elgin, Bematech, Daruma, Gertec, POS Android). Inclui renderização de código de barras, tabela de itens, totais, formas de pagamento, QR Code oficial da SEFAZ e comando de corte automático de papel.
/v1/nfce/:id/escposObtém os bytes ESC/POS formatados para envio direto à porta TCP 9100 ou USB/Serial.
| Query Param | Valores | Padrão | Descrição |
|---|---|---|---|
| largura | 80 | 58 | 80 | Largura da bobina em milímetros (80mm = 48 colunas, 58mm = 32 colunas). |
| format | raw | base64 | json | raw | Formato de entrega. "raw" entrega application/octet-stream pronto para socket. |
| cut | true | false | true | Se deve incluir comando de corte total/parcial no final do cupom. |
4. Consulta, XML e DANFE PDF
/v1/nfce/:idConsulta dados da nota, status e URLs públicas.
/v1/nfce/:id/xmlDownload do XML autorizado da NFC-e.
/v1/nfce/:id/danfeDownload do DANFE simplificado em PDF sob demanda.
5. Cancelamento de NFC-e
O cancelamento de NFC-e é submetido à SEFAZ por evento assíncrono. Lembre-se que o prazo máximo na maioria das UFs é de 30 minutos após a autorização.
/v1/nfe/:id/cancelEnvia pedido de cancelamento com justificativa.