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

La migración de la Instore Orders 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 que no existían antes: endpoints dedicados de consulta por order_id, cancelación y reembolso.

La migración no implica cambios en el flujo de negocio: el cliente sigue escaneando el Código QR con la aplicación de Mercado Pago y confirmando el pago. Además, en esta modalidad, la Orders API habilita retiro de dinero (extracash y cash-out), descuentos por medio de pago, descuentos por categoría y cuotas sin interés. Para más detalles, consulta la documentación de procesamiento de transacciones.

A continuación, te explicamos 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 API, cada operación utilizaba una URL con el identificador del usuario y de la caja en el path. La Orders API consolida estas operaciones en endpoints estandarizados e introduce recursos que no existían antes.

En la Instore Orders API, existían dos endpoints válidos para la creación y cancelación: POST /mpmobile/instore/qr/{user_id}/{external_id}API, usando el identificador externo de la caja, y /mpmobile/instore/qr/{pos_id}, usando el identificador interno. Ambos migran al mismo endpoint en la Orders API: POST /v1/ordersAPI, donde la caja se identifica por el campo config.qr.external_pos_id en el body.

Actualizar el modelo de status y notificaciones

Uno de los cambios más significativos entre la Instore Orders API y la Orders API es el modelo de status. En la Instore Orders API, el estado de una transacción se determinaba mediante 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 este 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 dos cambios obligatorios de headers que afectan a todos los endpoints. El Access Token debe enviarse a través del header Authorization. El envío vía query param no está permitido en la Orders API. Aplica los cambios a continuación antes de probar cualquier otro recurso.

Migrar la creación de orders

Los endpoints de creación POST /mpmobile/instore/qr/{user_id}/{external_id}API y POST /mpmobile/instore/qr/{pos_id} migran a POST /v1/ordersAPI. Además del cambio de URL, la estructura de la solicitud fue significativamente reorganizada: el identificador del usuario y de la caja dejan el path y pasan al body, se introdujeron nuevos campos obligatorios y la Orders API ofrece tres modos de Código QR configurables a través de config.qr.mode. Sigue los pasos a continuación para adaptar la solicitud, la respuesta y el tratamiento de errores.

curl
curl -X POST \
  'https://api.mercadopago.com/v1/orders' \
  -H 'Content-Type: application/json' \
  -H 'X-Idempotency-Key: {{IDEMPOTENCY_KEY}}' \
  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
  -d '{
    "type": "qr",
    "total_amount": "50.00",
    "external_reference": "ext_ref_1234",
    "config": {
      "qr": {
        "external_pos_id": "STORE001POS001",
        "mode": "static"
      }
    },
    "transactions": {
      "payments": [
        {
          "amount": "50.00"
        }
      ]
    },
    "items": [
      {
        "title": "Smartphone",
        "unit_price": "50.00",
        "quantity": 1,
        "unit_measure": "unit"
      }
    ]
  }'

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, lo que facilita la identificación y resolución de problemas. Consulta las tablas a continuación para más detalles.

Errores que desaparecen

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

HTTP	Instore Orders API	Observación
400	invalid_collector_id	Eliminado. La identidad se obtiene directamente del Access Token.

Errores renombrados

Los siguientes errores fueron renombrados en la Orders API.

HTTP	Instore Orders API	Orders API	Observación
400	invalid_sponsor_id	sponsor_id_not_valid	El campo migra a integration_data.sponsor.id.
404	pos_obtainment_error	pos_not_found	El external_pos_id deja de ser parámetro de path y pasa al body.

Errores que cambian de comportamiento

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

HTTP	Instore Orders API	Orders API	Observación
400	invalid_items	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	json_syntax_error	property_type	Equivalente más cercano. En la Instore Orders API, también cubría JSON malformado en general.
400	invalid_access_token	unauthorized (HTTP 401)	En la Instore Orders 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 API.

HTTP	Error	Observación
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.
400	bad_request	Campos no soportados o inválidos en general.
400	marketplace_not_valid	El Access Token no fue obtenido a través de OAuth y no es posible identificar un marketplace válido.
400	seller_configuration	El vendedor no está autorizado para realizar transacciones de retiro de dinero. Comunicarse con el equipo comercial de Mercado Pago para habilitar esta funcionalidad.
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.

Implementar la consulta de orders

El endpoint de consulta GET /v1/orders/{order_id}API es una novedad exclusiva de la Orders API. La Instore Orders API no contaba con un endpoint dedicado para consultar el estado de una transacción. Antes, el estado se obtenía exclusivamente a través de notificaciones de webhook de los tópicos payments y merchant_orders. La Orders API permite consultar el estado completo de la order en cualquier momento, incluyendo status, pagos, reembolsos y datos del medio de pago.

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

Actualizar la cancelación de orders

El endpoint de cancelación cambia completamente de estructura: de DELETE /mpmobile/instore/qr/{user_id}/{external_id}API 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 identificador único de la order.

En la Instore Orders 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. El response pasó de vacío (HTTP 204) al objeto completo de la order con status: "canceled" (HTTP 200).

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 API pero no tienen equivalencia en la Orders API.

HTTP	Instore Orders API	Observación
400	invalid_collector_id	Eliminado en la Orders API.
401	unauthorized (authorization value not present)	Eliminado. Ocurría al enviar {user_id} alfanumérico. La identidad se obtiene directamente del Access Token.
403	forbidden	Eliminado. Ocurría cuando el {user_id} no pertenecía al dueño del Access Token.

Errores renombrados

Los siguientes errores fueron renombrados en la Orders API.

HTTP	Instore Orders API	Orders API	Observación
400 → 404	pos_obtainment_by_external_id_error	order_not_found	En la Instore Orders API, era 400. En la Orders API, es 404. La cancelación pasa a operar sobre el order_id.

Errores que cambian de comportamiento

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

HTTP	Instore Orders API	Orders API	Observación
400 → 401	invalid_access_token	unauthorized	En la Instore Orders 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 API.

HTTP	Error	Observación
400	empty_required_header	X-Idempotency-Key ausente.
400	invalid_path_param	El order_id tiene formato inválido. Debe comenzar con ORD seguido de 26 caracteres.
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 cancelarse con status: created.
409	instore_order_locked_error	No es posible cancelar una order mientras el pago está en curso.

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 API. Antes, era necesario recibir el webhook del pago, obtener el payment_id y ejecutar el reembolso a través de la API de Payments por separado. Ahora, el reembolso se realiza 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 funcione correctamente en todos los flujos antes de ir a producción.

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