---
title: "Resumo agrupado"
description: "GET /v1/orders/summary/grouped — métricas de pedidos quebradas por hora, dia, canal, filial ou forma de pagamento."
method: "GET"
path: "/v1/orders/summary/grouped"
url: "https://developer.beefood.com.br/docs/pedidos/resumo-agrupado"
group: "Relatórios"
scope: "orders:read"
lang: "pt"
---
# Resumo agrupado

`GET /v1/orders/summary/grouped`

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

As métricas do resumo, quebradas por uma dimensão.

## 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

- `groupBy` *string* **obrigatório** — Dimensão do agrupamento. Exemplo: `"orderType"`.
  - *Valores:* `hour`, `day`, `dayOfWeek`, `week`, `month`, `orderType`, `orderStatus`, `deliveryType`, `deliveryStatus`, `salesChannel`, `merchantId`, `driverId`, `paymentMethodId`

- `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* — Tipo do pedido. Formato `in:v1,v2` ou `notIn:v1,v2`; sem operador vale `in`. Exemplo: `"in:DELIVERY"`.
  - *Valores:* `TABLE`, `DELIVERY`, `PDV`

- `orderStatus` *string* — Status do pedido; sem filtro, entram OPEN, RECEIVED e CLOSED. Formato `in:v1,v2` ou `notIn:v1,v2`; sem operador vale `in`. Exemplo: `"notIn:CANCELLED"`.
  - *Valores:* `OPEN`, `RECEIVED`, `CLOSED`, `GROUPED`, `CANCELLED`

- `deliveryType` *string* — Modalidade da entrega. Formato `in:v1,v2` ou `notIn:v1,v2`; sem operador vale `in`. Exemplo: `"in:TAKEOUT"`.
  - *Valores:* `DELIVERY`, `TAKEOUT`, `DINE_IN`

- `deliveryStatus` *string* — Status da entrega. Formato `in:v1,v2` ou `notIn:v1,v2`; sem operador vale `in`. Exemplo: `"notIn:CANCELLED"`.
  - *Valores:* `WAITING`, `ACCEPTED`, `PREPARING`, `READY`, `DISPATCHED`, `DELIVERED`, `CANCELLED`

- `salesChannel` *string* — Canal de venda. Formato `in:v1,v2` ou `notIn:v1,v2`; sem operador vale `in`. Exemplo: `"notIn:IFOOD,99FOOD"`.
  - *Valores:* `IFOOD`, `99FOOD`, `KEETA`, `AIQFOME`, `RAPPI`, `DELIVERYMUCH`, `UAIRANGO`, `TOTEM`, `WHATSAPP`, `DIGITAL_MENU`, `MANUAL`, `EXTERNAL`

- `merchantId` *string* — IDs de filial (inteiros maior ou igual a 1). Formato `in:v1,v2` ou `notIn:v1,v2`; sem operador vale `in`. Exemplo: `"in:10,11"`.

- `customerId` *string* — IDs de cliente (inteiros maior ou igual a 1). Formato `in:v1,v2` ou `notIn:v1,v2`; sem operador vale `in`. Exemplo: `"notIn:77"`.

- `documentNumber` *string* — CPF/CNPJ; só os dígitos contam. Formato `in:v1,v2` ou `notIn:v1,v2`; sem operador vale `in`. Exemplo: `"in:12345678900"`.

- `email` *string* — E-mail do cliente, sem diferenciar maiúsculas. Formato `in:v1,v2` ou `notIn:v1,v2`; sem operador vale `in`. Exemplo: `"in:ana@exemplo.com,bia@exemplo.com"`.

- `phone` *string* — Telefone do cliente; só dígitos, busca por trecho. Formato `in:v1,v2` ou `notIn:v1,v2`; sem operador vale `in`. Exemplo: `"in:11999990000"`.

- `couponCode` *string* — Código do cupom, sem diferenciar maiúsculas. Formato `in:v1,v2` ou `notIn:v1,v2`; sem operador vale `in`. Exemplo: `"notIn:BEMVINDO"`.

- `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/summary/grouped?saleDateFrom=2026-09-01&saleDateTo=2026-09-30&groupBy=orderType" \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```


## Exemplos de resposta

### 200 OK

```json
{
  "groupBy": "orderType",
  "groups": [
    { "key": "DELIVERY", "orderCount": 1, "totalRevenue": 60, "averageOrderValue": 60 },
    { "key": "PDV", "orderCount": 1, "totalRevenue": 40, "averageOrderValue": 40 }
  ]
}
```


## Campos da resposta

- `groupBy` *string* — Dimensão usada.
  - *Valores:* `hour`, `day`, `dayOfWeek`, `week`, `month`, `orderType`, `orderStatus`, `deliveryType`, `deliveryStatus`, `salesChannel`, `merchantId`, `driverId`, `paymentMethodId`

- `groups` *array* — Grupos com pedidos.

- `groups[].key` *string | null* — Identificador do grupo; null sem valor na dimensão.

- `groups[].label` *string* — Nome de exibição em merchantId, driverId e paymentMethodId.

- `groups[].orderCount` *integer* — Pedidos no grupo.

- `groups[].totalRevenue` *number* — Faturamento, 2 casas.

- `groups[].averageOrderValue` *number* — Ticket médio, 2 casas.


## Filtros

Os filtros usam o formato `campo=operador:valor1,valor2` (`in` ou `notIn`). Regras e exemplos em [Resumo de pedidos](/docs/pedidos/resumo#filtros).


## Erros

| Status | Mensagem |
| --- | --- |
| 400 | 'groupBy' is required |
| 400 | 'groupBy' must be one of: hour, day, dayOfWeek, week, month, orderType, orderStatus, deliveryType, deliveryStatus, salesChannel, merchantId, driverId, paymentMethodId |
| 400 | 'saleDateFrom' is required |
| 400 | 'saleDateFrom' must be a date (yyyy-mm-dd) |
| 400 | 'saleDateFrom'..'saleDateTo' must span at most 6 months |
| 400 | 'orderStatus' must be sent once; use orderStatus=in:value1,value2 |
| 400 | 'orderStatus' operator must be one of: in, notIn |
| 400 | 'orderStatus' must be one of: OPEN, RECEIVED, CLOSED, GROUPED, CANCELLED |
| 400 | 'merchantId' 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 |


## 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 |

## Relatórios · groupBy

Dimensões aceitas no filtro groupBy do resumo agrupado de pedidos.

| Valor | Significado | Uso |
| --- | --- | --- |
| `hour` | Hora do pedido | /v1/orders/summary/grouped |
| `day` | Dia do pedido | /v1/orders/summary/grouped |
| `dayOfWeek` | Dia da semana | /v1/orders/summary/grouped |
| `week` | Semana do pedido | /v1/orders/summary/grouped |
| `month` | Mês do pedido | /v1/orders/summary/grouped |
| `orderType` | Tipo do pedido | /v1/orders/summary/grouped |
| `orderStatus` | Status do pedido | /v1/orders/summary/grouped |
| `deliveryType` | Tipo de entrega | /v1/orders/summary/grouped |
| `deliveryStatus` | Status da entrega | /v1/orders/summary/grouped |
| `salesChannel` | Canal de vendas | /v1/orders/summary/grouped |
| `merchantId` | Estabelecimento | /v1/orders/summary/grouped |
| `driverId` | Entregador | /v1/orders/summary/grouped |
| `paymentMethodId` | Forma de pagamento | /v1/orders/summary/grouped |