Como migrar da API QR Modelo Dinâmico para a API de Orders

A API de Orders unifica o processamento de pagamentos com Código QR no Mercado Pago, consolidando em um único endpoint os dois métodos de criação da API QR Modelo Dinâmico e estendendo os recursos de consulta e cancelamento para ambos os modos. Além disso, todas as novas funcionalidades do Mercado Pago serão desenvolvidas sobre a API de Orders.

A API QR Modelo Dinâmico possuía dois métodos de criação com comportamentos distintos:

• POST /qrs, modo QR dinâmico: cria um pedido e retorna uma trama QR única por transação no campo qr_data, sem associá-la a nenhuma caixa. A aplicação é responsável por converter qr_data em código QR e exibi-lo ao cliente.
• PUT /qrs, modo QR híbrido: cria um pedido, o associa à caixa indicada com o {external_pos_id}, atualizando o QR estático vinculado, e retorna também o QR dinâmico no campo qr_data.

A API de Orders unifica esses dois métodos em um único endpoint POST /v1/ordersAPI, diferenciando o comportamento pelo parâmetro config.qr.mode: o valor dynamic corresponde ao fluxo POST legacy e o valor hybrid corresponde ao fluxo PUT legacy.

Essa distinção impactava também os recursos de consulta e cancelamento, disponíveis na API QR Modelo Dinâmico apenas para o fluxo PUT. Na API de Orders, esses recursos passam a estar disponíveis para os dois fluxos via order_id.

Para realizar a migração da sua integração da API QR Modelo Dinâmico para a API de Orders, siga as instruções a seguir.

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. A API de Orders unifica os dois métodos de criação em um único POST /v1/ordersAPI e estende os recursos de consulta e cancelamento para ambos os modos.

Uma das mudanças mais significativas entre a API QR Modelo Dinâmico e a API de Orders é o modelo de status. Na API QR Modelo Dinâmico, 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. Aplique a alteração a seguir antes de testar qualquer outro recurso.

A API de Orders unifica os dois métodos de criação em um único POST /v1/ordersAPI, diferenciando o comportamento pelo parâmetro config.qr.mode. O endpoint POST /qrs, modo QR dinâmico, equivale a config.qr.mode: dynamic, e o endpoint PUT /qrs, modo QR híbrido, equivale a config.qr.mode: hybrid. Em ambos os casos, o {user_id} deixa de ser parâmetro de path, o {external_pos_id} passa para o body, e o campo type: "qr" passa a ser obrigatório. Siga os passos abaixo para adaptar a requisição, a resposta e o tratamento de erros de cada modo.

O endpoint de consulta GET /v1/orders/{order_id}API está disponível para os modos dinâmico e híbrido na API de Orders. Na API QR Modelo Dinâmico, a consulta existia apenas para o fluxo PUT e consultava por caixa, não por order. O fluxo POST não tinha endpoint de consulta. O estado era obtido exclusivamente via notificações de payments e merchant_orders.

A API de Orders permite consultar o estado completo da order diretamente pelo order_id, 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 POST /v1/orders/{order_id}/cancelAPI está disponível para ambos os modos na API de Orders. Na API QR Modelo Dinâmico, o cancelamento existia apenas para o fluxo PUT e cancelava a order associada à caixa via DELETE. O fluxo POST não tinha endpoint de cancelamento.

O método HTTP muda de DELETE para POST, o {user_id} e o {external_pos_id} saem do path, e a operação passa a identificar a order pelo order_id. 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 QR Modelo Dinâmico em nenhum dos dois fluxos. 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, para ambos os modos.

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.