Como funciona
Os três lados da integração: lojista, MeuPedido e o seu sistema, com entrega por polling ou webhook.
Uma integração Open Delivery tem três participantes. Entender o papel de cada um evita a maioria das dúvidas que chegam ao suporte.
- 01
Lojista
Credencial na loja
No painel, em Integrações > Open Delivery, o lojista concede acesso ao seu sistema: nome, escopos e modo de entrega. O client_id e o segredo aparecem uma única vez.
client_id mp_… - 02
Seu sistema
Token
Troque client_id e client_secret por um JWT. Ele vale 3600 s e serve para toda a API; quando receber 401, peça outro no mesmo endpoint.
POST /oauth/token - 03
MeuPedido
Receber eventos
Cada mudança do pedido vira um evento com o link do pedido completo. Consulte por polling ou receba por webhook; o envelope é o mesmo.
GET /v1/events:polling - 04
Seu sistema
Confirmar o pedido
Confirme os eventos recebidos (acknowledgment) e avance o pedido conforme a operação: confirm, readyForPickup, dispatch, delivered.
POST /v1/orders/{id}/confirm
Os três lados
O lojista usa o MeuPedido para receber pedidos do cardápio digital, do balcão, de marketplaces e do WhatsApp. É ele quem decide se o seu sistema pode ver os pedidos da loja: no painel, em Integrações > Open Delivery, ele cria uma credencial, escolhe o que ela pode fazer e pode pausar ou revogar o acesso a qualquer momento.
O MeuPedido é a aplicação de pedidos, no vocabulário do Open Delivery. Ele guarda o pedido, controla o status, gera um evento a cada mudança relevante e expõe tudo isso pela API em https://api.meupedido.io/open-delivery.
O seu sistema consome a API. Ele se autentica com a credencial da loja, recebe os eventos, busca os pedidos que precisar e devolve ações (confirm, dispatch, delivered...) conforme a operação avança do seu lado.
O caminho de um pedido
Considere um pedido de entrega feito pelo cardápio digital da loja.
O pedido nasce no MeuPedido
O cliente fecha o carrinho. O MeuPedido cria o pedido com status PENDING (ou PENDING_PAYMENT, se o pagamento for Pix online e ainda não tiver sido confirmado) e emite o evento CREATED. Pedidos aguardando pagamento só geram CREATED quando o Pix é confirmado.
Seu sistema recebe o evento
Por polling, o evento aparece na próxima chamada a GET /v1/events:polling. Por webhook, o MeuPedido faz um POST na sua URL em segundos. Nos dois casos o corpo é o mesmo envelope, com eventId, eventType, orderId e orderURL. O envelope nunca traz o pedido.
Seu sistema busca o pedido
GET /v1/orders/{orderId} devolve o pedido completo: itens, opções, valores, pagamento, cliente e endereço de entrega. É esse payload que você grava no seu banco.
Seu sistema confirma o evento
POST /v1/events/acknowledgment com o eventId retira o evento do feed. Sem isso, ele volta a cada consulta, para sempre. Esse passo é obrigatório também para eventos recebidos por webhook.
Seu sistema avança o pedido
Quando o operador aceita o pedido no seu PDV, chame POST /v1/orders/{orderId}/confirm. O MeuPedido muda o status para ACCEPTED, mostra isso ao lojista e ao cliente, e emite CONFIRMED. O mesmo vale para startPreparation, readyForPickup, dispatch e delivered.
O ciclo fecha
Em DONE o pedido está concluído e o evento CONCLUDED é emitido. Se em algum momento o pedido for cancelado, pela loja, pelo cliente ou pela sua API, o evento é CANCELLED e o estado é final.
O detalhe de cada transição, incluindo o que é permitido voltar, está em Ciclo de vida.
Polling ou webhook
O modo de entrega é definido pelo lojista na credencial: POLLING, WEBHOOK ou BOTH. O envelope do evento é idêntico nos dois canais, então o código que interpreta o evento é um só.
| Polling | Webhook | |
|---|---|---|
| Quem inicia | Seu sistema consulta GET /v1/events:polling | O MeuPedido faz POST na sua URL HTTPS |
| Latência | O intervalo que você escolher | Segundos |
| Exige URL pública | Não | Sim, com TLS válido |
| Garantia | At-least-once: o que não foi confirmado volta na próxima consulta | Quatro tentativas em cerca de 35 s; depois o evento fica no polling |
| Autenticidade | Bearer token | Assinatura HMAC-SHA256 nos headers X-MeuPedido-* |
| Confirmação | POST /v1/events/acknowledgment | POST /v1/events/acknowledgment, igual |
Recomendação prática: comece por polling, que funciona de qualquer rede e não tem infraestrutura para manter. Ative webhook (modo BOTH) quando precisar de latência menor, mantendo o polling como rede de segurança para o que o webhook não conseguir entregar.
Webhook entregue não é evento confirmado
Um 2xx na sua URL diz ao MeuPedido que a entrega funcionou, mas o evento continua no feed até você chamar POST /v1/events/acknowledgment. Integrações que esquecem esse passo acumulam eventos que voltam a cada polling.
O que fica de cada lado
- No MeuPedido: o pedido, o status atual, o histórico de eventos por credencial e as tentativas de webhook. Eventos confirmados são apagados após 30 dias; eventos não confirmados nunca são apagados.
- No seu sistema: a cópia do pedido, o
eventIdde cada evento já processado (para deduplicar) e o token vigente, renovado antes de expirar.
Próximos passos
- Conceitos: loja, credencial, escopo, evento e os outros termos desta documentação.
- Obter credenciais: o que o lojista faz no painel.
- Polling: o canal recomendado para a primeira versão.