Criar um pedido

Este guia percorre o fluxo recomendado para criar um pedido pela API: ler o menu, resolver o cliente (e o endereço, para entrega), precificar a entrega se necessário, criar o pedido, adicionar seus itens e pagamento, e tratar as rejeições mais comuns ao longo do caminho.

O fluxo em resumo

Resolva quais variantes de produto o pedido precisa. Leia o menu completo (GET /v1/menu) ou navegue de forma enxuta: GET /v1/menu/categories, GET /v1/menu/products e GET /v1/menu/products/{id} para as variantes e categorias de modificadores de um produto. Você precisa de um variant_id (e, para qualquer adicional, um modifier_id) para cada item que vai adicionar ao pedido.

Escopo necessário: menu:read

Etapa 2 — encontrar ou criar o cliente (e o endereço)

GET /v1/clients, filtrado por telefone:

GET /v1/clients?filter[phone_number]=987654321&filter[country_calling_code]=51

Se nenhum cliente corresponder, crie um:

POST /v1/clients

{
  "name": "Maria Lopez",
  "phone_number": "987654321",
  "country_calling_code": "51"
}

Escopos necessários: clients:read (busca), clients:write (criação).

Para um pedido DELIVERY, resolva um endereço de entrega da mesma forma — liste os endereços salvos do cliente ou crie um:

POST /v1/addresses

{
  "client_id": "9c8e720f-31b1-485a-85fa-0aaf552faaa9",
  "address": "Av. Larco 345",
  "latitude": -12.1218,
  "longitude": -77.0297
}

Escopos necessários: addresses:read (busca), addresses:write (criação).

Etapa 3 — precificar a entrega (apenas pedidos DELIVERY)

Não estime a taxa de entrega: resolva-a a partir da própria configuração de preços do merchant. Veja Calcular preços de entrega para o fluxo completo (GET /v1/delivery/pricing + GET /v1/delivery/quote) — ele termina com o delivery_price que você envia abaixo.

Etapa 4 — criar o pedido

POST /v1/orders

Escopo necessário: orders:write. Header obrigatório: Idempotency-Key — um valor único por tentativa de pedido; repetir a mesma chave com o mesmo corpo reproduz o resultado original em vez de criar um segundo pedido.

curl -X POST https://public-api.olaclick.app/v1/orders \
  -H "Authorization: Bearer olk_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 018f1c33-5a2b-7e4d-9c1a-3b6f8e2d4a70" \
  -d '{
    "service_type": "DELIVERY",
    "client_id": "9c8e720f-31b1-485a-85fa-0aaf552faaa9",
    "address_id": "6b2f1a04-1c7e-4a2b-9f11-2d8e0b3c4d55",
    "delivery_price": 6.5
  }'

Campo	Aplica-se a	Notas
`service_type`	todos	`DELIVERY`, `ONSITE`, `TABLE` ou `TAKEAWAY`. Obrigatório.
`status`	todos	`INITIATED` (padrão) ou `PENDING`. Veja abaixo.
`client_id`	todos	Um cliente existente da sua empresa.
`table_id`	somente `TABLE`	Rejeitado em qualquer outro `service_type`.
`address_id`, `delivery_price`	somente `DELIVERY`	Rejeitados em qualquer outro `service_type`.
`comment`, `order_title`, `packaging_price`, `scheduled_delivery_date`	todos	Opcionais.

A resposta (201) é o pedido criado. Veja a Referência da API REST para o shape completo da resposta.

Rascunho (`INITIATED`) vs `PENDING`

Por padrão o pedido é criado como INITIATED — um rascunho que o merchant ainda não vê, e rascunhos nunca são retornados por GET /v1/orders: guarde o id da resposta de criação e leia o rascunho com GET /v1/orders/{id}. Adicione seus itens (e quaisquer descontos ou cupom) enquanto ainda é um rascunho, depois confirme-o com PATCH /v1/orders/{id}/status e {"status": "PENDING"} (ou PREPARING para pular a confirmação do próprio merchant). Confirmar atribui o número diário do pedido e o torna visível para o merchant.

Registrar um pagamento também confirma um rascunho: o primeiro pagamento em um pedido INITIATED (mesmo parcial) o move para PENDING e atribui seu número diário, sem o PATCH. Por isso, adicione itens, descontos e cupons primeiro, e o pagamento por último.

Para pular o rascunho por completo, envie "status": "PENDING" na criação — o pedido é confirmado imediatamente.

Etapa 5 — itens, pagamentos, descontos, cupons

Adicione todos os itens em uma única chamada:

POST /v1/orders/{id}/combos

{
  "combos": [
    {
      "variant_id": "3f6a9c2e-1b4d-4e7a-8c9f-2d5e7a1b3c40",
      "quantity": 2,
      "modifiers": [{ "modifier_id": "8e2b4d6f-9a0c-4e1b-85d7-9f2a4c6e8b10", "quantity": 1 }]
    }
  ]
}

Em seguida, registre um pagamento (payment_method_id vem de GET /v1/company/payment-methods):

POST /v1/orders/{id}/payments

{
  "payment_method_id": "4a7c9e1b-3d6f-4b2a-9e8c-1f3a5b7d9c20",
  "bill_amount": 25.5
}

Um desconto manual:

POST /v1/orders/{id}/discounts

{ "type": "PERCENTAGE", "value": 10, "description": "Loyalty 10%" }

Ou um código de cupom (o pedido precisa ter um client vinculado primeiro):

POST /v1/orders/{id}/coupon

{ "code": "WELCOME10" }

Escopo necessário para tudo acima: orders:write. Todos eles funcionam apenas em pedidos que sua empresa criou pela API (combos, discounts); pagamentos também aceitam pedidos feitos no storefront ou no POS — veja a página de referência de cada endpoint para a regra exata.

Erros 4xx comuns

Status	Código	Quando
422	`validation_failed`	Um campo não se aplica ao `service_type` enviado (ex.: `table_id` em um pedido `DELIVERY`), um campo obrigatório está ausente, ou um valor está fora do intervalo permitido (ex.: um `value` de desconto acima de 100 para `PERCENTAGE`).
400	`idempotency_key_required`	`POST /v1/orders` sem o header `Idempotency-Key`, ou com ele vazio.
400	`idempotency_key_invalid`	A chave tem mais de 255 caracteres.
422	`idempotency_conflict`	A mesma `Idempotency-Key` foi reutilizada com um corpo de requisição diferente.
409	`idempotency_in_progress`	Uma requisição com essa chave ainda está sendo processada; tente novamente após o header `Retry-After`.
422	`order_not_modifiable`	Ação em um pedido de um canal que este endpoint não permite editar (ex.: adicionar itens a um pedido feito em um app de delivery).
422	`validation_failed` (campo `status`)	Cancelar (`POST /v1/orders/{id}/cancel` com um `reason`) um pedido que ainda tem pagamentos ativos. Remova os pagamentos primeiro e depois cancele.
422	`coupon_not_applicable`	O cupom existe, mas não é elegível para este pedido (limite de uso atingido, uma vez por cliente, service type errado, restrito a novos clientes).
404	`not_found`	Id de pedido ou código de cupom desconhecido.
403	`insufficient_scope`	A API key não tem um escopo necessário.

Acompanhar o pedido

Depois de confirmado, não faça polling por mudanças de status — registre um webhook e deixe a OlaClick enviá-las para você. Veja Receba atualizações de pedidos com webhooks.

Fazendo isso pelo servidor MCP

Ferramenta	O que faz
`list_products` / `get_product`	Navega o menu em busca de `variant_id`s
`get_client` / `create_client`	Resolve o cliente
`list_addresses` / `create_address`	Resolve o endereço de entrega
`get_delivery_pricing` / `get_delivery_quote`	Precifica a entrega
`create_order`	Cria o pedido (um `idempotency_key` é gerado para você se omitido)
`add_order_combos`	Adiciona itens
`update_order_status`	Confirma ou avança o pedido
`add_order_payment` / `add_order_discount` / `apply_order_coupon`	Pagamentos, descontos, cupons

Escopos necessários: menu:read, clients:read/clients:write, addresses:read/addresses:write, orders:read/orders:write.

Exemplos de prompts:

"Crie um pedido de entrega para o cliente 9c8e720f-31b1-485a-85fa-0aaf552faaa9 com 2 unidades da variante 3f6a9c2e-1b4d-4e7a-8c9f-2d5e7a1b3c40, depois confirme-o"

"Adicione um desconto de fidelidade de 10% ao pedido 7a1e9c3a-4b2d-4f7e-9a1b-3c6d8e2f5a90"

Veja a página do Servidor MCP para todos os parâmetros de cada ferramenta.

O fluxo em resumo​

Etapa 1 — ler o menu​

Etapa 2 — encontrar ou criar o cliente (e o endereço)​

Etapa 3 — precificar a entrega (apenas pedidos DELIVERY)​

Etapa 4 — criar o pedido​

Rascunho (INITIATED) vs PENDING​

Etapa 5 — itens, pagamentos, descontos, cupons​

Erros 4xx comuns​

Acompanhar o pedido​

Fazendo isso pelo servidor MCP​