Saltar para o conteúdo principal
GET
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

​
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, revision, 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. 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)
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ê.
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. revision é a versão do pedido: começa em 1 e sobe um a cada vez que ele é corrigido. É o que você envia como expectedRevision ao corrigi-lo. A cobrança não a altera.

​
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)
status diz onde o pedido está fiscalmente. Agrupe pelo que você pode fazer a respeito:
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)

​
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.
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

​
Relacionado

Listar pedidos da loja

A mesma listagem, restrita a uma única loja.

Obter pedido

Leia um pedido específico por id.