> ## Documentation Index
> Fetch the complete documentation index at: https://docs.onbeef.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Entenda os dados do pedido

> Leia os identificadores, os itens por quilo, os totais, o pagamento e as datas que vêm na consulta do pedido.

`GET /v1/orders/{orderId}` devolve o pedido como ele está agora. A lista completa, com os campos fixos para ignorar, está em [Consultar pedido](https://docs.onbeef.app/api-reference/orders/get-order.md).

## Identificadores

```json theme={null}
{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "displayId": "4F15BA00B",
  "salesChannel": "CATALOG",
  "lastEvent": "READY_FOR_PICKUP",
  "merchant": { "id": "LOJA-01", "name": "Açougue Exemplo" }
}
```

* **`id`.** Identificador único. Guarde: é ele que entra em `GET /v1/orders/{orderId}`.
* **`displayId`.** Código que a loja vê no painel e na impressão. Mostre para a loja conferir. O número curto do painel ("Pedido 300") não vem na API e reinicia todo mês.
* **`merchant.id`.** Código da loja no PDV que sincroniza o catálogo dela. Sem sincronização, vem o UUID da loja na Onbeef. Se não é você quem envia o catálogo, roteie pela chave que fez a consulta.

## Itens

```json theme={null}
{
  "items": [
    {
      "id": "1001",
      "name": "Picanha",
      "externalCode": "000123",
      "kit_id": null,
      "unit": "KG",
      "quantity": 1.32,
      "specialInstructions": "Bem limpa",
      "unitPrice": { "value": 94.9, "currency": "BRL" },
      "originalPrice": { "value": 94.9, "currency": "BRL" },
      "optionsPrice": { "value": 3, "currency": "BRL" },
      "totalPrice": { "value": 128.27, "currency": "BRL" },
      "options": [
        {
          "id": "0b7d4c7a-93b1-4c53-8a55-7d2c5e0e4b20",
          "name": "Bife",
          "quantity": 1.32,
          "unit": "KG",
          "specialInstructions": "Bifes de 2 dedos",
          "unitPrice": { "value": 0, "currency": "BRL" },
          "totalPrice": { "value": 0, "currency": "BRL" }
        },
        {
          "id": "5a1d2c3b-7e8f-4a9b-b0c1-d2e3f4a5b6c7",
          "name": "Embalagem a vácuo",
          "quantity": 1,
          "unitPrice": { "value": 3, "currency": "BRL" },
          "totalPrice": { "value": 3, "currency": "BRL" }
        }
      ]
    },
    {
      "id": "2001",
      "name": "Refrigerante 2 L",
      "externalCode": null,
      "kit_id": null,
      "unit": "UN",
      "quantity": 2,
      "specialInstructions": null,
      "unitPrice": { "value": 10, "currency": "BRL" },
      "originalPrice": { "value": 10, "currency": "BRL" },
      "optionsPrice": { "value": 0, "currency": "BRL" },
      "totalPrice": { "value": 20, "currency": "BRL" },
      "options": []
    }
  ]
}
```

* **`id` é o Código de integração com PDV do produto**, o mesmo `id` que você envia no catálogo, sem prefixo.
* **`id` em formato UUID é produto sem vínculo.** O valor muda a cada pedido: não cadastre como código de produto. Peça à loja para preencher o código e consulte de novo, mesmo se você não envia catálogo. Em kit, confira cada produto. Veja [Vincule produtos que já existem](https://docs.onbeef.app/guides/catalog-linking.md).
* **`externalCode` é o código de balança.** Não é o código do PDV.
* **`unit: "KG"`.** `quantity` vem em quilos (1.32 = 1,320 kg) e `unitPrice` é o preço por quilo. Com `"UN"`, unidades e preço de cada uma.
* **Corte.** Vem em `options[]` com `unit: "KG"`, peso e observação, sempre com preço zero. O `id` é o de `cuts[].id` em `GET /v1/merchant`.
* **Adicional.** Vem em `options[]` sem `unit`, com preço. O `id` é sempre um UUID.
* **Observação.** A do item vem em `specialInstructions`. A do pedido, em `extraInfo`.

### Valor da linha

```text theme={null}
totalPrice = unitPrice x quantity + optionsPrice
```

Na Picanha: 94,90 x 1,32 = 125,27, mais 3,00 do adicional, dá 128,27. Se o documento fiscal exige `unitPrice` x `quantity` = `totalPrice`, lance o adicional como linha à parte.

### Kit

O kit vem como uma linha, com `kit_id: null`. Cada produto escolhido vem em outra, com `kit_id` igual ao `id` da linha do kit.

* **Kit com preço próprio, como o de Preço Fechado.** A linha do kit traz o preço. As dos produtos vêm com valor zero, ou só com o acréscimo da escolha.
* **Kit de Preço Aberto.** A linha do kit vem com valor zero. Cada produto traz o próprio preço.

```json theme={null}
{
  "items": [
    { "id": "3001", "name": "Kit Churrasco", "kit_id": null, "unit": "UN", "quantity": 1,
      "unitPrice": { "value": 199.9, "currency": "BRL" }, "totalPrice": { "value": 199.9, "currency": "BRL" } },
    { "id": "1001", "name": "Picanha", "kit_id": "3001", "unit": "KG", "quantity": 1,
      "unitPrice": { "value": 0, "currency": "BRL" }, "totalPrice": { "value": 0, "currency": "BRL" } },
    { "id": "2001", "name": "Refrigerante 2 L", "kit_id": "3001", "unit": "UN", "quantity": 2,
      "unitPrice": { "value": 0, "currency": "BRL" }, "totalPrice": { "value": 0, "currency": "BRL" } }
  ]
}
```

O exemplo é um kit de **Preço Fechado**. Cada real aparece em uma linha só: some o `totalPrice` de todas as linhas, como a API faz em `total.itemsPrice`. O `id` do kit é o código do PDV, se a loja preencheu, ou um UUID.

## Totais

```text theme={null}
orderAmount = itemsPrice + otherFees - discount
```

`itemsPrice` soma o `totalPrice` dos itens. `otherFees` soma o frete (`DELIVERY_FEE`) e a taxa de serviço (`SERVICE_FEE`). Os valores vêm em reais, com duas casas, arredondados: 1,320 kg a R\$ 94,90 dá 125,268 e sai 125.27.

Frete grátis da fidelidade vem como frete mais um desconto do mesmo valor. Se a loja não cobra frete, `otherFees` vem sem `DELIVERY_FEE`.

```json theme={null}
{
  "otherFees": [
    { "name": "Frete", "type": "DELIVERY_FEE", "price": { "value": 8, "currency": "BRL" } }
  ],
  "discounts": [
    {
      "amount": { "value": 8, "currency": "BRL" },
      "target": "DELIVERY_FEE",
      "sponsorshipValues": [
        { "name": "MERCHANT", "amount": { "value": 8, "currency": "BRL" }, "discountCode": null }
      ]
    }
  ],
  "total": {
    "itemsPrice": { "value": 148.27, "currency": "BRL" },
    "otherFees": { "value": 8, "currency": "BRL" },
    "discount": { "value": 8, "currency": "BRL" },
    "orderAmount": { "value": 148.27, "currency": "BRL" }
  }
}
```

Aqui, 148,27 + 8,00 - 8,00 = 148,27.

* **Um item de `discounts[]` por desconto.** Cupom, clube, fidelidade, cashback, agendamento e desconto da loja, sem campo com o tipo. O cupom traz o código em `sponsorshipValues[].discountCode`. O `target` é `CART` (itens) ou `DELIVERY_FEE` (frete).
* **Desconto da loja.** O de **Desconto personalizado** vem em `discounts[]`. O de **Ajustar valor** não vem: o pedido sai com a soma dos itens. Veja [Desconto dado pela loja](https://docs.onbeef.app/guides/order-import.md#desconto-dado-pela-loja).

## Pagamento

```json theme={null}
{
  "payments": {
    "prepaid": 0,
    "pending": 148.27,
    "methods": [
      {
        "value": 148.27,
        "currency": "BRL",
        "type": "PENDING",
        "method": "CASH",
        "brand": null,
        "methodInfo": null,
        "changeFor": 200
      }
    ]
  }
}
```

* **`type: "PREPAID"`.** Já está pago. Não cobre.
* **`type: "PENDING"`.** Não está pago. Cobre na entrega só se `method` for dinheiro, PIX, cartão ou vale e a loja confirmar que o pedido é para pagar na entrega.

`method`: `PIX`, `CREDIT` (inclusive Apple Pay), `DEBIT`, `CASH`, `FOOD_VOUCHER` (vale alimentação), `MEAL_VOUCHER` (vale refeição) ou `OTHER`.

* **Online ou na entrega.** A API não tem campo que separe pagamento na entrega de pagamento online em andamento: cartão online ainda não capturado também sai `CREDIT` com `PENDING`.
* **`OTHER` nunca se cobra na porta.** O nome vem em `methodInfo`, texto livre: "Pagamento a prazo (Nota/Fiado)", "Link de pagamento", "Link via Whatsapp" ou a forma criada pela loja, como boleto.
* **Troco.** Em `CASH`, `changeFor` traz o valor que o cliente vai entregar.
* **Pago na entrega continua `PENDING`** depois do `DELIVERED`: a API não registra o recebimento na porta.
* **O valor vem do total.** `value`, `prepaid` e `pending` repetem o `total.orderAmount`, recalculado a cada consulta. Se falta pagar uma diferença depois do ajuste, o pedido sai `PENDING` com o total inteiro.
* **O que não vem.** Valor cobrado no cartão ou no PIX, estorno, data do pagamento e `currency` nos números de `payments`.

## Cliente

```json theme={null}
{
  "customer": {
    "id": "9c2e4f6a-1b3d-4e5f-8a7b-6c5d4e3f2a1b",
    "name": "João da Silva",
    "phone": { "number": "11999999999", "extension": null },
    "email": "joao@example.com",
    "documentNumber": null,
    "ordersCountOnMerchant": 3
  }
}
```

`documentNumber` traz o CPF ou CNPJ informado no pedido ou, na falta dele, o do cadastro do cliente na loja. A API não diz se o cliente pediu o documento na nota.

## Entrega, retirada e datas

Em `type: "DELIVERY"` vem o bloco `delivery`, com o endereço em `deliveryAddress` e a hora da entrega em `deliveryDateTime`. Em `"TAKEOUT"` vem o bloco `takeout`: a hora em que o cliente retirou não vem na API.

Pedido para agora vem com `orderTiming: "INSTANT"` e `schedule: null`. O agendado vem assim:

```json theme={null}
{
  "createdAt": "2026-11-12T17:30:00.000000Z",
  "orderTiming": "SCHEDULED",
  "schedule": {
    "scheduledDateTimeStart": "2026-11-14T13:00:00.000000Z",
    "scheduledDateTimeEnd": "2026-11-14T14:00:00.000000Z"
  }
}
```

`createdAt` é o dia em que o cliente fez o pedido. O dia da entrega está em `schedule`. O `start_at` do polling olha o `createdAt`: veja [Pedido agendado na virada](https://docs.onbeef.app/guides/order-import.md#pedido-agendado-na-virada).

Toda data vem em UTC, em ISO 8601. Converta para o horário da loja: `17:30` UTC é `14:30` em Brasília.

Copia uma pergunta pronta para colar no Claude, no ChatGPT ou no seu assistente

> [card] [Quando importar o pedido](https://docs.onbeef.app/guides/order-import.md)
>
> Quando peso e total não mudam mais.

> [card] [Consultar pedido](https://docs.onbeef.app/api-reference/orders/get-order.md)
>
> Todos os campos.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.