Emissão de NFC-e

Todas as UFs. A emissão funciona em qualquer estado: a Sudrel prepara a UF da sua empresa em minutos, a partir do cadastro, sem ação sua. Onde o texto cita a Bahia, é a UF dos exemplos e das regras já detalhadas.

A NFC-e é a nota do varejo: venda presencial a consumidor final, dentro da UF. Na Sudrel ela é outro modelo da mesma emissão da NF-e: mesmo certificado, mesmo leiaute 4.00, mesmas garantias (o número é reservado na mesma transação que cria a nota, a chave nunca muda, e uma nota que pode ter chegado à SEFAZ só se resolve consultando a chave). A sandbox (sdr_test_) emite de verdade na homologação da SEFAZ, sem valor fiscal; a chave sdr_live_ emite na produção.

Antes da primeira NFC-e

1. Caixa. Toda NFC-e sai de um caixa, e cada caixa tem a sua série (0 a 889, única na empresa). Cadastre em POST /v1/caixas com o identificador que o seu sistema usa (LOJA1-CX02). O sandbox tem os caixas dele.
2. Produtos e perfil fiscal. No modo calcular (o padrão da NFC-e) a Sudrel calcula os tributos pelo produto cadastrado; veja Produtos e motor fiscal.
3. CSC (opcional). O QR Code sai na versão 3, que não usa o Código de Segurança do Contribuinte. Se a SEFAZ da UF recusar a versão 3 (rejeição 407), a Sudrel refaz a nota na versão 2, que precisa do CSC: cadastre-o em PUT /v1/nfce/csc/{empresa_id} (id_csc e csc, como a SEFAZ entregou). O CSC é guardado criptografado e nunca volta em resposta nem em log.
4. Prontidão. GET /v1/nfce/prontidao/{empresa_id} diz o que falta, item por item. A lista de itens cresce com as próximas fases.

A venda

POST /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 }]
}

A resposta vem na mesma chamada: 201 com a NFC-e autorizada, o qr_code, a url_consulta, o troco (o que os pagamentos passam do total, calculado) e os links do cupom. A Idempotency-Key é obrigatória: o caixa repete o pedido quando a rede cai, e a Sudrel devolve a mesma nota em vez de emitir outra.

• modo: calcular (padrão), informado (os tributos de cada item vêm prontos, como na NF-e) ou conferir.
• consumidor: { "documento", "nome", "email" }, opcional. Na BA é obrigatório a partir de R$ 500,00 (RICMS/BA, art. 107-D, § 2º): sem ele, a venda volta 422 nfce_consumidor_obrigatorio antes de qualquer número.
• Cartão e Pix levam o grupo do cartão: sem cartao, sai como POS sem integração; com "cartao": { "integrado": true, "cnpj_credenciadora", "autorizacao" }, o TEF.

A Sudrel confere as regras do modelo 65 antes de enviar e responde com o campo e a regra: CFOP (5101, 5102, 5103, 5104, 5115, 5405, 5656, 5667), CST do ICMS (00, 20, 40, 41, 60) e CSOSN (102, 103, 300, 400, 500) com o CFOP que combina, sem IPI, sem frete e só venda presencial.

Cupom

GET /v1/nfce/{id}/danfe devolve o DANFE NFC-e de 80 mm em PDF, no leiaute do Manual de Padrões DANFE NFC-e e QR Code (v6.0), com o QR Code e a mensagem de homologação quando for o caso. Com ?formato=texto, o mesmo cupom em 48 colunas para impressora térmica (o QR Code vai como o texto do qr_code, que a impressora desenha). POST /v1/nfce/{id}/envio manda o cupom e o XML por e-mail ao consumidor.

Cancelamento

POST /v1/nfce/{id}/cancelamento, com justificativa de 15 a 255 caracteres, até cancelavel_ate: 30 minutos depois da autorização na BA (RICMS/BA, art. 107-H, I). Fora do prazo a resposta é 422 cancelamento_fora_do_prazo, com o caminho que a legislação da UF dá; na BA não existe cancelamento extemporâneo de NFC-e. O cancelamento tem fila própria, separada da emissão: um pico de vendas não segura um cancelamento.

Estados e eventos

Os mesmos estados da NF-e (autorizada, rejeitada, denegada, cancelada, descartada, transmitindo, aguardando_confirmacao). Webhooks: NFCE_AUTORIZADA, NFCE_REJEITADA, NFCE_DENEGADA, NFCE_CANCELADA, NFCE_DESCARTADA, NFCE_DESCARTE_PROXIMO e NFCE_ENVIO_PAUSADO, com a NFC-e inteira em dados. As listas de estados e de eventos crescem: trate valor desconhecido sem quebrar.

NFC-e e NF-e são separadas na API: GET /v1/nfe não lista NFC-e, e GET /v1/nfce/{id} não encontra NF-e, mesmo com o id certo. A referencia e a Idempotency-Key são únicas por modelo.

Fontes: MOC 7.0 (Anexo I, regras do modelo 65), Manual de Padrões DANFE NFC-e e QR Code v6.0, NT 2025.001 v1.03 (QR Code versão 3), RICMS/BA (Decreto 13.780/2012).