> ## 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
> The fiscal authority has authorized the document (electronic invoice) for an order via your fiscal provider — all countries.
You are reading the **current (v1.2)** contract for `order.invoiced`. **v1.2 adds** `data.fiscalRepresentation`: the fiscal numbering the point of sale obtained before injecting the order. It **always** travels: `null` when numbering was not attempted, and populated when it was — `numberingStatus` tells you how it ended. Carrying content does **not** mean the document is authorized. Additive only — nothing you already read changed.
The block carries the order's **current** fiscal document: the fields that mean the same in every country at the top, the authority identifiers inside `countryData` in that country's own vocabulary, and the previous documents in `history`. When a cancellation numbers, the credit note moves to the top and the invoice moves down into history — with `compensates` pointing at it.
**v1.1 added** `data.policy.deferredPayment` (can this order be worked before payment?) and `data.lastKnown` (advisory kitchen/fiscal state), plus the new [`order.opened`](/en/events/order-opened) event. Still valid: v1.2 only adds one block.
The **v1** contract is **deprecated** — kept as a historical reference. Open it here: [`order.invoiced` — v1](/en/events-v1/order-invoiced).
The **v0** order snapshot is **deprecated** — kept only as a historical reference. See [order.completed — v0](/en/events-v0/order-completed).
`order.invoiced` fires once the **country's fiscal authority** authorizes the fiscal document associated with an order — SEFAZ in Brazil, SRI in Ecuador, DIAN in Colombia, AFIP in Argentina, SII in Chile, SENIAT in Venezuela. It is emitted by Fire's fiscal pipeline, which integrates with your fiscal provider as the document provider.
This event is **separate from** [`order.completed`](/en/events/order-completed): the order is paid first (`order.completed`), then Fire requests fiscal emission via your fiscal provider, and `order.invoiced` fires only when the fiscal authority returns the authorization.
## Trigger condition
Fire emits `order.invoiced` once per fiscal document, the first time **all** of these are true:
* The order is in a store with fiscal billing enabled (`storeFiscalConfig.enabled === true`)
* A fiscal document was emitted to your fiscal provider
* your fiscal provider reports that the fiscal authority authorized the document (`status` transitions to `authorized`; in Brazil this maps to the SEFAZ `cStat` authorized code)
| | |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Coverage | **All countries** — Brazil (NFC-e/NF-e via SEFAZ) and CO/EC/CL/AR/VE via the [generic fiscal callback](/en/api-reference/fiscal-callback). The country travels in `fiscal.countryCode`, no longer in the event name |
| Document types | Vary by country — `nfce`/`nfe` (BR), electronic invoice (CO/EC/CL/AR/VE). Arrives in `fiscal.docSubtype` |
| Idempotency key | `event.id` |
| Fires more than once | No, unless retried |
| Latency relative to `order.completed` | Usually seconds; can be minutes if the fiscal authority is degraded |
## What's in `trigger.data`
Same V4 order snapshot as [`order.completed`](/en/events/order-completed) plus a top-level **`fiscal`** block carrying the authorized document references. **Fields vary by country** — Brazil is shown below (`chaveAcesso`, `protocolo`); other countries carry their own identifiers (`cufe` in CO, `claveAcceso` in EC, `cae` in AR, etc.). See the [generic fiscal callback](/en/api-reference/fiscal-callback) for the per-country contract.
The order's `status` remains `"COMPLETED"` and `paymentStatus` remains `"SUCCEEDED"` — fiscal authorization does not change order status.
## Example — real production payload (BR, sanitized)
```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": { /* same as order.completed — includes storeFiscalConfig with CNPJ, legalName */ },
"client": { /* ... */ },
"payments": { /* ... — includes payments.metadata.fiscal aggregates */ },
"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" }
}
```
## `data.fiscal` reference
SEFAZ-authorized document references.
Document status. For this event, always `"authorized"`. Other values you may see in your fiscal provider (`pending`, `processing`, `rejected`, `denied`) do **not** trigger `order.invoiced` — only the terminal authorized state does.
Document type. Values: `nfce` (NFC-e — consumer invoice, B2C) or `nfe` (NF-e — business invoice, B2B).
The 44-digit SEFAZ access key. Encodes UF, year/month, CNPJ, model, series, number, type of emission, and a check digit. Use this for reconciliation with SEFAZ portals.
Document number assigned by Fire's emission pipeline. Sequential per `(cnpj, serie, docSubtype)`.
Document series. May be `null` for some configurations; the series is encoded in `chaveAcesso` regardless.
SEFAZ authorization protocol number. Required for any subsequent SEFAZ operation (cancellation, correction).
Internal document ID assigned by your fiscal provider. Use it to query your provider's APIs directly (e.g. fetch the canonical XML).
URL to download the document's PDF (DANFE for NF-e, DANFCE for NFC-e). Hosted by your fiscal provider; signed/short-lived in production, durable in sandbox.
URL to download the canonical SEFAZ XML. Same hosting as `pdfUrl`.
ISO 8601 UTC timestamp of the SEFAZ authorization (when SEFAZ stamped the protocol).
Raw SEFAZ status code. May be `null` when the provider does not surface it (some providers hide it for consumer flows). When present, `100` (NF-e) or `100` (NFC-e) indicate authorization.
## Where the fiscal totals live
The aggregate fiscal values (vBC, vNF, vICMS, etc.) **are not** inside `data.fiscal` — they're in `data.payments.metadata.fiscal`, the same place [`order.completed`](/en/events/order-completed#fiscal-data) carries them. `order.invoiced` does not duplicate them; treat the order snapshot as the single source of truth for monetary aggregates.
Per-line classification (NCM, CFOP, CSOSN, fiscalCategoryCode) lives in `data.orderLines[n].metadata.fiscal`. Same as in `order.completed`.
The `data.store.storeFiscalConfig` block carries the emitter identity (CNPJ, legalName, tradeName) — also unchanged from `order.completed`.
## `data.policy` and `data.lastKnown`
Every order event carries these two blocks — not just this one. They were added
together with the deferred-payment cycle and are **added in v1.1**, additive: existing
consumers keep working unchanged.
| Block | What it is | Trust it? |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ |
| `policy.deferredPayment` | Whether the order may be acted on **before** payment. Resolved once at injection and stamped immutably — every later event echoes the same value. | Yes. It is a decision, not a state. |
| `lastKnown` | Advisory snapshot of kitchen (`kds`) and fiscal state when the event was emitted. May be `null` or stale. | **No.** Never gate an irreversible action on it. |
```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" } }
```
Field-by-field detail lives in [`order.opened`](/en/events/order-opened#deferred-payment-policy),
the event where these blocks matter most.
## Handler example
```js theme={null}
async function onFiscalAuthorized(data) {
const { orderId, fiscal, store } = data;
// 1. Persist the SEFAZ authorization for audit
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. Fetch the canonical XML for archival (legally required in BR)
const xml = await fetch(fiscal.xmlUrl).then(r => r.text());
await archive.put(`xml/${fiscal.providerDocId}.xml`, xml);
// 3. Notify the customer with the PDF link
await mailer.send({
to: data.client?.email,
template: "fiscal-receipt",
pdf: fiscal.pdfUrl,
});
}
```
## Common pitfalls
* **`status === "authorized"`, not `"COMPLETED"`.** The `data.status` (the order status) is `"COMPLETED"`; the fiscal status is in `data.fiscal.status`.
* **`pdfUrl` and `xmlUrl` may be ephemeral.** In production, your fiscal provider may sign/expire these links. Download and persist the artifacts on receipt rather than linking customers directly to your fiscal provider.
* **`cStat` is often `null`.** Don't make logic depend on it. Use `status === "authorized"` and `protocolo` as the authoritative signals.
* **No event for `rejected` / `denied` / `error`.** If SEFAZ rejects the document, no event fires today. The fiscal document's status is persisted internally but no flow is triggered. Watch for this in the roadmap.
* **The country no longer lives in the event name.** `order.invoiced` fires for all countries; filter on `fiscal.countryCode`. The `fiscal` block fields vary per country (chaveAcesso/protocolo in BR, cufe in CO, claveAcceso in EC, etc.).
## Related events
Fires before this event — the order itself.
Fires later if the document gets cancelled at SEFAZ.
## `data.fiscalRepresentation`
The **fiscal numbering** the point of sale obtained *before* injecting the order:
it charges, requests the identifiers, prints the receipt, and only then injects.
That is why it travels on the order and not in a separate fiscal event — by the
time the order is born, this already happened.
**The presence of this block does NOT mean the document is authorized.** These
are the numbers printed at the till; the tax authority's verdict is in
`lastKnown.fiscal.status`. A ticket that says "authorized" just because the
block is present states something that may never have happened.
**The key always travels.** It arrives as `null` when numbering was not
attempted — aggregators, countries without fiscal representation, or merchants
with numbering turned off — and carries the block when it was.
Carrying the block means **numbering was attempted, not that it succeeded**:
`numberingStatus` tells you how the attempt ended, and `failure` why, when it did
not end well.
Branch on the value, not on the key's presence:
```js theme={null}
if (data.fiscalRepresentation) {
// numbering was attempted — read numberingStatus to see how it went
}
```
| Field | What it is |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `numberingStatus` | How the **numbering act** ended: `GENERATED`, `PENDING`, `FAILED_RETRYABLE`, `FAILED_FINAL`, `UNAVAILABLE`. **Not the authority's verdict** — that lives in `lastKnown.fiscal.status`. |
| `documentNumber` | The receipt's visible number, composed per country (`005-004-000000042`). It is presentation and **Fire builds it**, not the authority: reconcile with `countryData`. |
| `issuedAt` | When it was **numbered**. Not the authorization date. |
| `authorizationMode` | `ONLINE`, `OFFLINE` or `BATCH`. A provider concept, not universal. |
| `providerCode` | Identifier of the adapter that numbered. |
| `countryData` | The authority identifiers, in the vocabulary of the **country that numbered** — and only that country's. Ecuador: `numeroComprobante` (the human-readable document number, already assembled by the provider), `claveAcceso`, `establecimiento`, `puntoEmision`, `secuencial`, `ambiente`. Venezuela: `numeroControl`, `numeroFactura`, `serie`. **Iterate it; do not index blindly** — a new key here is not a breaking change. It is the same block the numbering endpoint returns and the authority callback carries. The per-country reference, with each regime's keys, is in [`countryData` by country](/en/api-reference/fiscal-documents#countrydata-by-country). |
| `graphic` | The printable artifact the provider returned (QR and the like), verbatim. `null` if it returned none. |
| `failure` | Why there is **no** receipt. `null` when numbering succeeded. |
| `providerIdentity` | **Who numbered, on the provider's side**: `{ "name": "hio.fiscalization", "version": "2026.08.1", "reference": "HIO-91f3c2" }`. Unlike the bag below, **it has a shape**: all three fields are part of the contract and always come through, with `null` when they do not apply. `reference` is **the provider's own support reference** — the identifier you quote back to them so they can find the operation in their records; it is not the `Idempotency-Key` the channel sent. It does not carry `providerCode`: that one is ours and travels at the top. |
| `providerMetadata` | **The provider's diagnostic bag**, exactly as it returned it: in Ecuador with HIO you get `{ "deviceUid": "4B8E…", "externalStoreCode": "K000" }`. It is **opaque** — the provider owns the keys and may change them without notice, so do not program against them; it is for pasting into a ticket, not for branching. **It is exactly the same field the numbering endpoint returns**, same name and same content: all three provider fields read the same at both ends. |
| `environment` | Which environment **Fire** numbered in: `SANDBOX` or `PRODUCTION`. It is ours, not the authority's — the authority's travels inside `countryData` with the country's own code. |
| `compensates` | Which document this one voids. Present **only** when `documentType` is `CREDIT_NOTE`. It is a **pointer**, not a copy: look its `documentNumber` up in `history` for the whole document. `reason` is the canonical code — the printed wording is authored per company and resolved in the numbering endpoint's response. |
| `history` | The order's **previous** documents, oldest first. Empty while there was only one; when a cancellation numbers, the invoice moves down here and the credit note sits on top. Every entry has **the same shape** as the block above, so they read alike. Documents only: a failed attempt does not appear. |
```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": []
}
```
**The authority's verdict does not alter it.** What the customer took home
printed does not change because the authority later authorizes or rejects — that
is what `lastKnown.fiscal` is for, and that is what does move.
**What does replace it is a new document.** The block carries the order's
**current** fiscal document. While there was only one, it was always the invoice;
when a cancellation produces a credit note, the note is what sits on top —
`documentType` says which one — and the invoice **moves down into `history`**,
whole and with its own authority identifiers. It is not lost: it moves.
`compensates` points at it by number, so the relationship stays explicit.
### When numbering fails
A sale can be charged and end up **with no fiscal receipt**. That case travels
too, and you must handle it: the identifiers come back `null` and the reason is
in `failure`.
```json theme={null}
"fiscalRepresentation": {
"numberingStatus": "FAILED_FINAL",
"documentNumber": null,
"issuedAt": null,
"providerCode": "hio",
"graphic": null,
"failure": { "code": "RUC_INVALIDO", "scope": "FUNCTIONAL", "message": "Tax ID not enabled" }
}
```
Branch on `failure.scope`:
* **`TECHNICAL`** — print "pending" and carry on. It may resolve on its own.
* **`FUNCTIONAL`** — some data is wrong and retrying will not fix it. Needs correction.
**`lastKnown.fiscal.sourceEvent` now reports real provenance.** It used to be
derived from the status, so a `processing` seeded at injection was reported as
`fiscal.callback` even though no callback had occurred. That case now says
`order.injected`. If you branch on this field, account for the new value.