> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fire.rest/llms.txt
> Use this file to discover all available pages before exploring further.
# order.invoiced
> La autoridad fiscal autorizó el documento (factura electrónica) de una orden vía tu proveedor fiscal — todos los países.
Estás viendo el contrato **actual (v1.2)** de `order.invoiced`. **v1.2 agrega** `data.fiscalRepresentation`: la numeración fiscal que el punto de venta obtuvo antes de inyectar la orden. Viaja **siempre**: en `null` cuando no se intentó numerar, y con contenido cuando sí —`numberingStatus` dice cómo terminó—. Que traiga contenido **no** significa que el comprobante esté autorizado. Solo aditivo — nada de lo que ya leías cambió.
El bloque lleva el documento fiscal **vigente** de la orden: los campos que significan lo mismo en todo país arriba, los identificadores del ente dentro de `countryData` con el vocabulario de su país, y los documentos anteriores en `history`. Cuando una anulación numera, la nota de crédito pasa arriba y la factura baja al histórico — con `compensates` apuntando a ella.
**v1.1 agregó** `data.policy.deferredPayment` (¿esta orden puede trabajarse antes del pago?) y `data.lastKnown` (estado orientativo de cocina/fiscal), más el evento nuevo [`order.opened`](/es/events/order-opened). Sigue siendo válido: v1.2 solo suma un bloque.
El contrato **v1** está **deprecado** — se mantiene como referencia histórica. Abrilo acá: [`order.invoiced` — v1](/es/events-v1/order-invoiced).
El contrato **v0** está **deprecado** — se mantiene solo como referencia histórica. Ábrelo acá: [order-completed — v0](/es/events-v0/order-completed).
`order.invoiced` dispara cuando la **autoridad fiscal del país** autoriza el documento fiscal asociado a una orden — SEFAZ en Brasil, SRI en Ecuador, DIAN en Colombia, AFIP en Argentina, SII en Chile, SENIAT en Venezuela. Lo emite el pipeline fiscal de Fire, que se integra con tu proveedor fiscal como proveedor de documentos.
Este evento es **separado de** [`order.completed`](/es/events/order-completed): la orden se paga primero (`order.completed`), después Fire pide la emisión fiscal vía tu proveedor fiscal, y `order.invoiced` dispara solo cuando la autoridad fiscal devuelve la autorización.
## Condición de disparo
Fire emite `order.invoiced` una vez por documento fiscal, la primera vez que **todo** lo siguiente es verdadero:
* La orden está en una tienda con facturación fiscal habilitada (`storeFiscalConfig.enabled === true`)
* Se emitió un documento fiscal a tu proveedor fiscal
* tu proveedor fiscal reporta que la autoridad fiscal autorizó el documento (el `status` transiciona a `authorized`; en Brasil esto corresponde al código `cStat` de autorización SEFAZ)
| | |
| ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Cobertura | **Todos los países** — Brasil (NFC-e/NF-e vía SEFAZ) y CO/EC/CL/AR/VE vía el [callback fiscal genérico](/es/api-reference/fiscal-callback). El país viaja en `fiscal.countryCode`, ya no en el nombre del evento |
| Tipos de documento | Varían por país — `nfce`/`nfe` (BR), factura electrónica (CO/EC/CL/AR/VE). Llega en `fiscal.docSubtype` |
| Llave de idempotencia | `event.id` |
| Dispara más de una vez | No, salvo en reintentos |
| Latencia relativa a `order.completed` | Usualmente segundos; puede ser minutos si la autoridad fiscal está degradada |
## Qué hay en `trigger.data`
Mismo snapshot V4 que [`order.completed`](/es/events/order-completed) más un bloque top-level **`fiscal`** con las referencias del documento autorizado. **Los campos varían por país** — abajo se muestra Brasil (`chaveAcesso`, `protocolo`); otros países llevan sus identificadores propios (`cufe` en CO, `claveAcceso` en EC, `cae` en AR, etc.). Ver el [callback fiscal genérico](/es/api-reference/fiscal-callback) para el contrato por país.
El `status` de la orden permanece `"COMPLETED"` y `paymentStatus` permanece `"SUCCEEDED"` — la autorización fiscal no cambia el status de orden.
## Ejemplo — payload real de producción (BR, sanitizado)
```json theme={null}
{
"event": {
"id": "...",
"type": "order.invoiced",
"createdAt": "2026-05-06T01:23:11.000Z"
},
"data": {
"orderId": "8017b54c-af0c-4246-a60a-a0d4ae9a0fef",
"orderCode": "OC-br-001",
"businessDayDate": "2026-03-31",
"externalOrderId": "8017b54c-af0c-4246-a60a-a0d4ae9a0fef",
"status": "COMPLETED",
"paymentStatus": "SUCCEEDED",
"createdAt": "2026-05-06T01:22:56.488Z",
"store": { /* igual que order.completed — incluye storeFiscalConfig con CNPJ, legalName */ },
"client": { /* ... */ },
"payments": { /* ... — incluye payments.metadata.fiscal con agregados */ },
"orderLines": [ /* ... */ ],
"fulfillment": { /* ... */ },
"device": { /* ... */ },
"channel": { /* ... */ },
"operator": { /* ... */ },
"kds": { /* ... */ },
"marketing": null,
"metadata": {},
"fiscal": {
"status": "authorized",
"docSubtype": "nfce",
"chaveAcesso": "41201008187168000160558050010000131609769080",
"numero": "1000013",
"protocolo": "141200000956123",
"providerDocId": "69fa97fe427d1240856e1282",
"pdfUrl": "https://api.fiscal-provider.example/nfce/69fa97fe427d1240856e1282/pdf",
"xmlUrl": "https://api.fiscal-provider.example/nfce/69fa97fe427d1240856e1282/xml",
"dataAutorizacao": "2026-05-06T01:23:10.991Z",
"cStat": null
}
},
"_meta": { "executionId": "...", "flowId": "...", "attempt": "1" }
}
```
## Referencia de `data.fiscal`
Referencias del documento autorizado por SEFAZ.
Status del documento. Para este evento, siempre `"authorized"`. Otros valores que puedes ver en tu proveedor fiscal (`pending`, `processing`, `rejected`, `denied`) **no** disparan `order.invoiced` — solo el estado terminal autorizado.
Tipo de documento. Valores: `nfce` (NFC-e — factura de consumidor, B2C) o `nfe` (NF-e — factura de negocio, B2B).
Chave de acesso SEFAZ de 44 dígitos. Codifica UF, año/mes, CNPJ, modelo, serie, número, tipo de emisión y un dígito verificador. Úsala para reconciliar con portales SEFAZ.
Número de documento asignado por el pipeline de emisión de Fire. Secuencial por `(cnpj, serie, docSubtype)`.
Serie del documento. Puede ser `null` para algunas configuraciones; la serie está codificada en `chaveAcesso` igualmente.
Número de protocolo de autorización SEFAZ. Requerido para cualquier operación SEFAZ subsecuente (cancelación, corrección).
ID interno del documento en tu proveedor fiscal. Úsalo para consultar las APIs de tu proveedor fiscal directamente (p. ej. obtener el XML canónico).
URL para descargar el PDF del documento (DANFE para NF-e, DANFCE para NFC-e). Hosteado por tu proveedor fiscal; firmado/de vida corta en producción, durable en sandbox.
URL para descargar el XML canónico SEFAZ. Mismo hosting que `pdfUrl`.
Timestamp ISO 8601 UTC de la autorización SEFAZ (cuando SEFAZ estampó el protocolo).
Código de status raw de SEFAZ. Puede ser `null` cuando el proveedor no lo expone (tu proveedor fiscal lo oculta para algunos flows de consumidor). Cuando está presente, `100` (NF-e) o `100` (NFC-e) indican autorización.
## Dónde viven los totales fiscales
Los valores agregados fiscales (vBC, vNF, vICMS, etc.) **no están** dentro de `data.fiscal` — están en `data.payments.metadata.fiscal`, el mismo lugar donde [`order.completed`](/es/events/order-completed#datos-fiscales) los lleva. `order.invoiced` no los duplica; trata el snapshot de la orden como la única fuente de verdad para los agregados monetarios.
La clasificación por línea (NCM, CFOP, CSOSN, fiscalCategoryCode) vive en `data.orderLines[n].metadata.fiscal`. Igual que en `order.completed`.
El bloque `data.store.storeFiscalConfig` lleva la identidad del emisor (CNPJ, legalName, tradeName) — también igual a `order.completed`.
## Handler de ejemplo
```js theme={null}
async function onFiscalAuthorized(data) {
const { orderId, fiscal, store } = data;
// 1. Persiste la autorización SEFAZ para auditoría
await db.fiscalDocs.upsert({
where: { providerDocId: fiscal.providerDocId },
create: {
providerDocId: fiscal.providerDocId,
fireOrderId: orderId,
country: "BR",
cnpj: store.storeFiscalConfig.govIdNumber,
docSubtype: fiscal.docSubtype,
chaveAcesso: fiscal.chaveAcesso,
protocolo: fiscal.protocolo,
authorizedAt: new Date(fiscal.dataAutorizacao),
status: "authorized",
},
update: {},
});
// 2. Obtén el XML canónico para archivado (legalmente requerido en BR)
const xml = await fetch(fiscal.xmlUrl).then(r => r.text());
await archive.put(`xml/${fiscal.providerDocId}.xml`, xml);
// 3. Notifica al cliente con el link del PDF
await mailer.send({
to: data.client?.email,
template: "fiscal-receipt",
pdf: fiscal.pdfUrl,
});
}
```
## `data.policy` y `data.lastKnown`
Todos los eventos de orden llevan estos dos bloques, no solo este. Se agregaron
junto con el ciclo de pago diferido y son **agregados en v1.1**, aditivos: los consumidores
existentes siguen funcionando sin cambios.
| Bloque | Qué es | ¿Confiar? |
| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
| `policy.deferredPayment` | Si la orden puede trabajarse **antes** del pago. Se resuelve una vez al inyectar y se estampa inmutable — todos los eventos posteriores repiten el mismo valor. | Sí. Es una decisión, no un estado. |
| `lastKnown` | Foto orientativa del estado de cocina (`kds`) y fiscal al emitir el evento. Puede venir `null` o viejo. | **No.** Nunca condiciones una acción irreversible a esto. |
```json theme={null}
"policy": { "deferredPayment": { "eligible": true, "resolvedAt": "2026-08-02T15:55:42.407Z",
"configVersion": "fnv1a:3144c6fb",
"resolvedFrom": { "channelCode": "APP", "fulfillmentCode": "DELIVERY", "paymentMethod": "CASH" } } },
"lastKnown": { "kds": null, "fiscal": { "status": "processing", "sourceEvent": "fiscal.callback" } }
```
El detalle campo por campo está en [`order.opened`](/es/events/order-opened#política-de-pago-diferido),
el evento donde estos bloques más importan.
## Errores comunes
* **`status === "authorized"`, no `"COMPLETED"`.** El `data.status` (status de la orden) es `"COMPLETED"`; el status fiscal está en `data.fiscal.status`.
* **`pdfUrl` y `xmlUrl` pueden ser efímeros.** En producción, tu proveedor fiscal puede firmar/expirar estos links. Descarga y persiste los artefactos al recibir, en lugar de linkear clientes directamente a tu proveedor fiscal.
* **`cStat` a menudo es `null`.** No hagas lógica que dependa de él. Usa `status === "authorized"` y `protocolo` como señales autoritativas.
* **No hay evento para `rejected` / `denied` / `error`.** Si SEFAZ rechaza el documento, no dispara evento hoy. El status del documento fiscal se persiste internamente pero no se dispara flow. Vigila esto en el roadmap.
* **El país ya no vive en el nombre del evento.** `order.invoiced` dispara para todos los países; usa `fiscal.countryCode` para filtrar. Los campos del bloque `fiscal` varían por país (chaveAcesso/protocolo en BR, cufe en CO, claveAcceso en EC, etc.).
## Eventos relacionados
Dispara antes de este evento — la orden misma.
Dispara después si el documento se cancela en SEFAZ.
## `data.fiscalRepresentation`
La **numeración fiscal** que el punto de venta obtuvo *antes* de inyectar la orden:
cobra, pide los identificadores, imprime el comprobante y recién después inyecta.
Por eso viaja en la orden y no en un evento fiscal aparte — cuando la orden nace,
esto ya ocurrió.
**Que este bloque exista NO significa que el comprobante esté autorizado.** Son
los números que se imprimieron en la caja; el veredicto del ente lo da
`lastKnown.fiscal.status`. Un ticket que diga "autorizado" solo porque el bloque
está presente declara algo que puede no haber pasado.
**La clave viaja siempre.** Llega en `null` cuando no se intentó numerar
—agregadores, países sin representación fiscal, o comercios con la numeración
desactivada— y con el bloque cuando sí se intentó.
Que traiga bloque significa **que se intentó numerar, no que se numeró**:
`numberingStatus` dice cómo terminó el intento, y `failure` por qué cuando no
terminó bien.
Ramificá por valor, no por presencia de la clave:
```js theme={null}
if (data.fiscalRepresentation) {
// se intentó numerar — mirá numberingStatus para saber cómo salió
}
```
| Campo | Qué es |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `numberingStatus` | Cómo terminó el **acto de numerar**: `GENERATED`, `PENDING`, `FAILED_RETRYABLE`, `FAILED_FINAL`, `UNAVAILABLE`. **No es el veredicto del ente** — ese está en `lastKnown.fiscal.status`. |
| `documentNumber` | Número visible del comprobante, compuesto según el país (`005-004-000000042`). Es presentación y **lo arma Fire**, no el ente: para conciliar usá `countryData`. |
| `issuedAt` | Cuándo se **numeró**. No es la fecha de autorización. |
| `authorizationMode` | `ONLINE`, `OFFLINE` o `BATCH`. Concepto del proveedor, no universal. |
| `providerCode` | Identificador del adaptador que numeró. |
| `countryData` | Los identificadores del ente, con el vocabulario del **país que numeró** y solo los de ese país. Ecuador: `numeroComprobante` (el número visible del comprobante, ya armado por el proveedor), `claveAcceso`, `establecimiento`, `puntoEmision`, `secuencial`, `ambiente`. Venezuela: `numeroControl`, `numeroFactura`, `serie`. **Recorrelo; no lo indexes a ciegas** — que aparezca una clave nueva no es un cambio que rompa. Es el mismo bloque que devuelve el endpoint de numeración y que trae el callback del ente. La referencia por país, con las claves de cada régimen, está en [`countryData` por país](/es/api-reference/fiscal-documents#countrydata-por-país). |
| `graphic` | El artefacto imprimible que entregó el proveedor (QR y demás), tal cual vino. `null` si no entregó ninguno. |
| `failure` | Por qué **no** hay comprobante. `null` cuando la numeración salió bien. |
| `providerIdentity` | **Quién numeró, del lado del proveedor**: `{ "name": "hio.fiscalization", "version": "2026.08.1", "reference": "HIO-91f3c2" }`. A diferencia de la bolsa de abajo, **tiene forma**: los tres campos están en el contrato y siempre vienen, con `null` cuando no aplica. `reference` es **la referencia de soporte del proveedor** — el identificador que se le cita a él para que encuentre la operación en sus registros; no es la `Idempotency-Key` que mandó el canal. No lleva `providerCode`: ese es nuestro y viaja arriba. |
| `providerMetadata` | **La bolsa de diagnóstico del proveedor**, tal como la devolvió: en Ecuador con HIO llega `{ "deviceUid": "4B8E…", "externalStoreCode": "K000" }`. Es **opaca** — las claves las pone el proveedor y pueden cambiar sin aviso, así que no programes contra ellas; sirve para pegar en un ticket, no para ramificar. **Es exactamente el mismo campo que devuelve el endpoint de numeración**, con el mismo nombre y el mismo contenido: los tres campos del proveedor se leen igual en los dos extremos. |
| `environment` | En qué ambiente numeró **Fire**: `SANDBOX` o `PRODUCTION`. Es nuestro, no del ente — el del ente viaja dentro de `countryData` con el código del país. |
| `compensates` | A qué documento anula este. Presente **solo** cuando `documentType` es `CREDIT_NOTE`. Es un **puntero**, no una copia: buscá su `documentNumber` en `history` si querés el documento entero. `reason` es el código canónico — el texto impreso lo redacta cada empresa y se resuelve en la respuesta del endpoint de numeración. |
| `history` | Los documentos **anteriores** de la orden, del más viejo al más nuevo. Vacío mientras hubo uno solo; cuando una anulación numera, la factura baja acá y la nota queda arriba. Cada entrada tiene **la misma forma** que el bloque de arriba, así que se leen igual. Solo documentos: un intento que falló no entra. |
```json theme={null}
"fiscalRepresentation": {
"numberingStatus": "GENERATED",
"documentNumber": "005-004-000000042",
"countryData": {
"numeroComprobante": "005-004-000000042",
"claveAcceso": "1208202601000000000000110050040000000421234567810",
"establecimiento": "005",
"puntoEmision": "004",
"secuencial": "000000042",
"ambiente": "2"
},
"authorizationMode": "ONLINE",
"issuedAt": "2026-08-13T08:11:29.744Z",
"providerCode": "hio",
"graphic": { "qr": "1208202601000000000000110050040000000421234567810" },
"failure": null,
"providerIdentity": { "name": "hio.fiscalization", "version": "2026.08.1", "reference": "HIO-91f3c2" },
"providerMetadata": { "deviceUid": "4B8E21F9A0D35C7A", "externalStoreCode": "K004" },
"environment": "PRODUCTION",
"compensates": null,
"history": []
}
```
**El veredicto del ente no lo altera.** Lo que el cliente se llevó impreso no
cambia porque el organismo después autorice o rechace; para eso está
`lastKnown.fiscal`, que es lo que sí se mueve.
**Lo que sí lo reemplaza es un documento nuevo.** El bloque lleva el documento
fiscal **vigente** de la orden. Mientras solo hubo uno, era siempre la factura;
cuando una anulación produce una nota de crédito, arriba queda la nota —
`documentType` dice cuál es— y la factura **baja a `history`**, entera y con sus
propios identificadores del ente. No se pierde: se mueve. `compensates` apunta a
ella por su número, así que la relación entre los dos queda explícita.
### Cuando la numeración falla
Una venta puede cobrarse y quedarse **sin comprobante fiscal**. Ese caso también
viaja, y hay que contemplarlo: los identificadores vienen en `null` y el motivo
en `failure`.
```json theme={null}
"fiscalRepresentation": {
"numberingStatus": "FAILED_FINAL",
"documentNumber": null,
"issuedAt": null,
"providerCode": "hio",
"graphic": null,
"failure": { "code": "RUC_INVALIDO", "scope": "FUNCTIONAL", "message": "RUC no habilitado" }
}
```
Ramificá por `failure.scope`:
* **`TECHNICAL`** — imprimí "en trámite" y seguí. Puede resolverse solo.
* **`FUNCTIONAL`** — hay un dato mal y reintentar no lo arregla. Requiere corrección.
**`lastKnown.fiscal.sourceEvent` ahora informa la procedencia real.** Antes se
deducía del estado, y un `processing` sembrado al inyectar se reportaba como
`fiscal.callback` sin que ningún callback hubiera ocurrido. Ahora ese caso dice
`order.injected`. Si ramificás por este campo, contemplá el valor nuevo.