---
title: "Listar pedidos"
description: "GET /v1/orders — histórico paginado de pedidos do estabelecimento na API BeeFood."
method: "GET"
path: "/v1/orders"
url: "https://developer.beefood.com.br/docs/pedidos/listar"
group: "Pedidos"
scope: "orders:read"
lang: "pt"
---
# Listar pedidos

`GET /v1/orders`

- Produção: `https://api.beefood.app/v1/orders`
- Sandbox: `https://api-sandbox.beefood.app/v1/orders`

Retorna o histórico de pedidos do estabelecimento.

## Autenticação

Envie o access token no header `Authorization: Bearer <accessToken>`. Escopo necessário: `orders:read`. Limite: 15 requisições por minuto.



## Parâmetros de query

- `page` *integer* — Página atual da lista. Exemplo: `1`.

- `limit` *integer* — Quantidade de itens por página. Exemplo: `20`.

- `sort` *string* — Ordem da lista: mais recentes (desc) ou mais antigos (asc). Exemplo: `"desc"`.
  - *Valores:* `asc`, `desc`

- `saleDateFrom` *string (yyyy-mm-dd)* **obrigatório** — Início do período da data de venda. O intervalo entre saleDateFrom e saleDateTo não pode passar de 6 meses. Exemplo: `"2026-03-01"`.

- `saleDateTo` *string (yyyy-mm-dd)* **obrigatório** — Fim do período da data de venda. O intervalo entre saleDateFrom e saleDateTo não pode passar de 6 meses. Exemplo: `"2026-03-31"`.

- `orderType` *string* — Filtra pelo tipo do pedido: DELIVERY, PDV ou TABLE. Exemplo: `"DELIVERY"`.
  - *Valores:* `DELIVERY`, `PDV`, `TABLE`

- `orderStatus` *string* — Filtra pelo status do pedido: OPEN, RECEIVED, GROUPED, CLOSED ou CANCELLED. Exemplo: `"CLOSED"`.
  - *Valores:* `OPEN`, `RECEIVED`, `GROUPED`, `CLOSED`, `CANCELLED`

- `deliveryType` *string* — Filtra pela modalidade da entrega: DELIVERY, TAKEOUT ou DINE_IN. Exemplo: `"DELIVERY"`.
  - *Valores:* `DELIVERY`, `TAKEOUT`, `DINE_IN`

- `deliveryStatus` *string* — Filtra pelo status da entrega: WAITING, ACCEPTED, PREPARING, READY, DISPATCHED, DELIVERED ou CANCELLED. Exemplo: `"DELIVERED"`.
  - *Valores:* `WAITING`, `ACCEPTED`, `PREPARING`, `READY`, `DISPATCHED`, `DELIVERED`, `CANCELLED`

- `salesChannel` *string* — Filtra pelo canal de venda: IFOOD, 99FOOD, KEETA, AIQFOME, RAPPI, DELIVERYMUCH, UAIRANGO, TOTEM, EXTERNAL, WHATSAPP, DIGITAL_MENU ou MANUAL. Exemplo: `"DIGITAL_MENU"`.
  - *Valores:* `IFOOD`, `99FOOD`, `KEETA`, `AIQFOME`, `RAPPI`, `DELIVERYMUCH`, `UAIRANGO`, `TOTEM`, `EXTERNAL`, `WHATSAPP`, `DIGITAL_MENU`, `MANUAL`

- `merchantId` *integer* — Filtra os pedidos de um cardápio. Exemplo: `1`.

- `customerId` *integer* — Filtra pedidos de um cliente. Exemplo: `123456`.

- `documentNumber` *string* — Filtra pelo CPF ou CNPJ do cliente do pedido (somente dígitos). Exemplo: `"12345678900"`.

- `email` *string* — Filtra pelo e-mail do cliente do pedido. Exemplo: `"cliente@exemplo.com"`.

- `phone` *string* — Filtra pelo telefone do cliente do pedido (somente dígitos). Exemplo: `"11999990000"`.

- `couponCode` *string* — Filtra pelos pedidos que usaram um cupom específico. Exemplo: `"PIX15%"`.

- `commandCode` *integer | integer[]* — Filtra pelo código da comanda. Exemplo: `12`.

- `tableCode` *integer | integer[]* — Filtra pelo código da mesa. Exemplo: `5`.




## Exemplos de requisição

### cURL

```bash
curl -X GET "https://api.beefood.app/v1/orders?saleDateFrom=2026-03-01&saleDateTo=2026-03-31&page=1&limit=20&sort=desc" \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```


## Exemplos de resposta

### 200 OK

```json
{
  "items": [
    {
      "orderId": 60181897,
      "createdAt": "2026-09-27T10:30:02.000-03:00",
      "orderStatus": "GROUPED",
      "orderIdGrouped": 60181902,
      "deliveryStatus": "PREPARING",
      "orderType": "TABLE",
      "deliveryType": "TAKEOUT",
      "orderAmount": 19.58,
      "paidAmount": 0
    },
    {
      "orderId": 60181831,
      "createdAt": "2026-09-27T10:27:41.000-03:00",
      "orderStatus": "GROUPED",
      "orderIdGrouped": 60181832,
      "deliveryStatus": "PREPARING",
      "orderType": "TABLE",
      "deliveryType": "TAKEOUT",
      "orderAmount": 29.37,
      "paidAmount": 0
    },
    {
      "orderId": 60181902,
      "createdAt": "2026-09-27T10:26:55.717-03:00",
      "orderStatus": "OPEN",
      "orderType": "TABLE",
      "orderAmount": 63.7,
      "paidAmount": 0
    }
  ],
  "page": 1,
  "limit": 3,
  "total": 252,
  "pages": 84
}
```


## Campos da resposta

- `items[].orderId` *number* — ID do pedido.

- `items[].createdAt` *string (ISO 8601)* — Data/hora em que o pedido foi criado.

- `items[].orderStatus` *string* — Situação geral do pedido.
  - *Valores:* `OPEN`, `RECEIVED`, `GROUPED`, `CLOSED`, `CANCELLED`

- `items[].deliveryStatus` *string* — Situação da entrega.
  - *Valores:* `WAITING`, `ACCEPTED`, `PREPARING`, `READY`, `DISPATCHED`, `DELIVERED`, `CANCELLED`

- `items[].orderType` *string* — Tipo do pedido.
  - *Valores:* `DELIVERY`, `PDV`, `TABLE`

- `items[].deliveryType` *string* — Como o pedido será entregue ou retirado.
  - *Valores:* `DELIVERY`, `TAKEOUT`, `DINE_IN`

- `items[].orderAmount` *number* — Valor total do pedido.

- `items[].paidAmount` *number* — Quanto já foi pago.

- `page` *number* — Página atual da lista.

- `limit` *number* — Quantidade de itens por página.

- `total` *number* — Total de registros encontrados.

- `pages` *number* — Total de páginas.



## Erros

| Status | Mensagem |
| --- | --- |
| 400 | 'page' must be an integer >= 1 |
| 400 | 'limit' must be an integer between 1 and 100 |
| 400 | 'sort' must be asc or desc |
| 400 | saleDateFrom and saleDateTo are required |
| 400 | The range between saleDateFrom and saleDateTo cannot exceed 6 months |
| 400 | 'commandCode' must be a positive integer |
| 400 | 'tableCode' must be a positive integer |
| 401 | Authentication token is missing |
| 401 | Invalid or expired access token |
| 403 | This credential does not include the orders:read scope |
| 429 | Too Many Requests |
| 500 | Database error when trying to … |


## Vocabulários usados neste endpoint

## Pedidos · orderStatus

| Valor | Significado | Uso |
| --- | --- | --- |
| `OPEN` | Aberto | Lista e detalhe de pedidos |
| `RECEIVED` | Recebido | Lista e detalhe de pedidos |
| `GROUPED` | Agrupado a outro pedido | Pedido somado a outro; orderIdGrouped indica o pedido principal |
| `CLOSED` | Fechado | Lista e detalhe de pedidos |
| `CANCELLED` | Cancelado | Lista e detalhe de pedidos |

## Pedidos · deliveryStatus

Situação operacional do pedido. Aparece na lista e no detalhe e é espelhada nos webhooks de status.

| Valor | Significado | Uso |
| --- | --- | --- |
| `WAITING` | Aguardando | Pedidos e webhooks |
| `ACCEPTED` | Aceito | Pedidos e webhooks |
| `PREPARING` | Em preparo | Pedidos e webhooks |
| `READY` | Pronto | Pedidos e webhooks |
| `DISPATCHED` | Despachado | Pedidos e webhooks |
| `DELIVERED` | Entregue | Pedidos e webhooks |
| `CANCELLED` | Cancelado | Pedidos e webhooks |

## Pedidos · deliveryType

| Valor | Significado | Uso |
| --- | --- | --- |
| `DELIVERY` | Entrega | Lista e detalhe de pedidos |
| `TAKEOUT` | Retirada | Lista e detalhe de pedidos |
| `DINE_IN` | Consumo no local | Lista e detalhe de pedidos |

## Pedidos · orderType

Outros literais vindos do PDV podem aparecer sem tradução.

| Valor | Significado | Uso |
| --- | --- | --- |
| `DELIVERY` | Pedido delivery | Detalhe do pedido |
| `PDV` | Pedido lançado no PDV | Detalhe do pedido |
| `TABLE` | Mesa / presencial | Detalhe do pedido |

## Pedidos · salesChannel

| Valor | Significado | Uso |
| --- | --- | --- |
| `IFOOD` | iFood | Detalhe, listagem (filtro), polling e webhooks |
| `99FOOD` | 99Food | Detalhe, listagem (filtro), polling e webhooks |
| `KEETA` | Keeta | Detalhe, listagem (filtro), polling e webhooks |
| `AIQFOME` | Aiqfome | Detalhe, listagem (filtro), polling e webhooks |
| `RAPPI` | Rappi | Detalhe, listagem (filtro), polling e webhooks |
| `DELIVERYMUCH` | Delivery Much | Detalhe, listagem (filtro), polling e webhooks |
| `UAIRANGO` | UaiRango | Detalhe, listagem (filtro), polling e webhooks |
| `TOTEM` | Totem | Detalhe, listagem (filtro), polling e webhooks |
| `EXTERNAL` | Integração externa | Detalhe, listagem (filtro), polling e webhooks |
| `WHATSAPP` | Cardápio digital via WhatsApp | Detalhe, listagem (filtro), polling e webhooks |
| `DIGITAL_MENU` | Cardápio digital | Detalhe, listagem (filtro), polling e webhooks |
| `MANUAL` | Lançamento manual / PDV | Detalhe, listagem (filtro), polling e webhooks |

## Listagens · sort

| Valor | Significado | Uso |
| --- | --- | --- |
| `asc` | Crescente | Todas as listagens |
| `desc` | Decrescente (padrão) | Todas as listagens |