TF Fiscal
Documentación

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.

PasoEndpointObservación
1 Registrar empresaPOST /openapi/v2/empresasIgual que la NF-e, más el bloque opcional emissaoNFeConsumidor que habilita la NFC-e; reenvíe con id para actualizar
2 Enviar certificadoPOST /openapi/v1/empresas/{empresaId}/certificadoDigitalIgual que la NF-e, el mismo certificado A1
3 Registrar webhookPOST /openapi/v1/webhooksRegistre el webhook de nuevo con los eventos nfce.* en eventos; los resultados van a la misma dirección
4 EmitirPOST /openapi/v2/empresas/{empresaId}/nfceAsíncrono por defecto; la caja puede usar el modo síncrono para tener el resultado en el momento
5 ConsultarGET /openapi/v2/empresas/{empresaId}/nfce/{nfceId}Estado, QR Code, enlaces del cupón y del XML
6 CancelarPOST .../nfce/{nfceId}/cancelarHasta 30 minutos después de la autorización
7 Cancelar por sustituciónPOST .../nfce/{nfceId}/cancelar-substituicaoCancela 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.
  • ambienteEmissao debe ser igual al ambiente actual de la empresa; si no, 10022003.

NFC-e o NF-e

SituaciónEmita
Venta en la tienda a persona físicaNFC-e
Delivery, entrega en la ciudad o el estado a persona físicaNFC-e (consumidor identificado con dirección), o NF-e
Pedido por internet enviado a otro estadoSolo NF-e
Comprador contribuyente del ICMSSolo NF-e
Nota por encima de R$ 200.000Solo NF-e
Devolución, complementaria, ajuste o nota referenciadaSolo 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:

json
"emissaoNFeConsumidor": {
"ambienteProducao": {
"sequencialNFe": 1,
"serieNFe": "1",
"csc": { "id": "000001", "codigo": "A1B2C3D4E5F6A7B8C9D0E1F2A3B4C5D6" }
}
}
CampoTipoObligatorioDescripción
ambienteProducaoobjectSíSerie y CSC. La serie vale para homologación y producción; el CSC solo para producción
sequencialNFeintegerSí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
serieNFestringSí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
cscobjectNoCó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.idstringSíIdentificador del CSC. De 1 a 6 dígitos, obtenido junto con el código en el portal de la SEFAZ
csc.codigostringSí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 id de la empresa para sobrescribir el bloque. Al cambiar solo el CSC, envíe sequencialNFe y serieNFe como 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

EndpointUso
Emitir NFC-eLa aceptación asíncrona devuelve HTTP 200 sin cuerpo; el modo síncrono devuelve el resultado o 202; idempotente por id
Consultar NFC-eEstado, QR Code, enlaces del cupón y del XML, eco de la emisión
Cancelar NFC-eHasta 30 minutos después de la autorización, asíncrono
Cancelar por sustituciónCancela la nota normal duplicada por una offline, hasta 168 horas, asíncrono

Estados y webhooks

EstadoSignificadoEvento de webhook
AguardandoAutorizacaoAceptada, esperando a la SEFAZNinguno
AutorizadaAutorizadanfce.authorized
NegadaRechazada por la SEFAZ, o falló en el procesamiento de la plataformanfce.rejected
CanceladaCanceladanfce.canceled
ContingenciaPendenteEmitida offline con la SEFAZ caída, esperando transmisiónnfce.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:

EstadoLímite de identificaciónVenta con entregaOtros
SPR$ 10.000Permitida, dentro de SP
MGR$ 10.000Solo establecimientos minoristasUn CSC para homologación y producción
RJR$ 2.000Permitida, con transportistaCancelación extemporánea paga en la SEFAZ
PRR$ 10.000; entrega siempre identificadaPermitida, en el estado
RSR$ 10.000; mayorista y minorista debe identificarPermitida
SCR$ 10.000; el comprador no puede identificarse por CNPJProhibida
ESR$ 10.000Solo restaurantes, farmacias y floreríasIdentificador del CSC fijo 000001
GOR$ 10.000, solo CPFPermitidaComprador identificado por CNPJ exige NF-e
MTR$ 1.000Solo en la misma ciudadCancelación extemporánea paga en la SEFAZ
TOR$ 3.000, con nombre y direcciónSolo en el estado
PER$ 5.000Permitida
BA, AL, PBR$ 500PermitidaEntrega en AL exige cupón impreso
Demás estadosR$ 10.000Permitida, 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 qrCode como QR Code e imprima urlConsulta y 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

  1. Registre la empresa con emissaoNFeConsumidor; la respuesta trae nfceHabilitado=true.
  2. Envíe el certificado y registre el webhook de nuevo con los eventos nfce.* en eventos.
  3. Emita el ejemplo de la página de emisión en modo síncrono; llega Autorizada con qrCode y linkDanfe, y descargue el PDF del cupón.
  4. Envíe el mismo id de nuevo; vuelve la misma nota, con el mismo número.
  5. Emita el ejemplo de entrega en modo asíncrono; llega un webhook con tipo=NFC-e y nfeStatus=Autorizada.
  6. Cancele la nota del paso 3 dentro de 30 minutos; la consulta muestra Cancelada y llega el webhook de cancelación.
  7. Casos negativos: presencaConsumidor=OperacaoPelaInternet, entrega sin cliente y CFOP 6102 devuelven 10022004; cancelar más de 30 minutos después de la autorización devuelve 10022007.