Como migrar da Dynamic QR Model API para a Orders API

A Dynamic QR Model API 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 Orders API 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 Dynamic QR Model API apenas para o fluxo PUT. Na Orders API, esses recursos passam a estar disponíveis para os dois fluxos via order_id.

Para realizar a migração da sua integração da Dynamic QR Model API para a Orders API, siga as instruções a seguir.

Mapear as mudanças de endpoint

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 Orders API 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.

Atualizar o modelo de status e notificações

Uma das mudanças mais significativas entre a Dynamic QR Model API e a Orders API é o modelo de status. Na Dynamic QR Model API, 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 Orders API unifica esse comportamento em um único campo status na order. Consulte o mapeamento completo abaixo.

Além disso, a Orders API 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 Orders API, 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.

Adaptar os headers

A Orders API 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.

Migrar a criação de orders

A Orders API 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.

3

3

Atualizar o tratamento de erros na criação

Os erros do fluxo POST e PUT são idênticos na Dynamic QR Model API. A Orders API consolida a maioria dos erros de validação específicos por campo nos códigos genéricos property_value e property_type, com o detalhe do campo no corpo da resposta. Além disso, as mensagens de resposta são mais descritivas, facilitando a identificação e resolução de problemas. Consulte as tabelas abaixo para mais detalhes.

Erros que mudam de comportamento

Os seguintes erros existem em ambas as APIs mas com comportamento diferente na Orders API.

HTTP	Dynamic QR Model API	Orders API	Observação
400	Múltiplos: invalid_collectorId, invalid_externalPosId, invalid_external_reference, invalid_total_amount, invalid_items.*, invalid_sponsor.* e outros	property_value	property_value consolida os erros de validação por campo. O campo com erro está indicado no detalhe da resposta.
400	(JSON malformado)	property_type	A Orders API distingue JSON malformado com um código próprio em vez do genérico error_creating_seller_qr_order.
400 → 401	(autenticação via middleware, 400)	unauthorized	Na Dynamic QR Model API, era 400. Na Orders API, é 401 explícito.

Erros que permanecem iguais

O seguinte erro tem o mesmo comportamento em ambas as APIs.

HTTP	Erro	Observação
500	Genérico	Erro interno. Verifique o retorno e repita a requisição.

Erros introduzidos pela Orders API

Os seguintes erros não têm equivalente na Dynamic QR Model API.

HTTP	Erro	Observação
400	sponsor_id_not_valid	Valor inválido como integration_data.sponsor.id.
400	marketplace_not_valid	O Access Token não foi obtido via OAuth.
400	empty_required_header	X-Idempotency-Key ausente.
400	unsupported_site	País não suportado.
400	unsupported_properties	Propriedade não suportada no body. O campo com erro está indicado no detalhe da resposta.
401	unauthorized	Access Token inválido ou expirado.
404	pos_not_found	O external_pos_id não pertence a nenhuma caixa.
404	marketplace_fee_not_allowed	Não é permitido enviar marketplace_fee. O marketplace não foi encontrado.
409	idempotency_key_already_used	O X-Idempotency-Key já foi utilizado com uma requisição distinta nas últimas 24 horas.

Atualizar a consulta de orders

O endpoint de consulta GET /v1/orders/{order_id}API está disponível para os modos dinâmico e híbrido na Orders API. Na Dynamic QR Model API, 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 Orders API permite consultar o estado completo da order diretamente pelo order_id, incluindo status, pagamentos, reembolsos e dados do meio de pagamento.

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

2

2

Atualizar o tratamento de erros na consulta

Na consulta, os erros foram agrupados conforme o tipo de alteração. Consulte as tabelas abaixo para mais detalhes.

Os erros legacy correspondem ao endpoint de consulta do fluxo PUT apenas.

Erros que desaparecem

Os seguintes erros existem na Dynamic QR Model API no fluxo PUT, mas não têm equivalência na Orders API.

HTTP	Dynamic QR Model API	Observação
400	invalid_collectorId	Removido na Orders API. A consulta opera sobre o order_id.
400	invalid_externalPosId	Removido. A consulta opera sobre order_id, não sobre a caixa.
400	pos_obtainment_by_external_id_error	Removido. O conceito de POS como parâmetro de consulta desaparece.
400	pos_deleted_error	Removido na Orders API.
403	forbidden	Removido na Orders API.

Erros renomeados

Os seguintes erros foram renomeados na Orders API.

HTTP	Dynamic QR Model API	Orders API	Observação
404	point_of_sale_in_store_order_not_found e in_store_order_not_found	order_not_found	Os dois casos são unificados em order_not_found.

Erros que mudam de comportamento

Os seguintes erros existem em ambas as APIs mas com comportamento diferente na Orders API.

HTTP	Dynamic QR Model API	Orders API	Observação
400 → 401	autenticação via middleware	unauthorized	Na Dynamic QR Model API, era 400. Na Orders API, é 401 explícito.

Erros introduzidos pela Orders API

Os seguintes erros não têm equivalência na Dynamic QR Model API.

HTTP	Erro	Observação
400	invalid_path_param	O order_id tem formato inválido. Deve começar com ORD seguido de 26 caracteres.
401	unauthorized	Access Token inválido ou expirado.
404	order_not_found	O order_id não corresponde a nenhuma order criada.
500	Genérico	Erro interno. Verifique o retorno e repita a requisição.

Atualizar o cancelamento de orders

O endpoint de cancelamento POST /v1/orders/{order_id}/cancelAPI está disponível para ambos os modos na Orders API. Na Dynamic QR Model API, 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.

2

2

Atualizar o tratamento de erros no cancelamento

No cancelamento, os erros foram agrupados conforme o tipo de alteração. Consulte as tabelas abaixo para mais detalhes.

Os erros legacy correspondem ao endpoint de cancelamento do fluxo PUT apenas.

Erros que desaparecem

Os seguintes erros existem na Dynamic QR Model API no fluxo PUT, mas não têm equivalência na Orders API.

HTTP	Dynamic QR Model API	Observação
400	invalid_collectorId	Removido na Orders API.
400	invalid_externalPosId	Removido. O {external_pos_id} deixa de ser parâmetro de path.
400	pos_deleted_error	Removido na Orders API.
403	forbidden	Removido. A identidade é validada internamente pelo Access Token.

Erros renomeados

Os seguintes erros foram renomeados na Orders API.

HTTP	Dynamic QR Model API	Orders API	Observação
400 → 404	pos_obtainment_by_external_id_error e in_store_order_delete_error (order não encontrada)	order_not_found	Na Dynamic QR Model API, era 400. Na Orders API, é 404. O cancelamento passa a operar sobre o order_id.
409	in_store_order_delete_error (Cannot delete a locked order)	instore_order_locked_error	Mesmo conceito. O nome do código de erro muda.

Erros que mudam de comportamento

Os seguintes erros existem em ambas as APIs mas com comportamento diferente na Orders API.

HTTP	Dynamic QR Model API	Orders API	Observação
400 → 401	autenticação via middleware	unauthorized	Na Dynamic QR Model API, era 400. Na Orders API, é 401 explícito.

Erros que permanecem iguais

O seguinte erro tem o mesmo comportamento em ambas as APIs.

HTTP	Erro	Observação
500	Genérico	Erro interno. Verifique o retorno e repita a requisição.

Erros introduzidos pela Orders API

Os seguintes erros não têm equivalente na Dynamic QR Model API.

HTTP	Erro	Observação
400	empty_required_header	X-Idempotency-Key ausente.
400	invalid_path_param	O order_id tem formato inválido.
401	unauthorized	Access Token inválido ou expirado.
404	order_not_found	O order_id não corresponde a nenhuma order criada.
409	idempotency_key_already_used	O X-Idempotency-Key já foi utilizado com uma requisição distinta.
409	order_already_canceled	A order já está cancelada. Orders só podem ser canceladas com status: created.

Implementar reembolsos com o endpoint dedicado

A Orders API introduz o endpoint dedicado POST /v1/orders/{order_id}/refundAPI para reembolsos, que não existia na Dynamic QR Model API 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
curl -X POST \
  'https://api.mercadopago.com/v1/orders/{{ORDER_ID}}/refund' \
  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
  -H 'X-Idempotency-Key: {{IDEMPOTENCY_KEY}}'

Validar a migração

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.