Conceitos

Os termos abaixo aparecem em toda a documentação e nos payloads da API. Cada um tem um significado preciso.

Loja (merchant)

A unidade de negócio que recebe pedidos no MeuPedido. Na API ela é o merchant, identificado por um GUID (merchantId). Toda credencial pertence a uma loja, e todo pedido vem com merchant.id e merchant.name.

Uma rede com várias unidades tem várias lojas. Cada uma precisa da própria credencial; não existe credencial que enxergue mais de uma loja.

merchantId  6d2f4c8a-1b3e-4f5a-9c7d-2e8b0a1f3c5d

Credencial

O par client_id e client_secret que o lojista gera no painel, em Integrações > Open Delivery, para autorizar o seu sistema em uma loja. O client_id começa com mp_ seguido de 24 caracteres hexadecimais; o client_secret é mostrado uma única vez, no momento da criação.

client_id      mp_7f3a9c1e5b2d4a6f8e0c1b3d
client_secret  mostrado uma vez, no painel

A credencial carrega tudo que define o acesso: os escopos, o modo de entrega de eventos, a URL do webhook e se pedidos de marketplace entram no feed. O lojista pode pausar (o acesso para de funcionar, mas os eventos continuam acumulando e voltam quando ele retomar), retomar e revogar (permanente). Com a credencial pausada ou revogada, qualquer chamada responde 401 invalid_token imediatamente.

Cada credencial tem o próprio feed de eventos. Duas credenciais na mesma loja recebem os mesmos eventos, com confirmações independentes.

Escopo

O que a credencial pode fazer. São quatro, definidos na criação e não editáveis depois: para mudar, o lojista cria outra credencial.

Uma chamada sem o escopo necessário responde 403 insufficient_scope.

Token

O JWT (HS256) que o seu sistema obtém em POST /oauth/token com a credencial e envia em Authorization: Bearer em todas as outras chamadas. Vale por 3600 segundos, não tem refresh token e carrega as claims merchant_id, client_id e scope. Renovar é pedir outro token.

Evento

O registro de que algo aconteceu com um pedido: foi criado, confirmado, ficou pronto, saiu para entrega, foi concluído ou cancelado. Cada evento tem um eventId (GUID) único, um eventType, o orderId e a orderURL para buscar o pedido. O evento nunca carrega o pedido inteiro.

{
  "eventId": "c0a8f1e2-3d4b-4c5a-9e6f-7a8b9c0d1e2f",
  "eventType": "CREATED",
  "orderId": "9b1e2d3c-4f5a-4b6c-8d7e-0f1a2b3c4d5e",
  "orderURL": "https://api.meupedido.io/open-delivery/v1/orders/9b1e2d3c-4f5a-4b6c-8d7e-0f1a2b3c4d5e",
  "createdAt": "2026-09-19T14:32:10Z"
}

Eventos ficam no feed da credencial até serem confirmados (POST /v1/events/acknowledgment). O eventId é a chave de deduplicação do seu lado: o mesmo evento pode chegar mais de uma vez. O catálogo completo está em Eventos.

Entrega de eventos

O canal pelo qual os eventos chegam ao seu sistema, escolhido pelo lojista na credencial:

• POLLING: seu sistema consulta GET /v1/events:polling no ritmo que preferir.
• WEBHOOK: o MeuPedido faz POST na sua URL HTTPS, com assinatura HMAC-SHA256.
• BOTH: os dois. O webhook dá latência baixa; o polling garante que nada se perde.

Não confunda com o tipo de entrega do pedido (type: DELIVERY, TAKEOUT ou INDOOR), que descreve como o cliente recebe a comida, nem com o bloco delivery do pedido, que traz o endereço.

Pedido

O objeto central da API. Tem id (GUID), displayId (o número curto que aparece para o lojista e o cliente), type, orderTiming (INSTANT ou SCHEDULED), itens com opções, taxas, descontos, totais, pagamentos, cliente e, conforme o tipo, delivery ou takeout. Campos sem valor vêm como null. A estrutura campo a campo está em Estrutura do pedido.

O status do pedido não é um campo do objeto: ele é comunicado pelos eventos e pelas respostas das ações (situation). A máquina de estados está em Ciclo de vida.

Ação

Uma chamada POST /v1/orders/{orderId}/<ação> que avança o pedido: confirm, startPreparation, readyForPickup, dispatch, pickedUp, delivered e requestCancellation. A resposta é 202 com status (accepted ou already_applied) e a situation resultante. O header opcional Idempotency-Key protege contra reenvios. Detalhes em Ações e idempotência.

Extensão MeuPedido

Qualquer evento, ação ou campo que o MeuPedido oferece além do que o Open Delivery 1.4.0 define. Estão marcados com Extensão MeuPedido na documentação. Exemplos: a ação startPreparation, o evento PREPARING, os eventos COURIER_* e os webhooks com assinatura X-MeuPedido-*. Uma integração estritamente Open Delivery pode ignorá-los.

Loja de teste

Uma loja real, em produção, criada pelo suporte para você desenvolver e homologar. Não existe sandbox. A diferença é que todo pedido dela sai com "test": true, e você mesmo gera os pedidos pelo cardápio digital. Veja Loja de teste.

Próximos passos

• Obter credenciais: como o lojista cria a credencial no painel.
• Autenticação: do client_secret ao token.
• Catálogo de eventos: todos os eventType e quando cada um dispara.