Referência de API
URL base, autenticação, erros, limites e downloads da especificação OpenAPI e da coleção Postman.
Contrato da API Open Delivery do MeuPedido, versão 1.4.0 do padrão (Abrasel), módulos Order e Merchant. Esta página resume o que vale para todas as operações; cada operação tem a própria página com parâmetros, esquemas e exemplos, gerada a partir da especificação OpenAPI.
URL base
https://api.meupedido.io/open-deliveryToda rota desta referência é relativa a essa URL. Há um único ambiente, o de produção. Para testar sem afetar uma loja real, use uma loja de teste: os pedidos dela chegam com test: true.
Só HTTPS. Chamadas de navegador são aceitas apenas a partir de https://developer.meupedido.io (playground do portal); integrações rodam servidor a servidor.
Autenticação
OAuth 2.0 client_credentials. Troque client_id e client_secret por um token em POST /oauth/token e envie o token em toda chamada:
Authorization: Bearer <access_token>| Item | Valor |
|---|---|
| Formato do token | JWT HS256, com claims merchant_id, client_id e scope |
| Validade | 3600 segundos, sem refresh token |
Formato do client_id | mp_ seguido de 24 caracteres hexadecimais, ex.: mp_4f8a1c9e2b7d3a6f0e5c8b1d |
| Loja | Uma credencial pertence a uma única loja; o merchantId das rotas precisa ser o dela |
| Sem token | 401 com corpo vazio e header WWW-Authenticate |
| Credencial pausada ou revogada | 401 com { "error": "invalid_token" } em qualquer chamada, imediatamente |
Detalhes, incluindo as três formas de enviar as credenciais, em Autenticação.
Escopos
Definidos na criação da credencial. Não são editáveis: para mudar, o lojista cria outra credencial.
| Escopo | Libera |
|---|---|
orders:read | GET /v1/orders/{orderId}, GET /v1/events:polling, POST /v1/events/acknowledgment |
orders:write | Todas as ações em POST /v1/orders/{orderId}/... |
merchant:read | GET /v1/merchant/{merchantId} |
catalog:read | GET /v1/merchant/{merchantId}/menus |
Chamada sem o escopo necessário: 403 com { "error": "insufficient_scope", "message": "..." }.
Formatos de erro
O endpoint de token segue o formato do RFC 6749 (error e error_description); as demais rotas usam error e message.
| Status | Formato | error | Quando |
|---|---|---|---|
400 | { error, error_description } | invalid_request | Corpo do token incompleto ou malformado |
400 | { error, error_description } | unsupported_grant_type | grant_type diferente de client_credentials |
400 | { error, message } | invalid_idempotency_key | Idempotency-Key acima de 128 caracteres; nada é executado |
400 | { error, message } | invalid_cancellation_reason | reason do cancelamento acima de 500 caracteres; o pedido continua como estava |
400 | ValidationProblemDetails | (campo errors) | Corpo inválido em rota de negócio |
401 | { error } | invalid_client | Credencial inexistente, segredo errado, pausada ou revogada, no endpoint de token |
401 | { error, message } | invalid_token | Credencial pausada ou revogada, nas demais rotas |
401 | corpo vazio | (header WWW-Authenticate) | Sem token, token expirado ou inválido |
403 | { error, message } | insufficient_scope | Token sem o escopo exigido |
404 | { error, message } | order_not_found | orderId desconhecido ou de outra loja |
404 | ProblemDetails | (campos type, title, status, traceId) | Rota inexistente, merchantId de outra loja ou orderId que não é GUID |
409 | { error, message } | idempotency_key_reuse | Mesma Idempotency-Key com requisição diferente |
413 | { error, error_description } | invalid_request | Corpo do endpoint de token acima de 4 KB |
415 | { error, error_description } | invalid_request | Content-Type não suportado no endpoint de token |
422 | { error, message } | invalid_transition | Ação incompatível com o estado do pedido |
429 | { error, message } | rate_limit_exceeded | Limite de requisições excedido (por credencial ou por IP); header Retry-After |
429 | { error, error_description } | rate_limit_exceeded | Dez falhas de autenticação na mesma credencial em um minuto, no endpoint de token; header Retry-After: 60 |
500 | { error, message, traceId } | internal_error | Falha interna; informe o traceId ao suporte |
Exemplos de cada formato e o que fazer em cada caso em Boas práticas.
Limites
| Limite | Valor |
|---|---|
| Chamadas autenticadas, por credencial | 600 por minuto |
POST /oauth/token, por IP | 60 por minuto |
Corpo de POST /oauth/token | 4 KB |
Falhas de autenticação em POST /oauth/token, por credencial | 10 por minuto (o segredo correto continua sendo aceito) |
limit em GET /v1/events:polling | Padrão 100, máximo 200 |
Replay por Idempotency-Key | 24 horas |
| Timeout de entrega de webhook | 10 segundos |
| Retenção de eventos confirmados | 30 dias |
Ao exceder um limite de requisições: 429 com Retry-After: 60.
Datas e valores
- Datas em ISO 8601, UTC, com sufixo
Z:2026-09-19T18:42:07Z. - Valores monetários como
{ "value": 49.9, "currency": "BRL" }. - Ids de pedido e de evento são GUIDs.
- Campos sem valor vêm como
null, nunca são omitidos.
Downloads
| Arquivo | Para quê |
|---|---|
| Especificação OpenAPI (YAML) | Gerar clientes, validar requisições, alimentar agentes de IA |
| Especificação OpenAPI (JSON) | O mesmo contrato, para ferramentas que preferem JSON |
| Coleção Postman | Executar todas as operações com variáveis para credenciais e ids |
| llms.txt | Índice de toda a documentação, para agentes de IA |
| llms-full.txt | A documentação inteira em um único Markdown |
Cada página de documentação também existe em Markdown: acrescente .md à URL, como em /pt-BR/docs/getting-started/authentication.md. Veja Para agentes de IA.
Operações
Autenticação
| Operação | Rota | Escopo |
|---|---|---|
| Obter token | POST /oauth/token | nenhum |
Loja e cardápio
| Operação | Rota | Escopo |
|---|---|---|
| Buscar loja | GET /v1/merchant/{merchantId} | merchant:read |
| Buscar cardápio | GET /v1/merchant/{merchantId}/menus | catalog:read |
Pedidos
| Operação | Rota | Escopo |
|---|---|---|
| Buscar pedido | GET /v1/orders/{orderId} | orders:read |
| Confirmar | POST /v1/orders/{orderId}/confirm | orders:write |
| Iniciar preparo Extensão MeuPedido | POST /v1/orders/{orderId}/startPreparation | orders:write |
| Pronto para retirada | POST /v1/orders/{orderId}/readyForPickup | orders:write |
| Despachar | POST /v1/orders/{orderId}/dispatch | orders:write |
| Retirado Extensão MeuPedido | POST /v1/orders/{orderId}/pickedUp | orders:write |
| Entregue | POST /v1/orders/{orderId}/delivered | orders:write |
| Cancelar | POST /v1/orders/{orderId}/requestCancellation | orders:write |
Eventos
| Operação | Rota | Escopo |
|---|---|---|
| Consultar eventos | GET /v1/events:polling | orders:read |
| Confirmar eventos | POST /v1/events/acknowledgment | orders:read |
Webhooks
| Operação | Rota | Escopo |
|---|---|---|
| Evento de pedido Extensão MeuPedido | POST na URL configurada pelo lojista | (assinatura X-MeuPedido-Signature) |
Próximos passos
- Primeira integração em 10 minutos: token, polling, ack e confirmação na prática.
- Autenticação: as formas de enviar as credenciais e os erros do endpoint de token.
- Changelog: mudanças na API e neste portal.