Cómo migrar de la Instore Orders V2 API a la Orders API

La migración de la Instore Orders V2 API a la Orders API implica la actualización de endpoints y campos de la solicitud, la consolidación del modelo de notificaciones y el aprovechamiento de nuevos recursos nativos, como los endpoints dedicados de cancelación y reembolso. El principal cambio en la creación es que la Orders API retorna 201 Created con el objeto completo de la order, en lugar de 204 No Content sin body. La migración no implica cambios en el flujo de negocio: el cliente continúa escaneando el Código QR con la aplicación de Mercado Pago y confirmando el pago.

Consulta a continuación cómo realizar esta migración de forma completa.

Mapear los cambios de endpoint

Antes de iniciar los pasos de migración, consulta la tabla a continuación para tener una visión general de todos los cambios de endpoint. En la Instore Orders V2 API, cada operación utilizaba una URL con el identificador del usuario, de la tienda y de la caja en el path. La Orders API consolida estas operaciones en endpoints estandarizados identificados por el order_id.

Actualizar el modelo de status y notificaciones

Uno de los cambios más significativos entre la Instore Orders V2 API y la Orders API es el modelo de status. En la Instore Orders V2 API, el estado de una transacción era determinado por el monitoreo de notificaciones de dos tópicos independientes: payments y merchant_orders con campos y valores distintos para cada uno. La Orders API unifica ese comportamiento en un único campo status en la order. Consulta el mapeo completo a continuación.

Además, la Orders API también introduce el campo status_detail, que permite identificar con mayor detalle el estado de la transacción. Los valores posibles son created, canceled, accredited, refunded y expired.

En cuanto a las notificaciones, en la API Legacy podían configurarse mediante el campo notification_url en el body de la solicitud (modelo IPN) o mediante webhooks con los tópicos payments y merchant_orders. En la Orders API, el campo notification_url no existe y los tópicos payments y merchant_orders no son compatibles. Configura las notificaciones en Tus integraciones, suscribiéndote al tópico "Order (Mercado Pago)" (orders), antes de ir a producción. Para más información, consulta la documentación de notificaciones.

Adaptar los headers

La Orders API introduce un cambio obligatorio de header que afecta a todos los endpoints. El Access Token debe enviarse vía header Authorization. El envío vía query param no está permitido en la Orders API. Aplica el cambio a continuación antes de probar cualquier otro recurso.

Migrar la creación de orders

El endpoint de creación cambia de PUT /instore/qr/seller/collectors/{user_id}/stores/{external_store_id}/pos/{external_pos_id}/ordersAPI a POST /v1/ordersAPI. Además del cambio de método de PUT a POST y de la URL, la respuesta pasa de HTTP 204 No Content sin body a 201 Created con el objeto completo de la order. El {user_id} y los parámetros de path de tienda y caja son eliminados. La identidad proviene del Access Token y la caja es identificada por el campo config.qr.external_pos_id en el body. Sigue los pasos a continuación para adaptar la solicitud, la respuesta y el tratamiento de errores.

3

3

Actualizar el tratamiento de errores en la creación

La Orders API consolida la mayoría de los errores de validación específicos por campo en los códigos genéricos property_value y property_type, con el detalle del campo en el cuerpo de la respuesta. Además, los mensajes de respuesta son más descriptivos, facilitando la identificación y resolución de problemas. Consulta las tablas a continuación para más detalles.

Errores que cambian de comportamiento

Los siguientes errores existen en ambas APIs pero con comportamiento diferente en la Orders API.

HTTP	Instore Orders V2 API	Orders API	Observación
400	Múltiples: invalid_collectorId, invalid_externalStoreId, invalid_externalPosId, invalid_total_amount, invalid_items.* y otros	property_value	property_value consolida los errores de validación por campo. El campo con error está indicado en el detalle de la respuesta.
400	error_creating_seller_qr_order (JSON malformado)	property_type	La Orders API distingue JSON malformado con un código propio en lugar del genérico error_creating_seller_qr_order.
400	error_creating_seller_qr_order (errores generales)	bad_request	El código genérico error_creating_seller_qr_order abarcaba múltiples errores. La Orders API usa bad_request para casos no cubiertos por otros códigos.
400	error_invalid_sponsor_id	sponsor_id_not_valid	El campo migra a integration_data.sponsor.id.
400 → 401	autenticación vía middleware	unauthorized	En la Instore Orders V2 API, la autenticación fallida retornaba 400. En la Orders API, es 401 explícito.
404	pos_obtainment_error	pos_not_found	El external_pos_id deja de ser parámetro de path y pasa al body.

Errores que permanecen iguales

El siguiente error tiene el mismo comportamiento en ambas APIs.

HTTP	Error	Observación
500	Genérico	Error interno. Verifica el retorno y repite la solicitud.

Errores introducidos por la Orders API

Los siguientes errores no tienen equivalencia en la Instore Orders V2 API.

HTTP	Error	Observación
400	marketplace_not_valid	El Access Token no fue obtenido vía OAuth y no es posible identificar un marketplace válido.
400	empty_required_header	X-Idempotency-Key ausente.
400	unsupported_site	Intento de crear la order en un país no soportado.
400	unsupported_properties	Propiedad no soportada en el body. El campo con error está indicado en el detalle de la respuesta.
404	marketplace_fee_not_allowed	No está permitido enviar marketplace_fee porque el marketplace no fue encontrado.
409	idempotency_key_already_used	El X-Idempotency-Key ya fue utilizado con una solicitud distinta en las últimas 24 horas.

Actualizar la consulta de orders

El endpoint de consulta cambia de GET /instore/qr/seller/collectors/{user_id}/pos/{external_pos_id}/ordersAPI a GET /v1/orders/{order_id}API. En la Instore Orders V2 API, la consulta era realizada por caja (external_pos_id), retornando la order activa en esa caja sin exponer el estado de la transacción. La Orders API sustituye el endpoint de consulta por caja por un endpoint que opera directamente por el order_id y retorna el estado completo de la transacción: status, pagos, reembolsos y datos del medio de pago. En la Instore Orders V2 API, esa información llegaba solo por notificación.

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

2

2

Actualizar el tratamiento de errores en la consulta

En la consulta, los errores fueron agrupados según el tipo de cambio. Consulta las tablas a continuación para más detalles.

Errores que desaparecen

Los siguientes errores existen en la Instore Orders V2 API pero no tienen equivalencia en la Orders API.

HTTP	Instore Orders V2 API	Observación
400	invalid_collectorId	Eliminado en la Orders API. La consulta opera sobre el order_id.
400	invalid_externalPosId	Eliminado. La consulta opera sobre order_id, no sobre la caja.
400	pos_obtainment_by_external_id_error	Eliminado. El concepto de POS como parámetro de consulta desaparece.
400	pos_deleted_error	Eliminado en la Orders API.
403	forbidden	Eliminado en la Orders API.

Errores renombrados

Los siguientes errores fueron renombrados en la Orders API.

HTTP	Instore Orders V2 API	Orders API	Observación
404	point_of_sale_in_store_order_not_found y in_store_order_not_found	order_not_found	Los dos casos de not found son unificados en order_not_found.

Errores que cambian de comportamiento

Los siguientes errores existen en ambas APIs pero con un comportamiento diferente en la Orders API.

HTTP	Instore Orders V2 API	Orders API	Observación
400 → 401	autenticación vía middleware	unauthorized	En la Instore Orders V2 API, era 400. En la Orders API, es 401 explícito.

Errores introducidos por la Orders API

Los siguientes errores no tienen equivalencia en la Instore Orders V2 API.

HTTP	Error	Observación
400	invalid_path_param	El order_id tiene formato inválido. Debe comenzar con ORD seguido de 26 caracteres.
401	unauthorized	Access Token inválido o expirado.
404	order_not_found	El order_id no corresponde a ninguna order creada.
500	Genérico	Error interno. Verifica el retorno y repite la solicitud.

Actualizar la cancelación de orders

El endpoint de cancelación cambia de DELETE /instore/qr/seller/collectors/{user_id}/pos/{external_pos_id}/ordersAPI a POST /v1/orders/{order_id}/cancelAPI. El método HTTP cambia de DELETE a POST, el {user_id} y el {external_id} salen del path, y la cancelación pasa a operar sobre el order_id. El response pasó de vacío (HTTP 204) al objeto completo de la order con status: "canceled" (HTTP 200).

En la Instore Orders V2 API, la cancelación eliminaba la order activa asociada a la caja, una operación sobre la caja y no sobre la transacción individual. En la Orders API, la cancelación opera directamente sobre la order por el order_id, sin depender de la caja en el path.

2

2

Actualizar el tratamiento de errores en la cancelación

En la cancelación, los errores fueron agrupados según el tipo de cambio. Consulta las tablas a continuación para más detalles.

Errores que desaparecen

Los siguientes errores existen en la Instore Orders V2 API pero no tienen equivalencia en la Orders API.

HTTP	Instore Orders V2 API	Observación
400	invalid_collector_id	Eliminado en la Orders API.
400	pos_deleted_error	Eliminado en la Orders API.
401	unauthorized (authorization value not present)	Eliminado. Ocurría al enviar {user_id} alfanumérico. La identidad es obtenida directamente del Access Token.
403	forbidden	Eliminado. La identidad es validada internamente por el Access Token.

Errores renombrados

Los siguientes errores fueron renombrados en la Orders API.

HTTP	Instore Orders V2 API	Orders API	Observación
400 → 404	pos_obtainment_by_external_id_error y in_store_order_delete_error	order_not_found	En la Instore Orders V2 API, era 400. En la Orders API, es 404. La cancelación pasa a operar sobre el order_id.
409	in_store_order_delete_error (Cannot delete a locked order)	instore_order_locked_error	Mismo concepto. El nombre del código de error cambia.

Errores que cambian de comportamiento

Los siguientes errores existen en ambas APIs pero con un comportamiento diferente en la Orders API.

HTTP	Instore Orders V2 API	Orders API	Observación
400 → 401	invalid_access_token	unauthorized	En la Instore Orders V2 API, era 400. En la Orders API, es 401.

Errores que permanecen iguales

El siguiente error tiene el mismo comportamiento en ambas APIs.

HTTP	Error	Observación
500	Genérico	Error interno. Verifica el retorno y repite la solicitud.

Errores introducidos por la Orders API

Los siguientes errores no tienen equivalencia en la Instore Orders V2 API.

HTTP	Error	Observación
400	empty_required_header	X-Idempotency-Key ausente.
400	invalid_path_param	El order_id tiene formato inválido.
401	unauthorized	Access Token inválido o expirado.
404	order_not_found	El order_id no corresponde a ninguna order creada.
409	idempotency_key_already_used	El X-Idempotency-Key ya fue utilizado con una solicitud distinta.
409	order_already_canceled	La order ya está cancelada. Las orders solo pueden ser canceladas con status: created.

Implementar reembolsos con el endpoint dedicado

La Orders API introduce el endpoint dedicado POST /v1/orders/{order_id}/refundAPI para reembolsos, que no existía en la Instore Orders V2 API. Anteriormente, era necesario recibir el webhook del pago, obtener el payment_id y ejecutar el reembolso por la API de Payments por separado. Ahora, el reembolso es realizado directamente sobre la 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 la migración

Después de aplicar los cambios, verifica que la integración opere correctamente en todos los flujos antes de ir a producción.

Accede a la documentación para saber cómo probar la integración.