Listar pedidos

GET https://api.fire.rest/api/v1/fire/external/orders?fields=id,orderCode,status,totals&page=1&size=20
x-api-key: <sua_api_key>

{
  "orders": [
    {
      "id": "7e2b8c10-1a2b-4c3d-8e9f-0a1b2c3d4e5f",
      "orderCode": "OC-1024",
      "status": "COMPLETED",
      "totals": [
        { "currencyCode": "USD", "total": 125000 }
      ]
    }
  ],
  "pagination": { "page": 1, "size": 20, "total": 1, "totalPages": 1 }
}

{
  "success": false,
  "error": "VALIDATION_ERROR",
  "message": "Unknown field(s) in projection: totls. Allowed: id, orderCode, orderExternal, accountId, vendorId, storeId, stationId, anonymousCustomerId, customerId, billingId, status, paymentStatus, channel, businessDayDate, createdAt, updatedAt, completedAt, deletedAt, store, customer, billing, fulfillment, orderLines, totals, paymentMethods, settlement, payments, metadata, kitchen, aggregator, fiscal"
}

{
  "success": false,
  "error": "FORBIDDEN",
  "message": "API key is not authorized for the requested vendor"
}

GET

api

fire

external

orders

GET https://api.fire.rest/api/v1/fire/external/orders?fields=id,orderCode,status,totals&page=1&size=20
x-api-key: <sua_api_key>

{
  "orders": [
    {
      "id": "7e2b8c10-1a2b-4c3d-8e9f-0a1b2c3d4e5f",
      "orderCode": "OC-1024",
      "status": "COMPLETED",
      "totals": [
        { "currencyCode": "USD", "total": 125000 }
      ]
    }
  ],
  "pagination": { "page": 1, "size": 20, "total": 1, "totalPages": 1 }
}

{
  "success": false,
  "error": "VALIDATION_ERROR",
  "message": "Unknown field(s) in projection: totls. Allowed: id, orderCode, orderExternal, accountId, vendorId, storeId, stationId, anonymousCustomerId, customerId, billingId, status, paymentStatus, channel, businessDayDate, createdAt, updatedAt, completedAt, deletedAt, store, customer, billing, fulfillment, orderLines, totals, paymentMethods, settlement, payments, metadata, kitchen, aggregator, fiscal"
}

{
  "success": false,
  "error": "FORBIDDEN",
  "message": "API key is not authorized for the requested vendor"
}

Retorna todos os pedidos do account + vendor vinculados à sua API key. Suporta paginação, um conjunto amplio de filtros e projeção de campos (você escolhe quais campos cada pedido retorna). Para listar os pedidos de uma única loja, use Listar pedidos da loja.

Autenticação

string

obrigatório

Sua API key do Fire com scope orders:read. A key deve ser vendor-scoped (binding account + vendor) — keys sem vendorId são rejeitadas com 403.

Query params

O account e o vendor são derivados da sua API key (vendor-scoped) — não são enviados por query.

string

Lista de campos a retornar separados por vírgula (projeção). Veja Projeção de campos. Omita para retornar todos os campos. Um campo desconhecido resulta em 400.

string

OPEN, COMPLETED, FORCE_CLOSED, CANCELLED.

string

PENDING, SUCCEEDED, FAILED.

string

Dia de negócio exato, YYYY-MM-DD.

string

Início do intervalo, YYYY-MM-DD.

string

Fim do intervalo, YYYY-MM-DD.

string

padrão:"business_day"

business_day ou created_at.

string

padrão:"+00:00"

Offset de timezone (+HH:MM) usado com dateFilterMode=created_at.

string

Código de canal (APP, KIOSK, …).

string

Código de serviço de fulfillment.

string

Código de método de pagamento (ex. CASH).

string

Match parcial sobre order code.

string

UUID exato, ou match parcial sobre external order id / order code.

integer

padrão:"1"

Número da página (base 1).

integer

padrão:"20"

Tamanho da página (1–100).

Requisição

GET https://api.fire.rest/api/v1/fire/external/orders?fields=id,orderCode,status,totals&page=1&size=20
x-api-key: <sua_api_key>

Projeção de campos

O consumidor decide quais campos cada pedido retorna, similar à projeção do MongoDB ou ao parâmetro _source do Elasticsearch.

Sem fields → todos os campos são retornados.
fields=id,orderCode,totals → apenas esses campos.
Um campo fora do catálogo → 400 com a lista de campos permitidos.

Campos disponíveis: id, orderCode, orderExternal, accountId, vendorId, storeId, stationId, anonymousCustomerId, customerId, billingId, status, paymentStatus, channel, businessDayDate, createdAt, updatedAt, completedAt, deletedAt, store, customer, billing, fulfillment, orderLines, totals, paymentMethods, settlement, payments, metadata, kitchen, aggregator, fiscal.

channel é o id de catálogo do pedido (orders.catalog_id), exposto sob o nome channel.

Os snapshots JSONB (totals, orderLines, paymentMethods, store, customer, fulfillment, metadata, fiscal) são retornados no formato de persistência interno do Fire (por exemplo, os valores de totals estão em escala ×10000).

Progresso da cobrança: `settlement` e `payments`

Quando um pedido é cobrado depois de aberto, status e paymentStatus só informam se ele foi cobrado. Dizem OPEN e PENDING tanto para um pedido que ninguém tentou cobrar quanto para um cujo cartão foi recusado duas vezes — e são situações bem diferentes para quem está olhando.

o pedido	`status`	`paymentStatus`	`settlement.status`
aberto, nada tentado	`OPEN`	`PENDING`	`pending`
uma peça foi recusada	`OPEN`	`PENDING`	`declined`
cobrado por completo	`COMPLETED`	`SUCCEEDED`	`settled`

Leia settlement para saber se e como foi cobrado, e payments para saber com o quê. A cobrança é tudo ou nada (veja Confirmar pagamento), então paidSoFar é 0 ou o total inteiro — nunca algo no meio.

Enquanto o pedido está aberto, paymentMethods é o que o POS declarou na criação do pedido — não o que foi cobrado. Só é sobrescrito com as peças reais quando o pedido liquida. Somá-lo para calcular o progresso dá o número errado. Use settlement.paidSoFar.

order.settlement (shape)

{
  "settlement": {
    "status": "settled",
    "origin": "ledger",
    "paidSoFar": "359000",
    "total": "359000",
    "currencyCode": "BRL",
    "tenderCount": 2,
    "declinedCount": 1,
    "amountMismatch": false,
    "declaredMethods": ["IFOOD"]
  }
}

status é um de pending, declined, settled. paidSoFar e total usam a mesma escala ×10000 de totals — acima, 35,90 cobrados em duas peças, depois de uma recusa anterior. tenderCount conta apenas as peças aprovadas; as recusadas estão em declinedCount. amountMismatch é sempre false: uma cobrança que não soma o total é rejeitada de saída, então um pedido liquidado sempre bate. O campo é mantido por compatibilidade. origin informa de onde vem paidSoFar, e os dois não têm o mesmo respaldo: ledger significa que as peças foram contadas uma a uma conforme chegaram; intake significa que o pedido foi criado já se declarando pago e o Fire acreditou. settlement é null nos pedidos criados antes de este campo existir. declaredMethods é com o que o pedido disse que seria pago, quando foi criado. Compare com paymentMethods para ver se pagaram com o que anunciaram: um pedido criado como IFOOD e cobrado com CREDIT mostra declaredMethods: ["IFOOD"] e paymentMethods com CREDIT. É o único lugar onde o meio declarado sobrevive, porque ao liquidar o paymentMethods é sobrescrito com as peças reais. Só os códigos viajam: os valores declarados vêm do POS em unidades ("35.9") enquanto paidSoFar vai ×10000, e misturar as duas escalas no mesmo objeto convida ao erro.

`payments` — as peças uma a uma

Os pedaços da cobrança, do mais antigo ao mais recente. As peças recusadas entram também: settlement.declinedCount diz quantas foram, payments diz quais e por quê.

"payments": [
  {
    "status": "approved",           // só as peças aprovadas somam em paidSoFar
    "amount": "200000",             // ×10000, a mesma escala de totals
    "currencyCode": "BRL",
    "method": "CASH",               // uma das duas peças de uma cobrança dividida
    "transactionId": "POS-0001",    // a chave de idempotência do POS
    "occurredAt": "2026-07-30T16:20:04.000Z"
  },
  {
    "status": "declined",
    "amount": "159000",
    "currencyCode": "BRL",
    "method": "CREDIT",
    "transactionId": "POS-0002",
    "declineReason": "51",                      // código cru do adquirente
    "declineReasonCode": "INSUFFICIENT_FUNDS",  // ausente quando não bateu com o catálogo
    "declineGroup": "FUNDS",
    "occurredAt": "2026-07-30T16:22:47.000Z"
  }
]

Um pedido que nunca passou por Confirmar pagamento — um pré-pago, por exemplo — retorna payments: [], nunca null. completedAt é o momento em que a cobrança fechou o pedido, e é null enquanto ele continua aberto.

O bloco `fiscal` por país

Quando um pedido possui um documento fiscal, o campo fiscal carrega seu estado atual. Seu sub-objeto metadata contém os campos comuns mais apenas os identificadores correspondentes a fiscal.countryCode — os identificadores dos outros países não são incluídos. Leia fiscal.countryCode para saber quais identificadores esperar.

order.fiscal (shape)

{
  "id": "7e2b8c10-…",
  "status": "COMPLETED",
  "fiscal": {
    "status": "authorized",
    "countryCode": "CO",
    "company": { "govIdType": "NIT", "govIdNumber": "9001234561", "legalName": "…", "tradeName": "…" },
    "store":   { "code": "CO-BOG-001", "name": "…", "govIdType": "NIT", "govIdNumber": "900123456-7" },
    "buyer":   { "isFinalConsumer": true, "name": null, "govIdType": null, "govIdNumber": null },
    "metadata": { "…": "see per-country tabs below" }
  }
}

status diz onde o pedido está fiscalmente. Agrupe pelo que você pode fazer a respeito:

Grupo	Valores	O que significa
Sem documento	`awaiting_payment`, `not_issued`	Nada foi emitido. `awaiting_payment` = o pedido está aberto e não pago, então ainda não cabe emitir. `not_issued` = o pedido fechou sem nunca ter sido faturado (cancelado antes do pagamento).
Em voo	`pending`, `processing`, `contingency`, `cancelling`	Há uma operação em curso e o desfecho é desconhecido. Não assuma sucesso nem falha — aguarde. `contingency` é um documento legalmente emitido pendente de transmissão.
Resolvido	`authorized`, `cancelled`	Terminal. Há documento válido, ou ele foi cancelado.
Falhou	`rejected`, `denied`, `error`	Não há documento válido. `fiscal.error` (`{ code, message }`) também está presente.
Entrega	`fiscal_graphic`	O provedor está entregando o artefato imprimível. Não é aprovação nem estado terminal.

awaiting_payment e not_issued descrevem o estado fiscal do pedido, não de um documento — em nenhum dos dois casos existe documento. Existem porque processing significava duas coisas incompatíveis: “há uma emissão em voo” e “este pedido ainda não chegou a ser faturado”. Aparecem em pedidos abertos e não pagos, então são mais frequentes junto com o pagamento diferido. Não viajam nos eventos de pedido; lá lastKnown.fiscal reporta null.

Os campos comuns de metadata (todos os países): docType, docSubtype, providerDocId, pdfUrl, xmlUrl, emittedAt, cancelledAt, totalAmount, taxAmount, currencyCode. Os identificadores específicos abaixo são adicionados por cima, mas metadata carrega apenas os identificadores do país do próprio documento — os dos outros países não são incluídos.

totalAmount e taxAmount NÃO vão escalados. Chegam tal como o provedor fiscal os mandou no callback: 95000 são 95.000 COP, não 9,50.É a exceção nesta página: totals, paidSoFar e os montantes de pagamento vão ×10.000, porque são dados que o FIRE calcula e armazena. Os de metadata são do documento do órgão e são guardados tal como estão.

metadata — CO (DIAN)

{
  "docType": "invoice",
  "docSubtype": "factura",
  "pdfUrl": "https://…/co.pdf",
  "xmlUrl": "https://…/co.xml",
  "emittedAt": "2026-04-26T14:32:10.000Z",
  "totalAmount": 95000,
  "taxAmount": 15170,
  "currencyCode": "COP",
  "cufe": "633732c7a2a577bfa1828551e64d03f715f0",
  "prefijo": "FE-CO",
  "numeroDian": "1001",
  "numeroComprobante": "FE-CO1001",
  "ambiente": "1"
}

metadata — EC (SRI)

{
  "docType": "invoice",
  "docSubtype": "factura",
  "pdfUrl": "https://…/ec.pdf",
  "xmlUrl": "https://…/ec.xml",
  "emittedAt": "2026-04-26T14:32:10.000Z",
  "totalAmount": 2450,
  "taxAmount": 315,
  "currencyCode": "USD",
  "claveAcceso": "0102030405060708091011121314151617181920212223242",
  "numeroAutorizacion": "AUT-EC-1001"
}

O qrCode (CO) e o ambiente (EC) do callback não são persistidos em fiscal.metadata — apenas os identificadores listados aqui são.

metadata — CL (SII)

{
  "docType": "invoice",
  "docSubtype": "boleta",
  "pdfUrl": "https://…/cl.pdf",
  "xmlUrl": "https://…/cl.xml",
  "emittedAt": "2026-04-26T14:32:10.000Z",
  "totalAmount": 18900,
  "taxAmount": 3019,
  "currencyCode": "CLP",
  "folio": 12345,
  "ted": "<TED>…</TED>",
  "tipoDte": 39,
  "trackId": "SII-TRK-998877"
}

metadata — AR (AFIP)

{
  "docType": "invoice",
  "docSubtype": "factura_b",
  "pdfUrl": "https://…/ar.pdf",
  "xmlUrl": "https://…/ar.xml",
  "emittedAt": "2026-04-26T14:32:10.000Z",
  "totalAmount": 12100,
  "taxAmount": 2100,
  "currencyCode": "ARS",
  "cae": "74256178925412",
  "fechaVtoCae": "2026-05-31",
  "puntoVenta": 1,
  "numeroComprobante": 12345,
  "tipoComprobante": 6
}

metadata — VE (SENIAT)

{
  "docType": "invoice",
  "docSubtype": "factura",
  "pdfUrl": "https://…/ve.pdf",
  "xmlUrl": "https://…/ve.xml",
  "emittedAt": "2026-04-26T14:32:10.000Z",
  "totalAmount": 480,
  "taxAmount": 76,
  "currencyCode": "VES",
  "numeroControl": "00-00012345",
  "numeroFactura": "12345",
  "rifEmisor": "J-12345678-9"
}

metadata — BR (SEFAZ, non-PlugNotas)

{
  "docType": "invoice",
  "docSubtype": "nfce",
  "pdfUrl": "https://…/br.pdf",
  "xmlUrl": "https://…/br.xml",
  "emittedAt": "2026-04-26T14:32:10.000Z",
  "totalAmount": 14290,
  "taxAmount": 1857,
  "currencyCode": "BRL",
  "chaveAcesso": "35260229062609000177650500000000011000000010",
  "protocolo": "141210001176277",
  "numero": 1,
  "serie": 50,
  "modelo": 65,
  "cnpjEmitente": "29062609000177"
}

O bloco `fiscal` traz o percurso completo do documento

fiscal segue o mesmo padrão de kitchen: o top-level é o estado vigente, e fiscal.history[] lista cada parada do documento fiscal, em ordem cronológica.

"fiscal": {
  "countryCode": "BR",
  "status": "cancelled",              // estado vigente
  "occurredAt": "2026-07-21T18:00:00Z",
  "company": { … }, "store": { … },   // emissor + loja, herdados
  "metadata": { … },                  // metadata do estado vigente
  "history": [
    { "status": "processing",     "occurredAt": "…" },
    { "status": "fiscal_graphic", "occurredAt": "…", "metadata": { "pdfUrl": "…" } },
    { "status": "authorized",     "occurredAt": "…", "metadata": { "chaveAcesso": "…" } },
    { "status": "cancelled",      "occurredAt": "…", "metadata": { "protocoloCancelamento": "…" } }
  ]
}

Status possíveis: pending, processing, contingency, fiscal_graphic, error, authorized, rejected, denied, cancelling, cancelled. Veja Callback fiscal para o significado de cada um. Ler o top-level continua funcionando como antes — history é aditivo. Use quando precisar dos dados de autorização de um documento que depois foi cancelado: eles vivem na entrada authorized.

Resposta

object[]

Array de pedidos, cada um projetado conforme fields.

object

Mostrar pagination

integer

Página atual.

integer

Tamanho da página.

integer

Total de pedidos que correspondem à query.

integer

Total de páginas.

{
  "orders": [
    {
      "id": "7e2b8c10-1a2b-4c3d-8e9f-0a1b2c3d4e5f",
      "orderCode": "OC-1024",
      "status": "COMPLETED",
      "totals": [
        { "currencyCode": "USD", "total": 125000 }
      ]
    }
  ],
  "pagination": { "page": 1, "size": 20, "total": 1, "totalPages": 1 }
}

{
  "success": false,
  "error": "VALIDATION_ERROR",
  "message": "Unknown field(s) in projection: totls. Allowed: id, orderCode, orderExternal, accountId, vendorId, storeId, stationId, anonymousCustomerId, customerId, billingId, status, paymentStatus, channel, businessDayDate, createdAt, updatedAt, completedAt, deletedAt, store, customer, billing, fulfillment, orderLines, totals, paymentMethods, settlement, payments, metadata, kitchen, aggregator, fiscal"
}

{
  "success": false,
  "error": "FORBIDDEN",
  "message": "API key is not authorized for the requested vendor"
}

API

APIs de parceiro

PayBridge

Autenticação

Query params

Requisição

Projeção de campos

Progresso da cobrança: `settlement` e `payments`

`payments` — as peças uma a uma

O bloco `fiscal` por país

O bloco `fiscal` traz o percurso completo do documento

Resposta

Relacionado

Listar pedidos da loja

Obter pedido

​Autenticação

​Query params

​Requisição

​Projeção de campos

​Progresso da cobrança: settlement e payments

​payments — as peças uma a uma

​O bloco fiscal por país

​O bloco fiscal traz o percurso completo do documento

​Resposta

​Relacionado

Listar pedidos da loja

Obter pedido

Autenticação

Query params

Requisição

Projeção de campos

Progresso da cobrança: `settlement` e `payments`

`payments` — as peças uma a uma

O bloco `fiscal` por país

O bloco `fiscal` traz o percurso completo do documento

Resposta

Relacionado