order.invoiced

v1.2 · atual
v1.1 · anterior
v1 · descontinuado
v0 · descontinuado

Você está lendo o contrato atual (v1.2) de order.invoiced. v1.2 adiciona data.fiscalRepresentation: a numeração fiscal que o ponto de venda obteve antes de injetar o pedido. Viaja sempre: em null quando não se tentou numerar, e preenchido quando sim — numberingStatus diz como terminou. Trazer conteúdo não significa que o comprovante esteja autorizado. Apenas aditivo — nada do que você já lia mudou.O bloco carrega o documento fiscal vigente do pedido: os campos que significam o mesmo em qualquer país no topo, os identificadores do órgão dentro de countryData no vocabulário do seu país, e os documentos anteriores em history. Quando um cancelamento numera, a nota de crédito passa ao topo e a de venda desce para o histórico — com compensates apontando para ela.

v1.1 adicionou data.policy.deferredPayment (este pedido pode ser trabalhado antes do pagamento?) e data.lastKnown (estado orientativo de cozinha/fiscal), além do novo evento order.opened. Continua válido: v1.2 apenas soma um bloco.

O contrato v1 está descontinuado — mantido como referência histórica. Abra aqui: order.invoiced — v1.

order.invoiced dispara quando a autoridade fiscal do país autoriza o documento fiscal associado a um pedido — SEFAZ no Brasil, SRI no Equador, DIAN na Colômbia, AFIP na Argentina, SII no Chile, SENIAT na Venezuela. É emitido pelo pipeline fiscal do Fire, que se integra com o seu provedor fiscal como provedor de documentos. Este evento é separado de order.completed: o pedido é pago primeiro (order.completed), depois o Fire pede a emissão fiscal via seu provedor fiscal, e order.invoiced dispara apenas quando a autoridade fiscal retorna a autorização.

Condição de disparo

O Fire emite order.invoiced uma vez por documento fiscal, na primeira vez em que tudo o seguinte é verdade:

O pedido está em uma loja com faturamento fiscal habilitado (storeFiscalConfig.enabled === true)
Um documento fiscal foi emitido para o seu provedor fiscal
O seu provedor fiscal reporta que a autoridade fiscal autorizou o documento (o status transiciona para authorized; no Brasil isso corresponde ao código cStat de autorização SEFAZ)


Cobertura	Todos os países — Brasil (NFC-e/NF-e via SEFAZ) e CO/EC/CL/AR/VE via o callback fiscal genérico. O país viaja em `fiscal.countryCode`, não mais no nome do evento
Tipos de documento	Variam por país — `nfce`/`nfe` (BR), nota fiscal eletrônica (CO/EC/CL/AR/VE). Chega em `fiscal.docSubtype`
Chave de idempotência	`event.id`
Dispara mais de uma vez	Não, salvo em retentativas
Latência relativa a `order.completed`	Geralmente segundos; pode ser minutos se a autoridade fiscal estiver degradada

O que tem em `trigger.data`

Mesmo snapshot V4 que order.completed mais um bloco top-level fiscal com as referências do documento autorizado. Os campos variam por país — abaixo é mostrado o Brasil (chaveAcesso, protocolo); outros países carregam seus próprios identificadores (cufe na CO, claveAcceso no EC, cae na AR, etc.). Veja o callback fiscal genérico para o contrato por país. O status do pedido permanece "COMPLETED" e paymentStatus permanece "SUCCEEDED" — a autorização fiscal não muda o status do pedido.

Exemplo — payload real de produção (BR, sanitizado)

{
  "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 a order.completed — inclui storeFiscalConfig com CNPJ, legalName */ },
    "client": { /* ... */ },
    "payments": { /* ... — inclui payments.metadata.fiscal com 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" }
}

Referência de `data.fiscal`

object

Referências do documento autorizado pela SEFAZ.

Mostrar fiscal

string

Status do documento. Para este evento, sempre "authorized". Outros valores que você pode ver no seu provedor fiscal (pending, processing, rejected, denied) não disparam order.invoiced — apenas o estado terminal autorizado.

string

Tipo de documento. Valores: nfce (NFC-e — fatura de consumidor, B2C) ou nfe (NF-e — fatura de negócio, B2B).

string

Chave de acesso SEFAZ de 44 dígitos. Codifica UF, ano/mês, CNPJ, modelo, série, número, tipo de emissão e um dígito verificador. Use para reconciliar com portais SEFAZ.

string

Número de documento atribuído pelo pipeline de emissão do Fire. Sequencial por (cnpj, serie, docSubtype).

string | null

Série do documento. Pode ser null para algumas configurações; a série está codificada em chaveAcesso de qualquer forma.

string

Número de protocolo de autorização SEFAZ. Necessário para qualquer operação SEFAZ subsequente (cancelamento, correção).

string

ID interno do documento no seu provedor fiscal. Use para consultar as APIs do seu provedor fiscal diretamente (ex.: buscar o XML canônico).

string

URL para baixar o PDF do documento (DANFE para NF-e, DANFCE para NFC-e). Hospedado pelo seu provedor fiscal; assinado/de vida curta em produção, durável em sandbox.

string

URL para baixar o XML canônico SEFAZ. Mesmo hosting que pdfUrl.

string

Timestamp ISO 8601 UTC da autorização SEFAZ (quando a SEFAZ carimbou o protocolo).

string | null

Código de status raw da SEFAZ. Pode ser null quando o provedor não o expõe (o seu provedor fiscal o esconde para alguns flows de consumidor). Quando presente, 100 (NF-e) ou 100 (NFC-e) indicam autorização.

Onde vivem os totais fiscais

Os valores agregados fiscais (vBC, vNF, vICMS, etc.) não estão dentro de data.fiscal — estão em data.payments.metadata.fiscal, o mesmo lugar onde order.completed os carrega. order.invoiced não os duplica; trate o snapshot do pedido como a única fonte de verdade para os agregados monetários. A classificação por linha (NCM, CFOP, CSOSN, fiscalCategoryCode) vive em data.orderLines[n].metadata.fiscal. Igual a order.completed. O bloco data.store.storeFiscalConfig carrega a identidade do emissor (CNPJ, legalName, tradeName) — também igual a order.completed.

Handler de exemplo

async function onFiscalAuthorized(data) {
  const { orderId, fiscal, store } = data;

  // 1. Persiste a autorização SEFAZ para auditoria
  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. Busque o XML canônico para arquivamento (legalmente exigido em BR)
  const xml = await fetch(fiscal.xmlUrl).then(r => r.text());
  await archive.put(`xml/${fiscal.providerDocId}.xml`, xml);

  // 3. Notifique o cliente com o link do PDF
  await mailer.send({
    to: data.client?.email,
    template: "fiscal-receipt",
    pdf: fiscal.pdfUrl,
  });
}

`data.policy` e `data.lastKnown`

Todos os eventos de pedido carregam estes dois blocos, não só este. Foram adicionados junto com o ciclo de pagamento diferido e são adicionados na v1.1, aditivos: consumidores existentes continuam funcionando sem alteração.

Bloco	O que é	Confiar?
`policy.deferredPayment`	Se o pedido pode ser trabalhado antes do pagamento. Resolvido uma vez na injeção e carimbado imutável — todos os eventos seguintes repetem o mesmo valor.	Sim. É uma decisão, não um estado.
`lastKnown`	Foto orientativa do estado de cozinha (`kds`) e fiscal na emissão do evento. Pode vir `null` ou desatualizado.	Não. Nunca condicione uma ação irreversível a isto.

"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" } }

O detalhe campo a campo está em order.opened, o evento onde estes blocos mais importam.

Erros comuns

status === "authorized", não "COMPLETED". O data.status (status do pedido) é "COMPLETED"; o status fiscal está em data.fiscal.status.
pdfUrl e xmlUrl podem ser efêmeros. Em produção, o seu provedor fiscal pode assinar/expirar esses links. Baixe e persista os artefatos ao receber, em vez de linkar clientes diretamente ao seu provedor fiscal.
cStat frequentemente é null. Não faça lógica que dependa dele. Use status === "authorized" e protocolo como sinais autoritativos.
Não há evento para rejected / denied / error. Se a SEFAZ rejeita o documento, nenhum evento dispara hoje. O status do documento fiscal é persistido internamente mas não dispara flow. Fique atento no roadmap.
O país não vive mais no nome do evento. order.invoiced dispara para todos os países; use fiscal.countryCode para filtrar. Os campos do bloco fiscal variam por país (chaveAcesso/protocolo no BR, cufe na CO, claveAcceso no EC, etc.).

Eventos relacionados

order.completed

Dispara antes deste evento — o pedido em si.

order.reversed

Dispara depois se o documento for cancelado na SEFAZ.

`data.fiscalRepresentation`

A numeração fiscal que o ponto de venda obteve antes de injetar o pedido: cobra, pede os identificadores, imprime o comprovante e só então injeta. Por isso viaja no pedido e não em um evento fiscal separado — quando o pedido nasce, isso já aconteceu.

A presença deste bloco NÃO significa que o comprovante esteja autorizado. São os números impressos no caixa; o veredito do órgão está em lastKnown.fiscal.status. Um ticket que diga “autorizado” só porque o bloco está presente declara algo que pode não ter acontecido.

A chave viaja sempre. Chega em null quando não se tentou numerar — agregadores, países sem representação fiscal, ou comércios com a numeração desativada — e traz o bloco quando houve tentativa. Trazer o bloco significa que se tentou numerar, não que foi numerado: numberingStatus diz como a tentativa terminou, e failure por quê quando não terminou bem. Ramifique pelo valor, não pela presença da chave:

if (data.fiscalRepresentation) {
  // houve tentativa de numeração — veja numberingStatus para saber como saiu
}

Campo	O que é
`numberingStatus`	Como terminou o ato de numerar: `GENERATED`, `PENDING`, `FAILED_RETRYABLE`, `FAILED_FINAL`, `UNAVAILABLE`. Não é o veredito do órgão — esse está em `lastKnown.fiscal.status`.
`documentNumber`	Número visível do comprovante, composto conforme o país (`005-004-000000042`). É apresentação e quem o monta é o Fire, não o órgão: para conciliar use `countryData`.
`issuedAt`	Quando foi numerado. Não é a data de autorização.
`authorizationMode`	`ONLINE`, `OFFLINE` ou `BATCH`. Conceito do provedor, não universal.
`providerCode`	Identificador do adaptador que numerou.
`countryData`	Os identificadores do órgão, no vocabulário do país que numerou — e só os desse país. Equador: `numeroComprobante` (o número visível do comprovante, já montado pelo provedor), `claveAcceso`, `establecimiento`, `puntoEmision`, `secuencial`, `ambiente`. Venezuela: `numeroControl`, `numeroFactura`, `serie`. Percorra-o; não o indexe às cegas — uma chave nova não é uma mudança que quebra. É o mesmo bloco que o endpoint de numeração devolve e que o callback do órgão traz. A referência por país, com as chaves de cada regime, está em `countryData` por país.
`graphic`	O artefato imprimível que o provedor devolveu (QR e afins), tal como veio. `null` se não devolveu nenhum.
`failure`	Por que não há comprovante. `null` quando a numeração deu certo.
`providerIdentity`	Quem numerou, do lado do provedor: `{ "name": "hio.fiscalization", "version": "2026.08.1", "reference": "HIO-91f3c2" }`. Diferente da bolsa abaixo, tem forma: os três campos estão no contrato e sempre chegam, com `null` quando não se aplicam. `reference` é a referência de suporte do provedor — o identificador que se cita a ele para encontrar a operação nos registros dele; não é a `Idempotency-Key` que o canal enviou. Não leva `providerCode`: esse é nosso e viaja acima.
`providerMetadata`	A bolsa de diagnóstico do provedor, tal como ele a devolveu: no Equador com a HIO chega `{ "deviceUid": "4B8E…", "externalStoreCode": "K000" }`. É opaca — as chaves são do provedor e podem mudar sem aviso, então não programe contra elas; serve para colar num ticket, não para ramificar. É exatamente o mesmo campo que o endpoint de numeração devolve, com o mesmo nome e o mesmo conteúdo: os três campos do provedor se leem igual nos dois extremos.
`environment`	Em qual ambiente o Fire numerou: `SANDBOX` ou `PRODUCTION`. É nosso, não do órgão — o do órgão viaja dentro de `countryData` com o código do país.
`compensates`	Qual documento este anula. Presente apenas quando `documentType` é `CREDIT_NOTE`; `null` nos demais. Traz `documentNumber`, `issuedAt` e `reason` (o código canônico — o texto impresso é redigido por empresa e resolvido na resposta do endpoint de numeração).
`history`	Os documentos anteriores do pedido, do mais antigo ao mais novo. Vazio enquanto houve apenas um; quando um cancelamento numera, a nota de venda desce para cá e a nota de crédito fica no topo. Cada entrada tem a mesma forma do bloco acima, então se leem igual. Somente documentos: uma tentativa de numeração que falhou não entra.

"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": []
}

O veredicto do órgão não o altera. O que o cliente levou impresso não muda porque o órgão depois autorize ou rejeite — para isso existe lastKnown.fiscal, que é o que de fato se move. O que o substitui é um documento novo. O bloco carrega o documento fiscal vigente do pedido. Enquanto houve apenas um, era sempre a nota de venda; quando um cancelamento produz uma nota de crédito, é ela que fica no topo — documentType diz qual é — e a nota de venda desce para history, inteira e com seus próprios identificadores do órgão. Não se perde: se move. compensates aponta para ela pelo número, então a relação fica explícita.

Quando a numeração falha

Uma venda pode ser cobrada e ficar sem comprovante fiscal. Esse caso também viaja, e precisa ser tratado: os identificadores vêm null e o motivo em failure.

"fiscalRepresentation": {
  "numberingStatus": "FAILED_FINAL",
  "documentNumber": null,
  "issuedAt": null,
  "providerCode": "hio",
  "graphic": null,
  "failure": { "code": "RUC_INVALIDO", "scope": "FUNCTIONAL", "message": "CNPJ não habilitado" }
}

Ramifique por failure.scope:

TECHNICAL — imprima “em trâmite” e siga. Pode se resolver sozinho.
FUNCTIONAL — há um dado errado e repetir não resolve. Precisa correção. O que muda é lastKnown.fiscal.

lastKnown.fiscal.sourceEvent agora informa a procedência real. Antes era deduzida do status, e um processing semeado na injeção era reportado como fiscal.callback sem que nenhum callback tivesse ocorrido. Esse caso agora diz order.injected. Se você ramifica por este campo, contemple o valor novo.

Conceitos

Catálogo

Condição de disparo

O que tem em `trigger.data`

Exemplo — payload real de produção (BR, sanitizado)

Referência de `data.fiscal`

Onde vivem os totais fiscais

Handler de exemplo

`data.policy` e `data.lastKnown`

Erros comuns

Eventos relacionados

order.completed

order.reversed

`data.fiscalRepresentation`

Quando a numeração falha

​Condição de disparo

​O que tem em trigger.data

​Exemplo — payload real de produção (BR, sanitizado)

​Referência de data.fiscal

​Onde vivem os totais fiscais

​Handler de exemplo

​data.policy e data.lastKnown

​Erros comuns

​Eventos relacionados

order.completed

order.reversed

​data.fiscalRepresentation

​Quando a numeração falha

Condição de disparo

O que tem em `trigger.data`

Exemplo — payload real de produção (BR, sanitizado)

Referência de `data.fiscal`

Onde vivem os totais fiscais

Handler de exemplo

`data.policy` e `data.lastKnown`

Erros comuns

Eventos relacionados

`data.fiscalRepresentation`

Quando a numeração falha