Como migrar da API de Pedidos presenciais para a API de Orders

A API de Orders unifica o processamento de pagamentos com Código QR no Mercado Pago, oferecendo endpoints padronizados, um modelo de status consolidado e novos recursos nativos que não existiam na API de Pedidos presenciais. Além disso, todas as novas funcionalidades do Mercado Pago serão desenvolvidas sobre a API de Orders.

A migração da API de Pedidos presenciais para a API de Orders envolve a atualização de endpoints e campos da requisição, a consolidação do modelo de notificações e o aproveitamento de novos recursos nativos que não existiam antes: endpoints dedicados de consulta por order_id, cancelamento e reembolso. A migração não implica mudanças no fluxo de negócio: o cliente continua escaneando o QR com o aplicativo do Mercado Pago e confirmando o pagamento.

Veja a seguir como realizar esta migração de forma completa.

Antes de iniciar os passos de migração, consulte a tabela abaixo para ter uma visão geral de todas as mudanças de endpoint. Na API de Pedidos presenciais, cada operação utilizava uma URL com o identificador do usuário e da caixa no path. A API de Orders consolida essas operações em endpoints padronizados e introduz recursos que não existiam antes.

Na API de Pedidos presenciais, existiam dois endpoints válidos para criação e cancelamento: /mpmobile/instore/qr/{user_id}/{external_id}, usando o identificador externo da caixa, e /mpmobile/instore/qr/{pos_id}, usando o identificador interno. Ambos migram para o mesmo endpoint na API de Orders: POST /v1/ordersAPI, onde a caixa é identificada pelo campo config.qr.external_pos_id no body.

Uma das mudanças mais significativas entre a API de Pedidos presenciais e a API de Orders é o modelo de status. Na API de Pedidos presenciais, o estado de uma transação era determinado pelo monitoramento de notificações de dois tópicos independentes: payments e merchant_orders com campos e valores distintos para cada um. A API de Orders unifica esse comportamento em um único campo status na order. Consulte o mapeamento completo abaixo.

Além disso, a API de Orders também introduz o campo status_detail, que permite identificar com maior detalhamento o estado da transação. Os valores possíveis são created, canceled, accredited, refunded e expired.

Quanto às notificações, na API Legacy podiam ser configuradas pelo campo notification_url no body da requisição (modelo IPN) ou por webhooks com os tópicos payments e merchant_orders. Na API de Orders, o campo notification_url não existe e os tópicos payments e merchant_orders não são compatíveis. Configure as notificações em Suas integrações, selecionando o tópico "Order (Mercado Pago)" (orders) antes de subir em produção. Para mais informações, acesse a documentação de notificações.

A API de Orders introduz duas mudanças obrigatórias de headers que afetam todos os endpoints. O Access Token deve ser enviado via header Authorization. O envio via query param não é permitido na API de Orders. Aplique as alterações a seguir antes de testar qualquer outro recurso.

Os endpoints de criação POST /mpmobile/instore/qr/{user_id}/{external_id}API e POST /mpmobile/instore/qr/{pos_id} migram para POST /v1/ordersAPI. Além da mudança de URL, a estrutura da requisição foi significativamente reorganizada: o identificador do usuário e da caixa deixam o path e passam para o body, novos campos obrigatórios foram introduzidos e a API de Orders oferece três modos de QR configuráveis via config.qr.mode. Siga os passos abaixo para adaptar a requisição, a resposta e o tratamento de erros.

curl
Copiar
curl -X POST \
  'https://api.mercadopago.com/v1/orders' \
  -H 'Content-Type: application/json' \
  -H 'X-Idempotency-Key: {{IDEMPOTENCY_KEY}}' \
  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
  -d '{
    "type": "qr",
    "total_amount": "50",
    "external_reference": "ext_ref_1234",
    "config": {
      "qr": {
        "external_pos_id": "STORE001POS001",
        "mode": "static"
      }
    },
    "transactions": {
      "payments": [
        {
          "amount": "50"
        }
      ]
    },
    "items": [
      {
        "title": "Smartphone",
        "unit_price": "50",
        "quantity": 1,
        "unit_measure": "unit"
      }
    ]
  }'

O endpoint de consulta GET /v1/orders/{order_id}API é uma novidade exclusiva da API de Orders. A API de Pedidos presenciais não contava com um endpoint dedicado para consultar o estado de uma transação. Anteriormente, o estado era obtido exclusivamente via notificações de webhook dos tópicos payments e merchant_orders. A API de Orders permite consultar o estado completo da order a qualquer momento, incluindo status, pagamentos, reembolsos e dados do meio de pagamento.

curl
Copiar
curl -X GET \
  'https://api.mercadopago.com/v1/orders/{{ORDER_ID}}' \
  -H 'Authorization: Bearer {{ACCESS_TOKEN}}'

O endpoint de cancelamento muda completamente de estrutura: de DELETE /mpmobile/instore/qr/{user_id}/{external_id}API para POST /v1/orders/{order_id}/cancelAPI. O método HTTP muda de DELETE para POST, o {user_id} e o {external_id} saem do path, e o cancelamento passa a operar sobre o identificador único da order.

Na API de Pedidos presenciais, o cancelamento apagava a order ativa associada à caixa, uma operação sobre a caixa e não sobre a transação individual. Na API de Orders, o cancelamento opera diretamente sobre a order pelo order_id, sem depender da caixa no path. O response passou de vazio, código HTTP 204, para o objeto completo da order com status: "canceled", código HTTP 200.

A API de Orders introduz o endpoint dedicado POST /v1/orders/{order_id}/refundAPI para reembolsos, que não existia na API de Pedidos presenciais. Anteriormente, era necessário receber o webhook do pagamento, obter o payment_id e executar o reembolso pela API de Payments separadamente. Agora, o reembolso é realizado diretamente sobre a order.

curl
Copiar
curl -X POST \
  'https://api.mercadopago.com/v1/orders/{{ORDER_ID}}/refund' \
  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
  -H 'X-Idempotency-Key: {{IDEMPOTENCY_KEY}}'

Após aplicar as alterações, verifique se a integração opera corretamente em todos os fluxos antes de ir a produção.

Acesse a documentação para saber como testar a integração.