---
title: "Criar pedido"
description: "POST /v1/orders — cria um pedido aberto no restaurante pela API BeeFood."
method: "POST"
path: "/v1/orders"
url: "https://developer.beefood.com.br/docs/pedidos/criar"
group: "Pedidos"
scope: "orders:write"
lang: "pt"
---
# Criar pedido

`POST /v1/orders`

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

Cria um pedido aberto no restaurante, sempre com canal de venda EXTERNAL.

## Autenticação

Envie o access token no header `Authorization: Bearer <accessToken>`. Escopo necessário: `orders:write`. Limite: 300 requisições a cada 3 minutos.




## Parâmetros do body

- `merchantId` *integer* **obrigatório** — Filial do restaurante. Aceita só merchant com cardápio publicado. Exemplo: `1`.

- `orderType` *string* **obrigatório** — Tipo do pedido. Exemplo: `"DELIVERY"`.
  - *Valores:* `DELIVERY`, `PDV`, `TABLE`

- `external` *object* — Identificadores externos do pedido.

- `external.externalOrderId` *string* — ID do pedido no seu sistema, até 36 caracteres. Exemplo: `"PARCEIRO-123"`.

- `usuarioId` *integer* — Usuário PDV do restaurante. Se ausente, usa o usuário vinculado ao dono da credencial. Exemplo: `12`.

- `employeeId` *integer* — Funcionário que lançou o pedido. Exemplo: `5`.

- `orderObservations` *string* — Observações do pedido. Exemplo: `"Sem cebola"`.

- `customer` *object* — Cliente do pedido. Obrigatório em DELIVERY e com Fiado; encontrado pelo telefone ou criado.

- `customer.customerName` *string* **obrigatório** — Nome do pedido e do cliente criado. Exemplo: `"Ana Souza"`.

- `customer.email` *string* — E-mail, até 250 caracteres. Gravado só se o cadastro estiver vazio. Exemplo: `"joao@exemplo.com"`.

- `customer.birthDate` *string (YYYY-MM-DD)* — Nascimento, não futuro. Gravado só se o cadastro estiver vazio. Exemplo: `"1990-12-31"`.

- `customer.phone` *object* **obrigatório** — Telefone que identifica o cliente do restaurante.

- `customer.phone.number` *string* **obrigatório** — Só dígitos, com DDD. Exemplo: `"11988887777"`.

- `customer.phone.extension` *string* **obrigatório** — DDI. Exemplo: `"+55"`.

- `customer.address` *object* — Endereço de entrega. Obrigatório em DELIVERY; proibido em TAKEOUT e DINE_IN. Encontrado por CEP, rua e número ou criado.

- `customer.address.street` *string* **obrigatório** — Logradouro. Exemplo: `"Av. Paulista"`.

- `customer.address.number` *string* **obrigatório** — Número. Exemplo: `"1000"`.

- `customer.address.neighborhood` *string* — Bairro, até 100 caracteres. Informe o bairro ou o CEP. Exemplo: `"Bela Vista"`.

- `customer.address.city` *string* **obrigatório** — Cidade, até 30 caracteres. Exemplo: `"São Paulo"`.

- `customer.address.state` *string* **obrigatório** — Sigla ou nome do estado, até 20 caracteres. Exemplo: `"SP"`.

- `customer.address.postalCode` *string* — CEP, só dígitos. Informe o CEP ou o bairro. Exemplo: `"01310100"`.

- `customer.address.complement` *string* — Complemento. Exemplo: `"Apto 12"`.

- `customer.address.latitude` *string | number* — Latitude. Exemplo: `"-23.5614"`.

- `customer.address.longitude` *string | number* — Longitude. Exemplo: `"-46.6559"`.

- `delivery` *object* — Obrigatório em DELIVERY; proibido em PDV e TABLE.

- `delivery.deliveryType` *string* **obrigatório** — Modalidade da entrega. Exemplo: `"DELIVERY"`.
  - *Valores:* `DELIVERY`, `TAKEOUT`, `DINE_IN`

- `delivery.deliveryStatus` *string* — Status inicial do pedido. Padrão WAITING. Com WAITING, o pedido aguarda o aceite do restaurante e gera o alerta de novo pedido no PDV; qualquer outro status cria o pedido já aceito, sem alerta. Exemplo: `"WAITING"`.
  - *Valores:* `WAITING`, `ACCEPTED`, `PREPARING`, `READY`, `DISPATCHED`, `DELIVERED`

- `delivery.scheduledDateTime` *string (ISO 8601)* — Data e hora do pedido agendado. Exemplo: `"2026-10-04T19:30:00-03:00"`.

- `delivery.driverId` *integer* — Entregador (funcionário). Exemplo: `7`.

- `delivery.paymentIntent` *object* — Intenção de pagamento: o combinado com o cliente, guardado só como aviso, sem lançar pagamento. Forma e troco são opcionais; se vier com payments, o pagamento substitui a intenção.

- `delivery.paymentIntent.paymentMethod` *string* — Forma de pagamento em texto livre, até 50 caracteres. Exemplo: `"Cartão de crédito"`.

- `delivery.paymentIntent.brand` *string* — Bandeira em texto livre, até 50 caracteres. Exemplo: `"Visa"`.

- `delivery.paymentIntent.changeFor` *number* — Troco para, maior ou igual a 0. Exemplo: `100`.

- `delivery.additionalDeliveryTime` *number* — Minutos adicionais, maior ou igual a 0. Exemplo: `10`.

- `indoor` *object* — Dados de mesa/balcão (TABLE e PDV).

- `indoor.tableId` *integer* — Mesa. Exemplo: `3`.

- `indoor.commandId` *integer* — Comanda. Exemplo: `21`.

- `indoor.waiterId` *integer* — Garçom (funcionário). Exemplo: `4`.

- `items` *array* **obrigatório** — Itens do pedido (ao menos 1).

- `items[].productId` *integer | null* **obrigatório** — ID do produto no catálogo do restaurante. null para item avulso (produto fora do catálogo); veja "Item avulso". Exemplo: `1`.

- `items[].itemName` *string* — Nome do item. No item avulso, é o nome que aparece como "não vinculado" no PDV. Exemplo: `"X-Burguer"`.

- `items[].quantity` *number* **obrigatório** — Quantidade, maior que 0. Exemplo: `1`.

- `items[].unitPrice` *number* **obrigatório** — Preço unitário, maior ou igual a 0. Exemplo: `25`.

- `items[].itemObservations` *string* — Observações do item. Exemplo: `"Bem passado"`.

- `items[].noServiceFee` *boolean* — Item sem taxa de serviço. Exemplo: `false`.

- `items[].options` *array* — Opções do item.

- `items[].options[].optionId` *integer* **obrigatório** — Opção de GET /v1/catalog/options; grupo e produto vêm do cadastro dela. Exemplo: `1`.

- `items[].options[].optionName` *string* — Nome da opção. Exemplo: `"Bacon"`.

- `items[].options[].quantity` *number* **obrigatório** — Quantidade, maior que 0. Exemplo: `1`.

- `items[].options[].unitPrice` *number* **obrigatório** — Preço unitário, maior ou igual a 0. Exemplo: `4`.

- `total` *object* **obrigatório** — Totais do pedido.

- `total.itemsPrice` *number* **obrigatório** — Soma dos itens, maior ou igual a 0. Exemplo: `39`.

- `total.orderAmount` *number* **obrigatório** — Valor total, maior ou igual a 0. Exemplo: `45`.

- `total.deliveryFee` *number* — Taxa de entrega, maior ou igual a 0. Exemplo: `6`.

- `total.additionalFees` *number* — Taxas adicionais, maior ou igual a 0. Exemplo: `0`.

- `total.discount` *number* — Desconto, maior ou igual a 0. Exemplo: `0`.

- `total.waiterServiceFee` *number* — Taxa de serviço, maior ou igual a 0. Exemplo: `0`.

- `payments` *array* — Pagamentos já recebidos; entram como pagos. Sem caixa aberto, entram no próximo caixa aberto. Fiado não usa caixa, exige customer (nome e telefone) e lança a dívida na conta do cliente.

- `payments[].paymentMethodId` *integer* **obrigatório** — Forma de pagamento de GET /v1/store/payment-methods. PIX Beetech e Fiado ainda não aceitos. Exemplo: `3`.

- `payments[].value` *number* **obrigatório** — Valor pago, maior que 0. Em dinheiro, o excedente vira troco. Exemplo: `45`.

- `payments[].brandId` *integer* — Bandeira, da lista brands da forma de pagamento. Exemplo: `2`.



## Exemplos de requisição

### cURL

```bash
curl -X POST "https://api.beefood.app/v1/orders" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "merchantId": 1,
  "external": {
    "externalOrderId": "PARCEIRO-123"
  },
  "orderType": "DELIVERY",
  "orderObservations": "Sem cebola",
  "customer": {
    "customerName": "Ana Souza",
    "phone": {
      "number": "11988887777",
      "extension": "+55"
    },
    "address": {
      "street": "Av. Paulista",
      "number": "1000",
      "neighborhood": "Bela Vista",
      "city": "São Paulo",
      "state": "SP",
      "postalCode": "01310100"
    }
  },
  "delivery": {
    "deliveryType": "DELIVERY",
    "deliveryStatus": "WAITING",
    "paymentIntent": {
      "paymentMethod": "Cartão de crédito",
      "brand": "Visa",
      "changeFor": 100
    }
  },
  "items": [
    {
      "productId": 1,
      "itemName": "X-Burguer",
      "quantity": 1,
      "unitPrice": 25,
      "itemObservations": "Bem passado",
      "options": [
        {
          "optionId": 1,
          "optionName": "Bacon",
          "quantity": 1,
          "unitPrice": 4
        }
      ]
    },
    {
      "productId": null,
      "itemName": "Item avulso",
      "quantity": 2,
      "unitPrice": 5
    }
  ],
  "total": {
    "itemsPrice": 39,
    "deliveryFee": 6,
    "discount": 0,
    "orderAmount": 45
  }
}'
```


## Exemplos de resposta

### 201 OK

```json
{
  "orderId": 1234
}
```


## Campos da resposta

- `orderId` *integer* — ID do pedido criado. Detalhe em GET /v1/orders/{orderId}. Exemplo: `1234`.


## Alerta de aceite

Pedidos DELIVERY com `delivery.deliveryStatus` `WAITING` chegam como pedido novo aguardando aceite. O PDV toca o alerta de novo pedido, o restaurante aceita ou cancela. A impressão na cozinha é feita apenas quando o pedido é aceito.

### Regras

- Pedidos DELIVERY criados em outro status (`ACCEPTED`, `PREPARING`, `READY`, `DISPATCHED` ou `DELIVERED`) já são aceitos: não geram alerta e vão direto para a impressão da cozinha.
- Pedidos PDV e TABLE nunca geram alerta de aceite.
- A resposta 201 não confirma que o alerta tocou: o pedido é criado mesmo se o aviso ao restaurante falhar.

## Item avulso

Use `productId: null` quando o produto não existe no catálogo. Com `itemName`, o PDV mostra o nome como "não vinculado" até o restaurante associá-lo a um produto.

### Regras

- A pendência é uma por restaurante e nome; pedidos seguintes com o mesmo `itemName` não duplicam. Sem `itemName`, não há pendência.
- O item não emite nota fiscal, não baixa estoque e não entra nas rotinas de produto do PDV.
- Nos relatórios, o item vem com `productId: null`.
- Associar a pendência no PDV não corrige pedidos já criados.


## Erros

| Status | Mensagem |
| --- | --- |
| 400 | 'merchantId' is required |
| 400 | 'orderType' must be one of DELIVERY, PDV, TABLE |
| 400 | 'items' must be a non-empty array |
| 400 | 'items[0].quantity' must be a number > 0 |
| 400 | 'total.orderAmount' must be a number >= 0 |
| 400 | 'delivery.scheduledDateTime' must be an ISO 8601 date-time |
| 400 | 'customer.phone.number' must contain only digits |
| 400 | 'customer.address.postalCode' must be a postal code like 01310-100 |
| 400 | 'customer.address.city' must have at most 30 characters |
| 400 | 'customer.address.neighborhood' must have at most 100 characters |
| 400 | 'customer.address.neighborhood' or 'customer.address.postalCode' is required |
| 400 | 'customer.email' must be a valid email |
| 400 | 'customer.birthDate' must be a date like 1990-12-31 |
| 400 | 'customer.birthDate' must not be in the future |
| 400 | Store ID 107 does not have user ID 99 |
| 400 | 'delivery.paymentIntent.changeFor' must be a number >= 0 |
| 400 | 'delivery.paymentIntent.paymentMethod' must have at most 50 characters |
| 401 | Authentication token is missing |
| 401 | Invalid or expired access token |
| 403 | This credential does not include the orders:write scope |
| 422 | 'delivery' is required when 'orderType' is DELIVERY |
| 422 | 'delivery.paymentIntent.paymentMethod' is required when 'delivery.paymentIntent.brand' is sent |
| 422 | 'customer.customerName' and 'customer.phone' are required |
| 422 | 'customer.address' is required when 'deliveryType' is DELIVERY |
| 422 | 'customer.address' is not allowed when 'deliveryType' is TAKEOUT |
| 422 | Merchant ID 99 not found (filial inexistente, inativa ou sem cardápio publicado) |
| 422 | Product IDs 10, 11 not found |
| 422 | Payment method ID 9 not found |
| 422 | Payment method ID 9 is not supported |
| 422 | Brand ID 4 does not belong to payment method ID 3 |
| 422 | 'customer.customerName' and 'customer.phone' are required for Fiado payments |
| 429 | Too Many Requests |
| 500 | Database error when trying to … |


## Vocabulários usados neste endpoint

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

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