Emisión de NFC-e

Todas las UF. La emisión funciona en cualquier estado: Sudrel prepara la UF de tu empresa en minutos, a partir del registro, sin acción tuya. Donde el texto cita Bahia, es la UF de los ejemplos y de las reglas ya detalladas.

La NFC-e es la nota del comercio minorista: venta presencial a consumidor final, dentro de la UF. En Sudrel es otro modelo de la misma emisión de la NF-e: mismo certificado, mismo diseño 4.00, mismas garantías (el número se reserva en la misma transacción que crea la nota, la clave nunca cambia, y una nota que pudo haber llegado a la SEFAZ solo se resuelve consultando la clave). El sandbox (sdr_test_) emite de verdad en la homologación de la SEFAZ, sin valor fiscal; la clave sdr_live_ emite en producción.

Antes de la primera NFC-e

1. Caja. Toda NFC-e sale de una caja, y cada caja tiene su serie (0 a 889, única en la empresa). Regístrala en POST /v1/caixas con el identificador que usa tu sistema (LOJA1-CX02). El sandbox tiene sus propias cajas.
2. Productos y perfil fiscal. En modo calcular (el predeterminado de la NFC-e) Sudrel calcula los tributos por el producto registrado; consulta Productos y motor fiscal.
3. CSC (opcional). El código QR sale en la versión 3, que no usa el Código de Segurança do Contribuinte. Si la SEFAZ de la UF rechaza la versión 3 (rechazo 407), Sudrel rehace la nota en la versión 2, que necesita el CSC: regístralo en PUT /v1/nfce/csc/{empresa_id} (id_csc y csc, como los entregó la SEFAZ). El CSC se guarda cifrado y nunca vuelve en una respuesta ni en un log.
4. Preparación. GET /v1/nfce/prontidao/{empresa_id} indica qué falta, ítem por ítem. La lista de ítems crece con las próximas fases.

La venta

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

La respuesta viene en la misma llamada: 201 con la NFC-e autorizada, el qr_code, la url_consulta, el troco (lo que los pagos exceden del total, calculado) y los enlaces del cupón. La Idempotency-Key es obligatoria: la caja repite la solicitud cuando la red cae, y Sudrel devuelve la misma nota en lugar de emitir otra.

• modo: calcular (predeterminado), informado (los tributos de cada ítem vienen listos, como en la NF-e) o conferir.
• consumidor: { "documento", "nome", "email" }, opcional. En BA es obligatorio a partir de R$ 500,00 (RICMS/BA, art. 107-D, § 2º): sin él, la venta vuelve con 422 nfce_consumidor_obrigatorio antes de cualquier número.
• Tarjeta y Pix llevan el grupo de la tarjeta: sin cartao, sale como POS sin integración; con "cartao": { "integrado": true, "cnpj_credenciadora", "autorizacao" }, el TEF.

Sudrel verifica las reglas del modelo 65 antes de enviar y responde con el campo y la regla: CFOP (5101, 5102, 5103, 5104, 5115, 5405, 5656, 5667), CST del ICMS (00, 20, 40, 41, 60) y CSOSN (102, 103, 300, 400, 500) con el CFOP que corresponde, sin IPI, sin flete y solo venta presencial.

Cupón

GET /v1/nfce/{id}/danfe devuelve el DANFE NFC-e de 80 mm en PDF, en el diseño del Manual de Padrões DANFE NFC-e e QR Code (v6.0), con el código QR y el mensaje de homologación cuando corresponde. Con ?formato=texto, el mismo cupón en 48 columnas para impresora térmica (el código QR va como el texto del qr_code, que la impresora dibuja). POST /v1/nfce/{id}/envio envía el cupón y el XML por e-mail al consumidor.

Cancelación

POST /v1/nfce/{id}/cancelamento, con justificativa de 15 a 255 caracteres, hasta cancelavel_ate: 30 minutos después de la autorización en BA (RICMS/BA, art. 107-H, I). Fuera del plazo la respuesta es 422 cancelamento_fora_do_prazo, con el camino que da la legislación de la UF; en BA no existe cancelación extemporánea de NFC-e. La cancelación tiene su propia cola, separada de la emisión: un pico de ventas no retrasa una cancelación.

Estados y eventos

Los mismos estados de la NF-e (autorizada, rejeitada, denegada, cancelada, descartada, transmitindo, aguardando_confirmacao). Webhooks: NFCE_AUTORIZADA, NFCE_REJEITADA, NFCE_DENEGADA, NFCE_CANCELADA, NFCE_DESCARTADA, NFCE_DESCARTE_PROXIMO y NFCE_ENVIO_PAUSADO, con la NFC-e completa en dados. Las listas de estados y de eventos crecen: trata los valores desconocidos sin fallar.

NFC-e y NF-e están separadas en la API: GET /v1/nfe no lista NFC-e, y GET /v1/nfce/{id} no encuentra NF-e, aun con el id correcto. La referencia y la Idempotency-Key son únicas por modelo.

Fuentes: MOC 7.0 (Anexo I, reglas del modelo 65), Manual de Padrões DANFE NFC-e e QR Code v6.0, NT 2025.001 v1.03 (QR Code versión 3), RICMS/BA (Decreto 13.780/2012).