NFC-e
Emisión de NFC-e (modelo 65) en nombre de comercios: flujo de integración, elección entre NFC-e y NF-e, configuración de la empresa, diferencias estatales e impresión del cupón.
Visión general y flujo de integración
La NFC-e (modelo 65, Nota Fiscal de Consumidor Eletrônica) es el comprobante electrónico del comercio minorista en Brasil, usado en ventas dentro del estado al consumidor final: venta en la tienda, delivery y entrega en la misma ciudad, y venta presencial fuera de la tienda. Usa el mismo diseño de la NF-e, pero los puntos de autorización, el QR Code, el plazo de cancelación y las reglas de validación son otros. El registro de la empresa, el certificado y el webhook son los mismos de la NF-e.
| Paso | Endpoint | Observación |
|---|---|---|
| 1 Registrar empresa | POST /openapi/v2/empresas | Igual que la NF-e, más el bloque opcional emissaoNFeConsumidor que habilita la NFC-e; reenvíe con id para actualizar |
| 2 Enviar certificado | POST /openapi/v1/empresas/{empresaId}/certificadoDigital | Igual que la NF-e, el mismo certificado A1 |
| 3 Registrar webhook | POST /openapi/v1/webhooks | Registre el webhook de nuevo con los eventos nfce.* en eventos; los resultados van a la misma dirección |
| 4 Emitir | POST /openapi/v2/empresas/{empresaId}/nfce | Asíncrono por defecto; la caja puede usar el modo síncrono para tener el resultado en el momento |
| 5 Consultar | GET /openapi/v2/empresas/{empresaId}/nfce/{nfceId} | Estado, QR Code, enlaces del cupón y del XML |
| 6 Cancelar | POST .../nfce/{nfceId}/cancelar | Hasta 30 minutos después de la autorización |
| 7 Cancelar por sustitución | POST .../nfce/{nfceId}/cancelar-substituicao | Cancela la nota normal duplicada por una nota de contingencia offline, hasta 168 horas |
La autenticación es la misma de la NF-e; vea Autenticación.
Requisitos previos
- Empresa aprobada y con certificado utilizable; si no,
10022002. - NFC-e habilitada para el ambiente actual mediante el bloque
emissaoNFeConsumidor; si no,10022001. - La empresa tiene inscripción estatal y la NFC-e está habilitada en su estado. La mayoría de los estados la habilita automáticamente a quien tiene IE; SP la habilita por establecimiento, PR exige una solicitud a la SEFAZ antes de producción, y TO, RN y GO exigen antes la habilitación para NF-e.
ambienteEmissaodebe ser igual al ambiente actual de la empresa; si no,10022003.
NFC-e o NF-e
| Situación | Emita |
|---|---|
| Venta en la tienda a persona física | NFC-e |
| Delivery, entrega en la ciudad o el estado a persona física | NFC-e (consumidor identificado con dirección), o NF-e |
| Pedido por internet enviado a otro estado | Solo NF-e |
| Comprador contribuyente del ICMS | Solo NF-e |
| Nota por encima de R$ 200.000 | Solo NF-e |
| Devolución, complementaria, ajuste o nota referenciada | Solo NF-e |
La plataforma no convierte por su cuenta una solicitud fuera de las reglas en NF-e; devuelve 10022004 con el motivo.
Registro de la empresa: bloque emissaoNFeConsumidor
El cuerpo de Registrar empresa gana un bloque opcional; los demás campos no cambian:
"emissaoNFeConsumidor": {"ambienteProducao": {"sequencialNFe": 1,"serieNFe": "1","csc": { "id": "000001", "codigo": "A1B2C3D4E5F6A7B8C9D0E1F2A3B4C5D6" }}}
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
ambienteProducao | object | Sí | Serie y CSC. La serie vale para homologación y producción; el CSC solo para producción |
sequencialNFe | integer | Sí | Próximo número. La plataforma numera en secuencia desde él; la numeración solo sube, y un valor menor en la actualización mantiene el número actual |
serieNFe | string | Sí | Serie de la NFC-e. De 1 a 3 dígitos, distinta de la serie de la NF-e, y 890 a 899 están reservadas por el fisco; se recomienda una serie por caja o canal de venta |
csc | object | No | Código de seguridad (CSC). Solo lo usa el QR Code v2, y solo tiene efecto en producción; la plataforma usa v3 por defecto y es ella quien pasa la empresa a v2, algo que la API abierta no permite; si recibe 10022009, contacte a la plataforma |
csc.id | string | Sí | Identificador del CSC. De 1 a 6 dígitos, obtenido junto con el código en el portal de la SEFAZ |
csc.codigo | string | Sí | Código del CSC. De 16 a 36 letras, dígitos o guiones; se guarda cifrado y nunca se devuelve |
- Enviar el bloque habilita la NFC-e y la respuesta del registro trae
nfceHabilitado=true. La homologación no necesita configuración propia: la misma serie sirve a los dos ambientes. - Actualización: reenvíe con el
idde la empresa para sobrescribir el bloque. Al cambiar solo el CSC, envíesequencialNFeyserieNFecomo están; la numeración nunca baja. - El CSC se genera en el portal de la SEFAZ. Tras revocar un código en el portal, actualícelo aquí, o la SEFAZ rechaza la emisión (462 / 463).
Endpoints
| Endpoint | Uso |
|---|---|
| Emitir NFC-e | La aceptación asíncrona devuelve HTTP 200 sin cuerpo; el modo síncrono devuelve el resultado o 202; idempotente por id |
| Consultar NFC-e | Estado, QR Code, enlaces del cupón y del XML, eco de la emisión |
| Cancelar NFC-e | Hasta 30 minutos después de la autorización, asíncrono |
| Cancelar por sustitución | Cancela la nota normal duplicada por una offline, hasta 168 horas, asíncrono |
Estados y webhooks
| Estado | Significado | Evento de webhook |
|---|---|---|
AguardandoAutorizacao | Aceptada, esperando a la SEFAZ | Ninguno |
Autorizada | Autorizada | nfce.authorized |
Negada | Rechazada por la SEFAZ, o falló en el procesamiento de la plataforma | nfce.rejected |
Cancelada | Cancelada | nfce.canceled |
ContingenciaPendente | Emitida offline con la SEFAZ caída, esperando transmisión | nfce.contingency_issued |
Cuando la SEFAZ rechaza una cancelación la nota sigue Autorizada y llega nfce.cancel_rejected. Cuando la nota offline se autoriza llega de nuevo nfce.authorized; si la transmisión se rechaza, llega nfce.rejected. La carga es la misma de la NF-e, con tipo igual a NFC-e y el contenido del QR Code en nfeQrCode; vea Webhooks. Estos eventos deben suscribirse explícitamente en eventos al registrar el webhook.
Contingencia offline
Con la SEFAZ caída y el estado permitiéndolo, la plataforma emite la NFC-e offline (el dígito 35 de la clave es 9) con estado ContingenciaPendente; el cupón ya puede imprimirse y entregarse. La plataforma la transmite cuando la SEFAZ vuelve; si la misma venta también tiene una nota normal autorizada, la plataforma cancela la normal por sustitución por su cuenta. Para casos especiales use Cancelar por sustitución.
Lo anterior solo cubre la SEFAZ caída con la tienda todavía conectada a la plataforma. Cuando la propia tienda se queda sin red, la solicitud no llega a la plataforma y la nota debe emitirse en la propia caja; vea NFC-e offline.
Diferencias estatales
Diferencias conocidas, sujetas a cambios en la legislación estatal. El límite de identificación, la prohibición de entrega en SC y la prohibición de comprador identificado por CNPJ en GO y SC los verifica la plataforma en la aceptación, según el estado del emisor, y devuelven 10022004; el resto lo verifica la SEFAZ en la autorización y termina como Negada, así que respételo antes de enviar:
| Estado | Límite de identificación | Venta con entrega | Otros |
|---|---|---|---|
| SP | R$ 10.000 | Permitida, dentro de SP | |
| MG | R$ 10.000 | Solo establecimientos minoristas | Un CSC para homologación y producción |
| RJ | R$ 2.000 | Permitida, con transportista | Cancelación extemporánea paga en la SEFAZ |
| PR | R$ 10.000; entrega siempre identificada | Permitida, en el estado | |
| RS | R$ 10.000; mayorista y minorista debe identificar | Permitida | |
| SC | R$ 10.000; el comprador no puede identificarse por CNPJ | Prohibida | |
| ES | R$ 10.000 | Solo restaurantes, farmacias y florerías | Identificador del CSC fijo 000001 |
| GO | R$ 10.000, solo CPF | Permitida | Comprador identificado por CNPJ exige NF-e |
| MT | R$ 1.000 | Solo en la misma ciudad | Cancelación extemporánea paga en la SEFAZ |
| TO | R$ 3.000, con nombre y dirección | Solo en el estado | |
| PE | R$ 5.000 | Permitida | |
| BA, AL, PB | R$ 500 | Permitida | Entrega en AL exige cupón impreso |
| Demás estados | R$ 10.000 | Permitida, en el estado |
Impresión del cupón
- El enlace del cupón en la consulta y en los webhooks es un PDF térmico de 80 mm que puede ir directo a la impresora.
- Si arma el cupón por su cuenta, incluya todos los datos oficiales, codifique
qrCodecomo QR Code e imprimaurlConsultay la clave de acceso. - Con el acuerdo del consumidor puede no imprimirse y enviarse la clave o el cupón electrónico; RJ, ES y las entregas en AL exigen impresión.
- El cupón de homologación lleva «EMITIDA EM AMBIENTE DE HOMOLOGAÇÃO – SEM VALOR FISCAL», y en homologación la plataforma reemplaza la descripción del primer ítem por el texto oficial; no hay nada que hacer de su lado.
Lista de pruebas
- Registre la empresa con
emissaoNFeConsumidor; la respuesta traenfceHabilitado=true. - Envíe el certificado y registre el webhook de nuevo con los eventos
nfce.*eneventos. - Emita el ejemplo de la página de emisión en modo síncrono; llega
AutorizadaconqrCodeylinkDanfe, y descargue el PDF del cupón. - Envíe el mismo
idde nuevo; vuelve la misma nota, con el mismo número. - Emita el ejemplo de entrega en modo asíncrono; llega un webhook con
tipo=NFC-eynfeStatus=Autorizada. - Cancele la nota del paso 3 dentro de 30 minutos; la consulta muestra
Canceladay llega el webhook de cancelación. - Casos negativos:
presencaConsumidor=OperacaoPelaInternet, entrega sinclientey CFOP 6102 devuelven10022004; cancelar más de 30 minutos después de la autorización devuelve10022007.
