Visão geral
O que é a API Open Delivery do MeuPedido, para quem ela serve e por onde começar.
A API Open Delivery do MeuPedido entrega ao seu sistema, em tempo real, os pedidos que chegam às lojas que usam o MeuPedido, e recebe de volta cada avanço de status até a conclusão. Ela segue o padrão Open Delivery 1.4.0 da Abrasel, módulos Order e Merchant, com o MeuPedido no papel de aplicação de pedidos.
Se você mantém um ERP, PDV, KDS, sistema de gestão de entregas ou qualquer software que precisa saber o que a loja vendeu, é aqui que você conecta.
https://api.meupedido.io/open-deliveryO que a API faz
| Capacidade | Como | Escopo |
|---|---|---|
| Receber pedidos novos e mudanças de status | Polling em GET /v1/events:polling ou webhook na sua URL | orders:read |
| Ler um pedido completo | GET /v1/orders/{orderId} | orders:read |
| Avançar o pedido (confirmar, preparar, despachar, concluir, cancelar) | POST /v1/orders/{orderId}/confirm e as demais ações | orders:write |
| Ler os dados da loja | GET /v1/merchant/{merchantId} | merchant:read |
| Ler o cardápio | GET /v1/merchant/{merchantId}/menus | catalog:read |
Tudo é autenticado com OAuth 2.0 client credentials. Uma credencial dá acesso a exatamente uma loja; para integrar cinco lojas, o lojista de cada uma gera uma credencial e você guarda cinco pares de client_id e client_secret.
Como a integração funciona
- 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
- O lojista concede acesso. No painel do MeuPedido, em Integrações > Open Delivery, ele cria uma credencial para o seu sistema e escolhe os escopos e o modo de entrega.
- Seu sistema pede um token.
POST /oauth/tokencomclient_ideclient_secretdevolve um JWT válido por 3600 segundos. - Seu sistema recebe eventos. Cada pedido criado, confirmado, despachado ou cancelado vira um evento. Você consulta por polling, recebe por webhook, ou os dois.
- Seu sistema responde com ações. Ao confirmar o pedido no seu lado, chame
confirm; ao despachar,dispatch; e assim atédeliveredoupickedUp.
A leitura completa desse fluxo está em Como funciona.
Sem sandbox, com loja de teste
Não existe um ambiente separado de homologação. O suporte cria uma loja de teste em produção para você: ela se comporta como qualquer loja, mas todo pedido sai com "test": true, e você mesmo gera pedidos pelo cardápio digital dela. Veja Loja de teste.
Duas formas de receber eventos
Polling
Seu sistema consulta a API. Entrega at-least-once: o que não for confirmado volta na próxima consulta. Funciona atrás de qualquer firewall.
Webhooks
A API chama a sua URL HTTPS com o mesmo envelope, assinado com HMAC-SHA256. Retentativas automáticas e o polling continua como rede de segurança.
Nos dois casos, o evento só sai do feed quando você chama POST /v1/events/acknowledgment. Receber por webhook não confirma o evento.
Além do padrão
O MeuPedido emite alguns eventos e aceita algumas ações que o Open Delivery 1.4.0 não prevê, como PREPARING, MODIFIED e a família COURIER_* de rastreio do entregador. Eles aparecem nesta documentação com o selo Extensão MeuPedido. Se o seu sistema já fala Open Delivery, pode ignorá-los sem prejuízo. A lista completa do que está e do que ainda não está implementado fica em Compatibilidade.
Por onde começar
Obter credenciais
O lojista gera o client_id e o segredo no painel.
Primeira integração em 10 minutos
Token, polling, busca do pedido, ack e confirm, com playground em cada passo.
Referência de API
Todos os endpoints, campos e erros, com a especificação OpenAPI para download.
Próximos passos
- Como funciona: os três lados da integração e o caminho de um pedido.
- Conceitos: o vocabulário que o resto da documentação usa.
- Obter credenciais: o primeiro passo prático.