Como migrar da API de Pedidos presenciais V2 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 V2. 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 V2 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, como os endpoints dedicados de cancelamento e reembolso. A principal mudança na criação é que a API de Orders retorna 201 Created com o objeto completo da order, em vez de 204 No Content sem body. 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 V2, cada operação utilizava uma URL com o identificador do usuário, da loja e da caixa no path. A API de Orders consolida essas operações em endpoints padronizados identificados pelo order_id.

Uma das mudanças mais significativas entre a API de Pedidos presenciais V2 e a API de Orders é o modelo de status. Na API de Pedidos presenciais V2, 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 uma mudança obrigatória de header que afeta 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 a alteração a seguir antes de testar qualquer outro recurso.

O endpoint de criação muda de PUT /instore/qr/seller/collectors/{user_id}/stores/{external_store_id}/pos/{external_pos_id}/ordersAPI para POST /v1/ordersAPI. Além da mudança de método de PUT para POST e da URL, a resposta passa de HTTP 204 No Content sem body para 201 Created com o objeto completo da order. O {user_id} e os parâmetros de path de loja e caixa são removidos. A identidade vem do Access Token e a caixa é identificada pelo campo config.qr.external_pos_id no body. Siga os passos abaixo para adaptar a requisição, a resposta e o tratamento de erros.

O endpoint de consulta muda de GET /instore/qr/seller/collectors/{user_id}/pos/{external_pos_id}/ordersAPI para GET /v1/orders/{order_id}API. Na API de Pedidos presenciais V2, a consulta era realizada por caixa (external_pos_id), retornando a order ativa naquela caixa sem expor o estado da transação. A API de Orders substitui o endpoint de consulta por caixa por um endpoint que opera diretamente pelo order_id e retorna o estado completo da transação: status, pagamentos, reembolsos e dados do meio de pagamento. Na API de Pedidos presenciais V2, essas informações chegavam apenas por notificação.

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

O endpoint de cancelamento muda de DELETE /instore/qr/seller/collectors/{user_id}/pos/{external_pos_id}/ordersAPI 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 order_id. O response passou de vazio, código HTTP 204, para o objeto completo da order com status: "canceled", código HTTP 200.

Na API de Pedidos presenciais V2, 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.

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 V2. 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.