Como emitir NFC-e por API a partir do caixa (PDV)

Este é o caminho de uma venda do caixa até o cupom impresso, pela API da Sudrel. A ideia é que o PDV mande só o que ele já sabe (os itens, as quantidades, os preços e o pagamento) e receba de volta a NFC-e autorizada e pronta para imprimir.

1. Uma vez: caixa, produtos e prontidão

• Caixa. Cada caixa é cadastrado em POST /v1/caixas com o identificador que o seu PDV já usa (LOJA1-CX02) e uma série de 0 a 889, única na empresa. Dois caixas nunca disputam o mesmo número.
• Produtos. NCM, origem e o perfil fiscal de cada produto ficam no cadastro, aprovado por uma pessoa. É dele que a Sudrel calcula CFOP, CST ou CSOSN e os valores de cada venda.
• Prontidão. GET /v1/nfce/prontidao/{empresa_id} diz, item por item, o que falta: certificado, inscrição estadual, caixa, CSC.

2. A venda

POST /api/v1/nfce
Idempotency-Key: CUPOM-000123
Prefer: wait=15

{
  "empresa_id": "0b7e6a52-3c1d-4f8e-9a20-5d4c3b2a1f00",
  "referencia": "CUPOM-000123",
  "caixa": "LOJA1-CX02",
  "itens": [{ "produto": "CAM-1", "quantidade": 2, "valor_unitario": 39.90 }],
  "pagamentos": [{ "forma": "dinheiro", "valor": 100 }]
}

Com Prefer: wait=15, a resposta chega na mesma chamada: a NFC-e autorizada, a chave de acesso, o qr_code, a url_consulta, o troco calculado e o horário limite para cancelar em cancelavel_ate. Antes de reservar número, a Sudrel confere as regras do modelo 65 e os limites do estado; uma venda fora da regra volta com o campo e a regra, sem gastar número.

Cartão e Pix levam os dados do pagamento. Sem integração com a maquininha, a nota sai como pagamento sem integração; com TEF, informe o CNPJ da credenciadora e o código de autorização.

3. O cupom

GET /v1/nfce/{id}/danfe devolve o DANFE NFC-e de 80 mm em PDF. Com ?formato=texto, o mesmo cupom em 48 colunas, para a impressora térmica imprimir direto; o QR Code vai como texto, e a impressora o desenha com o comando dela. Se o consumidor quiser por e-mail, POST /v1/nfce/{id}/envio manda o cupom e o XML.

4. A rede caiu no meio da venda

Na NFC-e a Idempotency-Key é obrigatória. O PDV repete o pedido com a mesma chave e recebe a mesma nota, nunca uma segunda. E se quem se perdeu foi a resposta da SEFAZ, a Sudrel consulta a chave de acesso antes de qualquer reenvio: uma nota que já foi autorizada é recuperada, não emitida outra vez.

5. O cliente desistiu

POST /v1/nfce/{id}/cancelamento, com uma justificativa de 15 a 255 caracteres, até o cancelavel_ate. Na Bahia são 30 minutos (as regras da Bahia). O cancelamento tem fila própria, separada das vendas, para não esperar atrás de um pico de movimento.

Testar antes de vender

A chave de teste (sdr_test_) emite de verdade na homologação da SEFAZ, com o certificado da empresa e sem valor fiscal, e tem os caixas dela. Os SDKs de Node.js e PHP já trazem nfce e caixas, e geram a Idempotency-Key sozinhos.

Perguntas frequentes

O que acontece se a rede do caixa cair no meio da venda?

Repita a chamada com a mesma Idempotency-Key, que na NFC-e é obrigatória: a resposta é a mesma nota, nunca uma segunda. Se a resposta da SEFAZ se perdeu, a Sudrel consulta a chave antes de reenviar.

A impressora térmica imprime o PDF?

Muitas imprimem, mas o caminho mais simples é o cupom em texto de 48 colunas, que a API também devolve. O QR Code vai como texto, e a impressora o desenha com o comando dela.

O passo a passo completo, com todos os campos, está no guia de emissão de NFC-e. E a visão geral do produto, na página da API de NFC-e.