Como migrar da Instore Orders V2 API para a Orders API

A migração da Instore Orders V2 API para a Orders API 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 Orders API 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.

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. Na Instore Orders V2 API, cada operação utilizava uma URL com o identificador do usuário, da loja e da caixa no path. A Orders API consolida essas operações em endpoints padronizados identificados pelo order_id.

Atualizar o modelo de status e notificações

Uma das mudanças mais significativas entre a Instore Orders V2 API e a Orders API é o modelo de status. Na Instore Orders V2 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. O envio via query param não é permitido na Orders API. Aplique a alteração a seguir antes de testar qualquer outro recurso.

Migrar a criação de orders

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.

3

3

Atualizar o tratamento de erros na criação

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	Instore Orders V2 API	Orders API	Observação
400	Múltiplos: invalid_collectorId, invalid_externalStoreId, invalid_externalPosId, invalid_total_amount, invalid_items.* 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	error_creating_seller_qr_order (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	error_creating_seller_qr_order (erros gerais)	bad_request	O código genérico error_creating_seller_qr_order abarcava múltiplos erros. A Orders API usa bad_request para casos não cobertos por outros códigos.
400	error_invalid_sponsor_id	sponsor_id_not_valid	O campo migra para integration_data.sponsor.id.
400 → 401	autenticação via middleware	unauthorized	Na Instore Orders V2 API, autenticação falha retornava 400. Na Orders API, é 401 explícito.
404	pos_obtainment_error	pos_not_found	O external_pos_id deixa de ser parâmetro de path e passa para o body.

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 equivalência na Instore Orders V2 API.

HTTP	Erro	Observação
400	marketplace_not_valid	O Access Token não foi obtido via OAuth e não é possível identificar um marketplace válido.
400	empty_required_header	X-Idempotency-Key ausente.
400	unsupported_site	Tentativa de criar a order em um país não suportado.
400	unsupported_properties	Propriedade não suportada no body. O campo com erro está indicado no detalhe da resposta.
404	marketplace_fee_not_allowed	Não é permitido enviar marketplace_fee porque 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 muda de GET /instore/qr/seller/collectors/{user_id}/pos/{external_pos_id}/ordersAPI para GET /v1/orders/{order_id}API. Na Instore Orders V2 API, a consulta era realizada por caixa (external_pos_id), retornando a order ativa naquela caixa sem expor o estado da transação. A Orders API 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 Instore Orders V2 API, essas informações chegavam apenas por notificação.

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.

Erros que desaparecem

Os seguintes erros existem na Instore Orders V2 API mas não têm equivalência na Orders API.

HTTP	Instore Orders V2 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	Instore Orders V2 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 de not found 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	Instore Orders V2 API	Orders API	Observação
400 → 401	autenticação via middleware	unauthorized	Na Instore Orders V2 API, era 400. Na Orders API, é 401 explícito.

Erros introduzidos pela Orders API

Os seguintes erros não têm equivalência na Instore Orders V2 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 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 Instore Orders V2 API, o cancelamento apagava a order ativa associada à caixa, uma operação sobre a caixa e não sobre a transação individual. Na Orders API, o cancelamento opera diretamente sobre a order pelo order_id, sem depender da caixa no path.

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.

Erros que desaparecem

Os seguintes erros existem na Instore Orders V2 API mas não têm equivalência na Orders API.

HTTP	Instore Orders V2 API	Observação
400	invalid_collector_id	Removido na Orders API.
400	pos_deleted_error	Removido na Orders API.
401	unauthorized (authorization value not present)	Removido. Ocorria ao enviar {user_id} alfanumérico. A identidade é obtida diretamente do Access Token.
403	forbidden	Removido. A identidade é validada internamente pelo Access Token.

Erros renomeados

Os seguintes erros foram renomeados na Orders API.

HTTP	Instore Orders V2 API	Orders API	Observação
400 → 404	pos_obtainment_by_external_id_error e in_store_order_delete_error	order_not_found	Na Instore Orders V2 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	Instore Orders V2 API	Orders API	Observação
400 → 401	invalid_access_token	unauthorized	Na Instore Orders V2 API, era 400. Na Orders API, é 401.

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 equivalência na Instore Orders V2 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 Instore Orders V2 API. 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
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.