NF-e

Visión general

Los endpoints de NF-e emiten facturas de producto (NF-e) en nombre de una empresa registrada: la emisión se acepta de inmediato y se autoriza de forma asíncrona en la SEFAZ, el resultado llega por webhook o consulta, y una factura autorizada puede cancelarse o complementarse con cartas de corrección (CC-e).

Endpoints

Antes de emitir, la empresa debe estar registrada mediante Registrar empresa, tener el certificado vinculado mediante Vincular certificado, y su aplicación debería tener una URL de callback registrada mediante Registrar webhook. El empresaId devuelto en el registro es la variable de ruta de todos los endpoints siguientes.

Toda solicitud lleva las tres cabeceras de firma descritas en Autenticación; el path firmado incluye el prefijo /openapi y las variables de ruta (empresaId / nfeId).

Semántica de los estados

Los resultados autorizado y denegado también se entregan en su URL de callback; los formatos de carga están en Webhooks.

Estado de la empresa y requisitos previos

El endpoint de registro coloca la empresa en la cola de aprobación de la plataforma; la empresa puede emitir facturas solo después de que operaciones la apruebe y el certificado esté vinculado. Emitir antes de la aprobación devuelve el error 10004004 (empresa no habilitada para emitir). Confirme el avance de la aprobación con operaciones de la plataforma.

Toda empresa tiene un entorno actual (prueba Homologacao / producción Producao); las empresas recién registradas comienzan en prueba, y el cambio a producción es una acción de operaciones. El ambienteEmissao de la solicitud de emisión debe corresponder al entorno actual de la empresa; la discrepancia devuelve 10004030, una protección estricta contra facturas de prueba emitidas en producción. Vea Entornos.

Idempotencia y reenvío

Las solicitudes de emisión aceptadas devuelven HTTP 200 sin cuerpo y entran en el flujo asíncrono de emisión; el resultado llega por webhook o por el endpoint de consulta. Reenviar el mismo id reutiliza la tarea original; si el intento anterior fue denegado (Negada), reenviar el mismo id con los campos corregidos emite de nuevo con el nuevo payload, sin necesidad de otro id. Cambiar campos clave como el destinatario mientras el intento anterior sigue en proceso o ya fue autorizado se rechaza con 10004032.

Alcance

Lista de verificación de integración

1. Registre una empresa → 200 + empresaId; registre el mismo CNPJ de nuevo → 400 + 10003002.
2. Vincule el certificado → 200 sin cuerpo; contraseña incorrecta → 400 + CER0005.
3. Registre el webhook → 200 + webHookId.
4. Tras la aprobación, emita con ambienteEmissao=Homologacao → 200 sin cuerpo; luego consulte → AguardandoAutorizacao pasa a Autorizada, y linkDanfe / linkDownloadXml se descargan correctamente.
5. Reciba el callback de autorización: la cabecera token es igual al valor registrado y la carga tiene nfeStatus=Autorizada.
6. Casos negativos: ambienteEmissao=Producao → 400 + 10004030; presencaConsumidor=OperacaoPresencial → 400 + 10004031.
7. Cancele la factura recién autorizada → 200; consulte de nuevo → Cancelada; cancele un id desconocido → 404 + NFe0001.
8. Rutas de fallo: sign incorrecto → 401 + 10009003; endpoint no suscrito → 403 + 10009005.

Solución de problemas