> ## 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.
# Injetar pedido
> Injete um pedido no Fire. O Fire gerencia o ciclo de vida do pedido e envia atualizações de status de volta via webhooks.
Token Bearer obtido em [POST /login](/pt/api-reference/login). Formato: `Bearer `.
Sua API key do Fire.
Deve ser `integration`. Identifica a requisição como vinda de uma integração externa.
Identificador da conta à qual a requisição pertence.
Identificador único do pedido no seu sistema.
Origem do pedido. Exemplos: `App`, `Kiosco`.
Plataforma do cliente. Exemplos: `Android`, `iOS`, `Web`.
Detalhes do canal de venda. Use valores `uid` dos webhooks de publicação (por exemplo [`channel.updated`](/pt/webhook-reference/channel-updated)) ou da configuração de canais no painel ([Integrações de agregadores](/pt/configuration/backoffice-integrations)).
UID do canal no Fire.
Código do tipo de canal. Um de: `POS`, `Kiosk`, `App`, `Web`, `CallCenter`, `Aggregator`.
Metadados adicionais do canal.
Detalhes do serviço de fulfillment. Use valores `uid` do array `services` nesses payloads de canal ou as mesmas fontes que `channel`.
UID do serviço no Fire.
Código do tipo de fulfillment. Um de: `DELIVERY`, `TAKEAWAY`, `PICKUP`, `DINE_IN`.
Metadados adicionais do serviço.
Detalhes do dispositivo. `null` para canais sem dispositivo físico.
UID do dispositivo.
Nome de exibição do dispositivo (ex.: `KIOSK`).
Plataforma do dispositivo (ex.: `android`, `ios`).
Metadados adicionais do dispositivo.
Ponto de emissão fiscal do dispositivo. Usado apenas ao
[solicitar o documento fiscal](/pt/api-reference/fiscal-documents); aqui é aceito e ignorado.
Resultado de [Solicitar documento fiscal](/pt/api-reference/fiscal-documents), copiado tal
como veio. Opcional: se você não fiscalizou antes de injetar, omita — o Fire resolve a
fiscalização por conta própria.
O Fire pega daqui os dados do comprovante para o pedido e ignora o resto. O status do
documento perante o fisco é responsabilidade do Fire: `documentStatus` é ignorado se vier.
Operador ou caixa que processou o pedido. `null` para canais self-service.
UID do operador.
Nome de exibição do operador.
Detalhes da sessão ativa.
UID da sessão.
Metadados adicionais do operador.
Método de envio selecionado pelo cliente. Valores: `delivery`, `pickup`.
Indica se o cliente acumula pontos de fidelidade neste pedido.
Indica se o cliente resgata pontos de fidelidade neste pedido.
Indica se descontos são aplicados neste pedido.
Comentário geral do cliente para o pedido inteiro.
Informações do cliente.
Identificador único do cliente vindo do provedor de autenticação.
Nome.
Sobrenome.
Número de telefone.
Endereço de e-mail.
Tipo de documento. Exemplo: `DNI`, `CI`.
Número do documento.
ID do cliente em um sistema externo.
ID do cliente no Fire.
Dados de faturamento.
Razão social ou nome da pessoa para a fatura.
Tipo de documento para faturamento.
Número de documento para faturamento.
Telefone de faturamento.
E-mail de faturamento.
Endereço de faturamento.
ID de faturamento em sistema externo.
ID de faturamento no Fire.
Dados adicionais do cliente (ex.: data de nascimento, gênero).
Loja onde o pedido é realizado.
ID da loja.
Nome de exibição da loja.
Código da loja.
Identificador da marca.
Nome da marca.
Latitude da loja.
Longitude da loja.
Conteúdo do pedido.
Produtos pedidos.
Identificador do produto.
Nome de exibição do produto.
Tipo do item. Valores aceitos: `COMBO` (produto com grupos de modificadores não vazios), `PRODUCT` (produto simples vendável), `MODIFIER` (opção de modificador puro — usar em `selectedModifiers[]`), `PACKAGING` (item de embalagem). Sem valor padrão — omiti-lo torna o payload inválido.
Quantidade pedida.
Opcional. Comentário do cliente para esta linha de produto.
Recompensa ou cupom aplicado a este produto.
Detalhamento do preço desta linha. Modificadores usam a mesma forma em `modifierGroups[n].selectedModifiers[n].price`.
Valores por **uma unidade** (antes de multiplicar por `quantity`).
Código de moeda ISO 4217 (ex.: `BRL`, `USD`).
Opcional. Preço antes de preços promocionais.
Subtotal sem impostos. Em JSON pode vir como número ou string.
Percentual de desconto aplicado.
Valor do desconto.
Subtotal após descontos, antes dos impostos.
Percentual de imposto agregado da faixa.
Valor de imposto da faixa.
Total final da faixa.
Preço de lista sugerido.
Detalhamento por imposto (ex.: `IVA`, ou ICMS, PIS, COFINS no Brasil). Entradas podem omitir `metadata` quando não aplicável.
Código ou rótulo do imposto (ex.: `IVA`, `icms`, `pis`, `cofins`).
Alíquota desta linha (geralmente string decimal como `0.00`).
Valor do imposto nesta linha.
Opcional. Campos fiscais por região (ex.: `cst` no ICMS).
Mesmas chaves que `unitPrice`. Representa a **linha inteira** (em geral valores unitários escalados pela `quantity`). Inclua a mesma forma de `taxes[]` quando a API retornar detalhe fiscal por linha.
Grupos de modificadores selecionados.
ID do grupo de modificadores.
Descrição do grupo de modificadores.
Opções de modificador escolhidas.
ID da resposta/opção.
Produto usado como esta opção de modificador.
Nome da opção de modificador.
Tipo do item. Valores aceitos: `COMBO` (produto com grupos de modificadores não vazios), `PRODUCT` (produto vendável usado como opção de modificador), `MODIFIER` (opção de modificador puro), `PACKAGING` (item de embalagem). Sem valor padrão — omiti-lo torna o payload inválido.
Quantidade adicionada.
Quantidade removida (para remover ingredientes).
Recompensa aplicada a este modificador.
Preço do modificador. Mesma estrutura que o preço do produto.
Grupos de modificadores aninhados (até 3 níveis).
Dados do campo `additionalInfo` do menu. Passe o valor como recebido no payload do webhook de menu.
Dados do campo `additionalInfo` do menu. Passe o valor como recebido no payload do webhook de menu.
Detalhes do envio conforme `selectedShippingMethod`.
Detalhes de delivery. Presente quando `selectedShippingMethod` é `delivery`.
Data/hora estimada de entrega.
Latitude do endereço de entrega.
Longitude do endereço de entrega.
País.
Cidade.
Rua principal.
Número da rua.
Rua secundária ou transversal.
Referência ou ponto de referência para a entrega.
ID do tipo de imóvel.
Instruções de entrega.
Número de contato no endereço de entrega.
CEP ou código postal.
Apelido do endereço (ex.: "casa", "escritório").
ID do endereço em sistema externo.
ID do endereço no Fire.
Timestamp ISO 8601 de quando o entregador chegou à loja.
Dados adicionais da entrega.
Opcional. Código de confirmação para verificar a entrega na porta.
Detalhes de pickup. Presente quando `selectedShippingMethod` é `pickup`.
Data/hora agendada do pickup.
Data/hora de início do preparo.
Unidade do tempo de preparo. Exemplo: `minute`.
Valor do tempo de preparo.
ID do tipo de imóvel.
Rótulo da opção de retirada.
Métodos de contato para a notificação de pickup.
Tipo de contato: `pager`, `sms`, `whatsapp`.
Identificador (para pager).
Código de país do telefone.
Número de telefone.
Detalhamento dos pagamentos.
Totais do pedido com detalhamento de impostos e descontos. Cada entrada é um objeto price com `currencyCode`, `subtotalWithoutTaxes`, `discountPercentage`, `discountsValue`, `subtotalIncludeDiscounts`, `taxesPercentage`, `taxValue`, `total` e opcionalmente `rewardId`.
Linhas de frete. Cada entrada usa a **mesma faixa de preço** que `totals[]`—envie o valor já calculado (base, imposto e `total`). O Fire armazena como enviado. Consulte [Frete e descontos](#frete-e-descontos).
Código de moeda ISO 4217.
Valor antes dos impostos.
Percentual de desconto aplicado a esta linha.
Valor do desconto.
Subtotal após descontos, antes dos impostos.
Percentual de imposto aplicado.
Valor do imposto.
Total da linha com impostos.
Cobranças adicionais como gorjetas ou custos de embalagem.
Tipo do item. Valores aceitos: `COMBO` (produto com grupos de modificadores não vazios), `PRODUCT` (produto simples vendável), `MODIFIER` (opção de modificador puro), `PACKAGING` (item de embalagem). Normalmente `PACKAGING` para itens neste array. Sem valor padrão — omiti-lo torna o payload inválido.
Quantidade.
ID do produto associado, se houver.
Descrição da cobrança (ex.: `tip`, `packing cost`).
Código da moeda.
Valor antes dos impostos.
Valor do imposto.
Total com impostos incluídos.
Linhas de desconto de promoções ou cupons que o **estabelecimento absorve** (o custo fica por conta do restaurante). Cada entrada usa os **mesmos campos de faixa de preço** que `totals[]` e `shippingCost[]`. **Deixe este array vazio para descontos do agregador** — esses são modelados como uma entrada em `paymentMethods[]`. Consulte [Descontos do agregador](#descontos-do-agregador).
Código de moeda ISO 4217.
Base tributável antes do desconto.
Percentual de desconto nesta linha.
Valor abatido pelo desconto.
Subtotal após o desconto, antes dos impostos.
Percentual de imposto aplicado após o desconto.
Valor do imposto.
Total da linha com impostos.
Resumo de impostos.
Nome do imposto (ex.: `IVA 15%`).
Código da moeda.
Base tributável.
Percentual do imposto.
Valor total do imposto.
Métodos de pagamento utilizados.
Nome do processador de pagamento (ex.: `Kushki`, `Efectivo`).
Código da moeda.
Código do método de pagamento. Use `AGGREGATOR_DISCOUNT` quando o agregador cobre um desconto promocional e reembolsa o estabelecimento — sempre combinado com `transactionType: "BENEFIT"`. Consulte [Descontos do agregador](#descontos-do-agregador).
Tipo de transação. Valores comuns: `ONLINE`, `CREDIT`, `CASH`. Use `BENEFIT` quando `paymentMethodCode` for `AGGREGATOR_DISCOUNT`.
Identificador da transação.
Status da transação (ex.: `APPROVED`).
Indica se o valor exato foi entregue.
Valor cobrado com este método.
Número de autorização NFCE (código SiTef 952 / IdAuth). Opcional.
Via do cliente: texto do comprovante impresso para o portador (código SiTef 121 / ReceiptCustomer). Opcional.
Via do estabelecimento: texto do comprovante impresso para o lojista (código SiTef 122 / ReceiptMerchant). Opcional.
Dados do banco adquirente. Envie `null` para métodos de pagamento sem credenciadora.
Código da credenciadora.
Nome da credenciadora.
CNPJ da credenciadora para NFCE (código SiTef 950 / CNPJAuth). Opcional.
Dados do cartão. Envie `null` para métodos sem cartão (ex.: `AGGREGATOR_DISCOUNT`).
Bandeira do cartão (ex.: `VISA`, `MASTERCARD`, `AMEX`).
Primeiros 6 dígitos do número do cartão (BIN).
Número do cartão mascarado.
Últimos 4 dígitos do número do cartão.
Nome do titular.
País de emissão do cartão.
Identificador de bandeira específico do processador.
Tipo de leitura do cartão (código SiTef 2090 / Media). Valores aceitos: `CHIP`, `MAGNETIC`, `NFC`, `MANUAL`. Opcional.
Data da transação com info de fuso horário.
Metadados específicos do processador.
Informações de fidelidade e cupons.
Detalhamento de acumulação e resgate de pontos de fidelidade.
Pontos ganhos: `storeCost`, `marketingCost`, `totalPoints`.
Pontos resgatados: `storeCost`, `marketingCost`, `totalPoints`.
Saldo de pontos atual do cliente.
Cupons e recompensas aplicados.
Identificador da recompensa.
Nome de exibição da recompensa.
Dados adicionais da recompensa.
Metadados extras a nível de pedido (ex.: endereço IP do quiosque).
## Valores e faixas de preço
O Fire **não** escala nem recalcula preços. Envie valores na **unidade final da moeda** (por exemplo `"8.99"` para USD 8,99, não centavos). Seu POS ou agregador deve enviar montantes já calculados.
Linhas de produto, `payments.totals[]`, `payments.shippingCost[]` e `payments.discounts[]` usam as mesmas chaves de **faixa de preço**: `currencyCode`, `subtotalWithoutTaxes`, `discountPercentage`, `discountsValue`, `subtotalIncludeDiscounts`, `taxesPercentage`, `taxValue`, `total`.
| Campo da faixa | Significado usual |
| -------------------------- | ------------------------------------------ |
| `subtotalWithoutTaxes` | Base tributável antes do desconto da linha |
| `discountsValue` | Valor do desconto nesta linha |
| `subtotalIncludeDiscounts` | Base após desconto, antes dos impostos |
| `taxValue` | Imposto sobre a base com desconto |
| `total` | Total da linha como enviado |
## Frete e descontos
### Descontos por linha de produto
Aplique descontos em `order.products[n].price.unitPrice` e `totalPrice` (mesmos números quando `quantity` é 1). Exemplo: **10% de desconto** em base **15.00** com **IVA 12%** → `discountsValue` **1.50**, `subtotalIncludeDiscounts` **13.50**, `taxValue` **1.62**, `total` da linha **15.12**.
### `payments.shippingCost[]`
Taxas de entrega como uma ou mais linhas na faixa de preço. Nos exemplos, o imposto do frete segue a mesma lógica dos produtos.
### `payments.discounts[]`
Descontos em nível de pedido (promos, cupons) como linhas na faixa de preço. Use quando o desconto **não** estiver totalmente refletido no `discountsValue` de cada produto e o custo é **absorvido pelo estabelecimento**. Descontos de produto e `payments.discounts[]` podem ser combinados; concilie com `paymentMethods[].totalBill`.
### `payments.totals[]`
Resumo da parte de **produtos** do pedido. Ao conciliar: **produtos (totals) + frete − descontos do pedido ≈ valor pago**.
O Fire não rejeita a requisição se `paymentMethods[].totalBill` divergir levemente da soma das faixas — mesmo assim envie valores consistentes do seu sistema de origem.
## Descontos de combo
Quando um produto combo tem **preço do contêiner igual a 0** (ou seja, `type: "COMBO"` com `subtotalWithoutTaxes: 0`), o desconto do combo **não deve ser colocado** na linha do contêiner. Atribuir `discountsValue` a uma base zero produz totais negativos, que o Fire rejeita.
Em vez disso, **distribua o valor total do desconto entre os `selectedModifiers`** que compõem o combo.
### Regras
| Regra | Detalhe |
| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| Contêiner COMBO (`price === 0`) | Todos os campos de preço devem ser `0` — sem `discountsValue`, sem valores negativos |
| Localização do desconto | Distribuir `discountsValue` entre os modificadores proporcionalmente ao preço base de cada um |
| Restrição não negativa | Após aplicar o desconto, cada modificador deve ter `subtotalIncludeDiscounts >= 0` e `total >= 0` |
| Reconciliação de totais | `SUM(modifier.totalPrice.discountsValue)` deve ser igual ao desconto total do combo, e as somas devem coincidir com `payments.totals[]` |
### Algoritmo de distribuição
```
D = desconto total do combo
B = SUM(modifier.price.totalPrice.subtotalWithoutTaxes)
discount_i = ROUND(D × (base_i / B), 2)
net_i = base_i − discount_i // deve ser >= 0
```
Ajustar o arredondamento no último modificador para que `SUM(discount_i) === D` exatamente. Se a distribuição proporcional deixasse algum modificador com `net_i < 0`, limitar o desconto desse item à sua base (`discount_i = base_i`, líquido = 0) e redistribuir o restante entre os demais.
### Exemplo — desconto BRL 17,94 em um combo (base BRL 89,68)
A seguir é mostrado o padrão **incorreto** (desconto no contêiner) e o padrão **correto** (desconto distribuído entre os modificadores).
```json Incorreto — desconto no COMBO com base zero (totais negativos) theme={null}
{
"type": "COMBO",
"price": {
"unitPrice": {
"subtotalWithoutTaxes": "0",
"discountsValue": "17.94",
"subtotalIncludeDiscounts": "-17.94",
"total": "-17.94"
}
}
}
```
```json Correto — contêiner COMBO em zero, desconto nos modificadores theme={null}
{
"type": "COMBO",
"price": {
"unitPrice": { "subtotalWithoutTaxes": "0", "discountsValue": "0", "subtotalIncludeDiscounts": "0", "total": "0" },
"totalPrice": { "subtotalWithoutTaxes": "0", "discountsValue": "0", "subtotalIncludeDiscounts": "0", "total": "0" }
},
"modifierGroups": [
{
"selectedModifiers": [
{
"product": "12 Coxinhas da Asa",
"type": "MODIFIER",
"price": {
"unitPrice": { "subtotalWithoutTaxes": "22.30", "discountsValue": "4.46", "subtotalIncludeDiscounts": "17.84", "total": "17.84" },
"totalPrice": { "subtotalWithoutTaxes": "22.30", "discountsValue": "4.46", "subtotalIncludeDiscounts": "17.84", "total": "17.84" }
}
},
{
"product": "Batata Média",
"type": "MODIFIER",
"price": {
"unitPrice": { "subtotalWithoutTaxes": "4.59", "discountsValue": "0.92", "subtotalIncludeDiscounts": "3.67", "total": "3.67" },
"totalPrice": { "subtotalWithoutTaxes": "4.59", "discountsValue": "0.92", "subtotalIncludeDiscounts": "3.67", "total": "3.67" }
}
}
]
}
]
}
```
Distribuição completa para este exemplo (todos os 7 modificadores):
| Modificador | Base | `discountsValue` | Líquido |
| ------------------- | --------: | ---------------: | --------: |
| 12 Coxinhas da Asa | 22,30 | 4,46 | 17,84 |
| Batata Média | 4,59 | 0,92 | 3,67 |
| Onion Rings | 7,50 | 1,50 | 6,00 |
| Batata Grande | 6,50 | 1,30 | 5,20 |
| Molho Secreto 120g | 4,09 | 0,82 | 3,27 |
| Água sem Gás (×2) | 29,80 | 5,96 | 23,84 |
| Água com gás | 14,90 | 2,98 | 11,92 |
| **Contêiner COMBO** | **0** | **0** | **0** |
| **Total** | **89,68** | **17,94** | **71,74** |
`payments.totals[0].subtotalWithoutTaxes` = **89,68**, `subtotalIncludeDiscounts` = **71,74** ✓
## Descontos do agregador
Quando a plataforma do agregador (iFood, Rappi, UberEats, etc.) aplica um desconto promocional ao cliente, o **agregador reembolsa o estabelecimento** — o local sempre recebe o valor integral. Por isso o desconto não reduz a receita do estabelecimento e **não deve aparecer em `payments.discounts[]`**.
Modele como uma entrada adicional em `payments.paymentMethods[]`:
| Quem paga | O quê | Como modelar |
| -------------------------- | ----------------------------------------------------------- | --------------------------------------------------------------------------- |
| Cliente | Produtos + frete + cobranças extras − desconto do agregador | `paymentMethods[n]` com o código de pagamento real (`CREDIT`, `CASH`, etc.) |
| Agregador | Valor do desconto (reembolso ao estabelecimento) | `paymentMethods[n]` com `paymentMethodCode: "AGGREGATOR_DISCOUNT"` |
| **Estabelecimento recebe** | **Produtos + frete + cobranças extras completos** | — |
### Campos obrigatórios na entrada `AGGREGATOR_DISCOUNT`
| Campo | Valor |
| ------------------- | ---------------------------------------------------------------- |
| `paymentMethodCode` | `"AGGREGATOR_DISCOUNT"` — mesmo código para todos os agregadores |
| `processor` | Nome do agregador: `"IFOOD"`, `"RAPPI"`, `"UBEREATS"`, … |
| `transactionType` | `"BENEFIT"` |
| `transactionStatus` | `"APPROVED"` |
| `card` | `null` |
| `totalBill` | Valor do desconto |
### Regra de saldo
A soma de **todos** os `paymentMethods[].totalBill` — incluindo a entrada `AGGREGATOR_DISCOUNT` — deve ser igual ao total bruto do pedido:
```
SUM(paymentMethods[].totalBill)
= SUM(order.products[].price.totalPrice.total)
+ SUM(payments.extraCharges[].total)
+ SUM(payments.shippingCost[].total)
```
`payments.discounts[]` fica **vazio**.
```json Entrega simples (sem descontos) theme={null}
{
"orderId": "AGG-SIMPLE-001",
"source": "App",
"platform": "Android",
"channel": { "uid": "CH-IFOOD-001", "code": "Aggregator", "metadata": {} },
"service": { "uid": "3", "code": "DELIVERY", "metadata": {} },
"selectedShippingMethod": "delivery",
"client": { "name": "Jane", "lastName": "Doe", "phone": "+1555000111" },
"store": { "id": 10, "name": "Gran Santa Fe", "code": "T001", "vendorId": 8 },
"order": {
"products": [
{
"productId": "991117",
"product": "Classic Burger",
"type": "PRODUCT",
"quantity": 1,
"price": {
"unitPrice": {
"currencyCode": "USD",
"subtotalWithoutTaxes": "7.7826",
"discountPercentage": "0.0000",
"discountsValue": "0.0000",
"subtotalIncludeDiscounts": "7.7826",
"taxesPercentage": "15.0000",
"taxValue": "1.1739",
"total": "8.9900"
},
"totalPrice": {
"currencyCode": "USD",
"subtotalWithoutTaxes": "7.7826",
"discountPercentage": "0.0000",
"discountsValue": "0.0000",
"subtotalIncludeDiscounts": "7.7826",
"taxesPercentage": "15.0000",
"taxValue": "1.1739",
"total": "8.9900"
}
},
"additional_info": { "externalCode": "burger-classic-ext-001" }
}
]
},
"shippingMethod": {
"delivery": {
"city": "Guayaquil",
"mainStreet": "Av. Principal 123",
"zipCode": "090101",
"additional_info": {
"deliveryConfirmationCode": "4821"
}
}
},
"payments": {
"totals": [
{
"currencyCode": "USD",
"subtotalWithoutTaxes": "7.7826",
"discountPercentage": "0.0000",
"discountsValue": "0.0000",
"subtotalIncludeDiscounts": "7.7826",
"taxesPercentage": "15.0000",
"taxValue": "1.1739",
"total": "8.9900"
}
],
"shippingCost": [
{
"currencyCode": "USD",
"subtotalWithoutTaxes": "1.5000",
"discountPercentage": "0.0000",
"discountsValue": "0.0000",
"subtotalIncludeDiscounts": "1.5000",
"taxesPercentage": "15.0000",
"taxValue": "0.2250",
"total": "1.7250"
}
],
"discounts": [],
"paymentMethods": [
{
"processor": "Kushki",
"currencyCode": "USD",
"transactionStatus": "APPROVED",
"totalBill": "10.7150"
}
]
}
}
```
```json Desconto na linha e frete theme={null}
{
"orderId": "AGG-DISC-LINE-001",
"source": "Kiosco",
"platform": "Android",
"channel": { "uid": "CH-KIOSK-001", "code": "Kiosk", "metadata": {} },
"service": { "uid": "3", "code": "DELIVERY", "metadata": {} },
"selectedShippingMethod": "delivery",
"client": { "name": "Maria", "phone": "+5511999999999" },
"store": { "id": 20, "name": "Centro", "code": "T020", "vendorId": 16 },
"order": {
"products": [
{
"productId": "SKU-COMBO-001",
"product": "Combo Especial",
"type": "COMBO",
"quantity": 1,
"comment": "Sin cebolla",
"price": {
"unitPrice": {
"currencyCode": "BRL",
"subtotalWithoutTaxes": "15.00",
"discountPercentage": "10.0000",
"discountsValue": "1.50",
"subtotalIncludeDiscounts": "13.50",
"taxesPercentage": "12.0000",
"taxValue": "1.62",
"total": "15.12"
},
"totalPrice": {
"currencyCode": "BRL",
"subtotalWithoutTaxes": "15.00",
"discountPercentage": "10.0000",
"discountsValue": "1.50",
"subtotalIncludeDiscounts": "13.50",
"taxesPercentage": "12.0000",
"taxValue": "1.62",
"total": "15.12"
}
},
"modifierGroups": [
{
"id": "MG-SAUCE-001",
"description": "Molho",
"selectedModifiers": [
{
"answerId": "ANS-BBQ-001",
"productId": "MOD-BBQ-001",
"product": "Molho BBQ",
"type": "MODIFIER",
"quantity": 1,
"additional_info": { "externalCode": "sauce-bbq-ext-001" }
}
]
}
],
"additional_info": { "externalCode": "combo-especial-ext-001" }
}
]
},
"shippingMethod": {
"delivery": {
"city": "São Paulo",
"mainStreet": "Rua Exemplo 100",
"zipCode": "01310-100"
}
},
"payments": {
"totals": [
{
"currencyCode": "BRL",
"subtotalWithoutTaxes": "15.00",
"discountPercentage": "10.0000",
"discountsValue": "1.50",
"subtotalIncludeDiscounts": "13.50",
"taxesPercentage": "12.0000",
"taxValue": "1.62",
"total": "15.12"
}
],
"shippingCost": [
{
"currencyCode": "BRL",
"subtotalWithoutTaxes": "3.50",
"discountPercentage": "0.0000",
"discountsValue": "0.0000",
"subtotalIncludeDiscounts": "3.50",
"taxesPercentage": "12.0000",
"taxValue": "0.42",
"total": "3.92"
}
],
"discounts": [],
"paymentMethods": [
{
"processor": "CREDIT_CARD",
"currencyCode": "BRL",
"transactionStatus": "APPROVED",
"totalBill": "19.04"
}
]
}
}
```
```json Vários produtos, frete e desconto do pedido theme={null}
{
"orderId": "AGG-PROMO-001",
"source": "Aggregator",
"channel": { "uid": "CH-AGG-001", "code": "Aggregator", "metadata": {} },
"service": { "uid": "3", "code": "DELIVERY", "metadata": {} },
"selectedShippingMethod": "delivery",
"client": { "name": "João", "lastName": "Silva", "phone": "+5511987654321" },
"store": { "id": 30, "name": "Lab Brasil", "code": "K000", "vendorId": 8 },
"order": {
"products": [
{
"productId": "BURG-001",
"product": "Hamburguesa Clásica",
"type": "PRODUCT",
"quantity": 2,
"price": {
"unitPrice": {
"currencyCode": "BRL",
"subtotalWithoutTaxes": "11.52",
"discountPercentage": "0.0000",
"discountsValue": "0.0000",
"subtotalIncludeDiscounts": "11.52",
"taxesPercentage": "12.0000",
"taxValue": "1.38",
"total": "12.90"
},
"totalPrice": {
"currencyCode": "BRL",
"subtotalWithoutTaxes": "23.04",
"discountPercentage": "0.0000",
"discountsValue": "0.0000",
"subtotalIncludeDiscounts": "23.04",
"taxesPercentage": "12.0000",
"taxValue": "2.76",
"total": "25.80"
}
},
"additional_info": { "externalCode": "hamburguesa-clasica-ext-001" }
},
{
"productId": "BEV-001",
"product": "Refresco 500ml",
"type": "PRODUCT",
"quantity": 1,
"price": {
"unitPrice": {
"currencyCode": "BRL",
"subtotalWithoutTaxes": "4.46",
"discountPercentage": "0.0000",
"discountsValue": "0.0000",
"subtotalIncludeDiscounts": "4.46",
"taxesPercentage": "12.0000",
"taxValue": "0.54",
"total": "5.00"
},
"totalPrice": {
"currencyCode": "BRL",
"subtotalWithoutTaxes": "4.46",
"discountPercentage": "0.0000",
"discountsValue": "0.0000",
"subtotalIncludeDiscounts": "4.46",
"taxesPercentage": "12.0000",
"taxValue": "0.54",
"total": "5.00"
}
},
"additional_info": { "externalCode": "refresco-500ml-ext-001" }
}
]
},
"shippingMethod": {
"delivery": { "city": "São Paulo", "mainStreet": "Av. Paulista 1000" }
},
"payments": {
"totals": [
{
"currencyCode": "BRL",
"subtotalWithoutTaxes": "27.50",
"discountPercentage": "0.0000",
"discountsValue": "0.0000",
"subtotalIncludeDiscounts": "27.50",
"taxesPercentage": "12.0000",
"taxValue": "3.30",
"total": "30.80"
}
],
"shippingCost": [
{
"currencyCode": "BRL",
"subtotalWithoutTaxes": "3.50",
"discountPercentage": "0.0000",
"discountsValue": "0.0000",
"subtotalIncludeDiscounts": "3.50",
"taxesPercentage": "0.0000",
"taxValue": "0.0000",
"total": "3.50"
}
],
"discounts": [
{
"currencyCode": "BRL",
"subtotalWithoutTaxes": "34.30",
"discountPercentage": "0.0000",
"discountsValue": "2.00",
"subtotalIncludeDiscounts": "32.30",
"taxesPercentage": "0.0000",
"taxValue": "0.0000",
"total": "2.00"
}
],
"paymentMethods": [
{
"processor": "99",
"currencyCode": "BRL",
"transactionStatus": "APPROVED",
"totalBill": "32.30"
}
]
}
}
```
```json Desconto do agregador (iFood reembolsa BRL 1.00) theme={null}
{
"orderId": "AGG-DISC-IFOOD-001",
"source": "Aggregator",
"channel": { "uid": "CH-IFOOD-001", "code": "Aggregator", "metadata": {} },
"service": { "uid": "3", "code": "DELIVERY", "metadata": {} },
"selectedShippingMethod": "delivery",
"client": { "name": "João", "lastName": "Silva", "phone": "+5511987654321" },
"store": { "id": 30, "name": "Lab Brasil", "code": "K000", "vendorId": 8 },
"order": {
"products": [
{
"productId": "PROD-TESTE-001",
"product": "PEDIDO DE TESTE Suc",
"type": "PRODUCT",
"quantity": 2,
"price": {
"unitPrice": {
"currencyCode": "BRL",
"subtotalWithoutTaxes": "14.90",
"discountPercentage": "0.0000",
"discountsValue": "0.0000",
"subtotalIncludeDiscounts": "14.90",
"taxesPercentage": "0.0000",
"taxValue": "0.0000",
"total": "14.90"
},
"totalPrice": {
"currencyCode": "BRL",
"subtotalWithoutTaxes": "29.80",
"discountPercentage": "0.0000",
"discountsValue": "0.0000",
"subtotalIncludeDiscounts": "29.80",
"taxesPercentage": "0.0000",
"taxValue": "0.0000",
"total": "29.80"
}
},
"additional_info": { "externalCode": "pedido-teste-ext-001" }
}
]
},
"shippingMethod": {
"delivery": { "city": "São Paulo", "mainStreet": "Av. Paulista 1000", "zipCode": "01310-100" }
},
"payments": {
"totals": [
{
"currencyCode": "BRL",
"subtotalWithoutTaxes": "29.80",
"discountPercentage": "0.0000",
"discountsValue": "0.0000",
"subtotalIncludeDiscounts": "29.80",
"taxesPercentage": "0.0000",
"taxValue": "0.0000",
"total": "29.80"
}
],
"shippingCost": [
{
"currencyCode": "BRL",
"subtotalWithoutTaxes": "8.90",
"discountPercentage": "0.0000",
"discountsValue": "0.0000",
"subtotalIncludeDiscounts": "8.90",
"taxesPercentage": "0.0000",
"taxValue": "0.0000",
"total": "8.90"
}
],
"extraCharges": [
{
"type": "PACKAGING",
"quantity": 1,
"description": "Taxa de serviço",
"currencyCode": "BRL",
"subtotalWithoutTaxes": "0.99",
"taxValue": "0.0000",
"total": "0.99"
}
],
"discounts": [],
"paymentMethods": [
{
"processor": "IFOOD",
"currencyCode": "BRL",
"paymentMethodCode": "CREDIT",
"transactionType": "ONLINE",
"transactionStatus": "APPROVED",
"exactPayment": true,
"totalBill": "38.69",
"id_auth": "123456",
"receipt_customer": "COMPROVANTE CLIENTE\nAMEX ****1234\nAPROVADO",
"receipt_merchant": "COMPROVANTE ESTABELECIMENTO\nAMEX ****1234\nAPROVADO",
"card": {
"brand": "AMEX",
"bin": "378282",
"mask": "3782 82****1234",
"lastFourDigits": "1234",
"holder": "JOAO SILVA",
"cardCountry": "BR",
"externalCardBrandId": "",
"media": "CHIP"
},
"acquirer": {
"code": "01",
"name": "CIELO",
"cnpj": "01.027.058/0001-91"
}
},
{
"processor": "IFOOD",
"currencyCode": "BRL",
"paymentMethodCode": "AGGREGATOR_DISCOUNT",
"transactionType": "BENEFIT",
"transactionId": "0ec06303-28f8-4d1f-aa3d-8b88aadb9814",
"transactionStatus": "APPROVED",
"exactPayment": true,
"totalBill": "1.00",
"card": null,
"acquirer": { "code": "", "name": "" }
}
]
}
}
```
## Conciliação dos exemplos
| Exemplo | Produtos (`totals[].total`) | Frete (`shippingCost[].total`) | Desconto do pedido (`discounts[].discountsValue`) | Pago (`totalBill`) |
| ------------------------- | --------------------------: | -----------------------------: | ------------------------------------------------: | ---------------------------------------------------: |
| Entrega simples | 8.99 | 1.73 | — | **10.72** |
| Desconto na linha + frete | 15.12 | 3.92 | — | **19.04** |
| Vários produtos + promo | 30.80 | 3.50 | 2.00 | **32.30** |
| Desconto do agregador | 29.80 | 8.90 | — | **39.69** (CREDIT 38.69 + AGGREGATOR\_DISCOUNT 1.00) |
Notas de cálculo:
* **Entrega simples:** 8.99 + 1.73 = **10.72**.
* **Desconto na linha:** 10% sobre 15.00 → IVA sobre 13.50 → produto **15.12**; frete 3.50 + IVA 12% = **3.92**; **15.12 + 3.92 = 19.04**.
* **Vários produtos + promo:** hambúrgueres **25.80** + bebida **5.00** = **30.80**; + frete **3.50** = 34.30; − promo **2.00** = **32.30** pago.
* **Desconto do agregador:** produtos **29.80** + embalagem **0.99** + frete **8.90** = **39.69** bruto; cliente paga **38.69** (CREDIT) + agregador reembolsa **1.00** (AGGREGATOR\_DISCOUNT) = **39.69** ✓. `payments.discounts` fica vazio.
```json 200 theme={null}
{
"data": {
"uid": "92eb4720-dbee-4786-ad76-b0b01aa47f36",
"order_code": "99-2c6970fd-a164-48bd-9f45-d5098a679a8f",
"account_uid": "100",
"vendor_uid": "100.6.1350",
"store_uid": "100.6.1350.1",
"catalog_uid": "200a6bf1-55dd-4c9b-af2b-07a62cb0d6f2",
"channel": {
"uid": "200a6bf1-55dd-4c9b-af2b-07a62cb0d6f2",
"code": "KEETA",
"metadata": {
"partner": "99"
}
},
"service": {
"uid": "91c2c168-5a4b-4944-977e-75a1ea7a77e7",
"code": "DELIVERY",
"metadata": {}
},
"device": {
"uid": "99-aggregator-device",
"name": "99 Aggregator",
"metadata": {
"ip": "0.0.0.0"
}
},
"operator": {
"uid": "99-operator",
"name": "99",
"session": {
"uid": "sess-99-aggregator"
}
},
"store": {
"uid": "100.6.1350.1",
"code": "K000",
"name": "Laboratorio Brasil",
"latitude": "-23.5632",
"longitude": "-46.6543",
"vendor_uid": "100.6.1350",
"vendor_name": "Sandbox Brasil"
},
"anonymous_customer_uid": "99-client-e24b0c40-43ff-4d0e-b384-b1f3e1173193",
"customer_uid": null,
"customer": {
"uid": "99-client-e24b0c40-43ff-4d0e-b384-b1f3e1173193",
"name": "João",
"email": "joao.silva@email.com",
"phone": "11987654321",
"last_name": "Silva",
"gov_id_type": "CPF",
"gov_id_number": "123.456.789-09"
},
"billing_uid": null,
"billing": null,
"fulfillment": {
"method": "DELIVERY",
"details": {
"uid": "99-client-e24b0c40-43ff-4d0e-b384-b1f3e1173193",
"city": "São Paulo",
"country": "Brasil",
"latitude": "-23.5632",
"zip_code": "01310-100",
"longitude": "-46.6543",
"reference": "Apto 42",
"main_street": "Av. Paulista 1000",
"delivery_date": "2026-05-11T14:38:16.360Z"
},
"catalog_uid": "200a6bf1-55dd-4c9b-af2b-07a62cb0d6f2"
},
"status": "COMPLETED",
"payment_status": "SUCCEEDED",
"payment_methods": [
{
"uid": "6781726c-4dbb-4cb9-a8e6-a76a7283b102",
"total": "347800",
"method": "99",
"details": {
"mid": null,
"tid": null,
"card": {
"bin": "",
"mask": "",
"brand": "",
"holder": "",
"card_country": "",
"last_four_digits": "",
"external_card_brand_id": "CASH"
},
"voucher": null,
"acquirer": {
"code": "",
"name": ""
},
"metadata": {},
"processor": "99",
"total_bill": "347800",
"currency_code": "BRL",
"exact_payment": false,
"transaction_id": "99-txn-5d7faa7d-f1aa-4af2-9f57-614cf5346eb4",
"reference_number": null,
"transaction_date": {
"date": "2026-05-11T14:38:17.482Z",
"time_zone_name": "UTC",
"time_zone_type": "0"
},
"transaction_type": "cash",
"authorization_code": "",
"transaction_status": "APPROVED",
"customer_cash_amount": "0"
},
"metadata": {},
"currency_code": "BRL"
}
],
"metadata": {
"pos": {
"discount": false,
"order_id": "99-2c6970fd-a164-48bd-9f45-d5098a679a8f",
"account_id": "100",
"created_at": "2026-05-11T14:38:16.360Z",
"order_comment": ""
},
"additional_info": {}
},
"created_at": "2026-05-11 14:38:18.767989",
"updated_at": "2026-05-11 14:38:18.767989",
"deleted_at": null,
"order_lines": [
{
"uid": "2fe6b60a-50e0-40f3-8040-91a26f1888b5",
"hash": "001224591808cb3551c9d0c248b739ef07dd8dd3f958d3eb1251ca5f022bad48",
"price": {
"unit_price": [
{
"taxes": [
{
"name": "IVA",
"percentage": "0"
}
],
"metadata": {},
"discounts": [],
"net_price": "17.39",
"gross_price": "17.39",
"taxes_value": "0",
"currency_code": "BRL",
"discount_value": "0",
"subtotal_before_taxes": "17.39"
}
],
"total_price": [
{
"taxes": [
{
"name": "IVA",
"percentage": "0"
}
],
"metadata": {},
"discounts": [],
"net_price": "34.78",
"gross_price": "34.78",
"taxes_value": "0",
"currency_code": "BRL",
"discount_value": "0",
"subtotal_before_taxes": "34.78"
}
]
},
"item_id": "001224591808cb3551c9d0c248b739ef07dd8dd3f958d3eb1251ca5f022bad48",
"quantity": "2",
"item_type": "PRODUCT",
"store_uid": "100.6.1350.1",
"updated_at": "2026-05-11T14:38:17.481Z",
"vendor_uid": "100.6.1350",
"fulfillment": {
"method": "DELIVERY",
"catalog_uid": "200a6bf1-55dd-4c9b-af2b-07a62cb0d6f2"
},
"line_totals": [
{
"taxes": [
{
"name": "IVA",
"percentage": "0"
}
],
"total": "34.78",
"subtotal": "34.78",
"discounts": [],
"taxes_value": "0",
"currency_code": "BRL",
"discount_value": "0",
"subtotal_before_taxes": "34.78"
}
],
"modifier_groups": [],
"item_description": "X-Burguer",
"selected_currency": "BRL"
}
],
"totals": [
{
"taxes": [
{
"name": "IVA",
"percentage": "0"
}
],
"total": "34.78",
"subtotal": "34.78",
"discounts": [],
"taxes_value": "0",
"currency_code": "BRL",
"discount_value": "0",
"subtotal_before_taxes": "34.78"
}
]
},
"isArray": false,
"status": 200,
"method": "POST",
"pathname": "/stage/api/v4/aggregator/orders",
"duration": 4900,
"traceId": "1-6a01e9d9-7c9577787de4d07a2c14686b;Parent"
}
```
```json 400 theme={null}
{
"error": {
"code": "validation_error",
"message": "channelId is required"
}
}
```
```json 409 theme={null}
{
"error": {
"code": "duplicate_order",
"message": "An order with orderId '0000012194-081101' already exists"
}
}
```