Cómo migrar de la API de Órdenes presenciales V2 a la API de Orders

La API de Orders unifica el procesamiento de pagos con Código QR en Mercado Pago, ofreciendo endpoints estandarizados, un modelo de status consolidado y nuevos recursos nativos que no existían en la API de Órdenes presenciales V2. Además, todas las nuevas funcionalidades de Mercado Pago se desarrollarán sobre la API de Orders.

La migración de la API de Órdenes presenciales V2 a la API de Orders 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 API de Orders 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.

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 API de Órdenes presenciales V2, cada operación utilizaba una URL con el identificador del usuario, de la tienda y de la caja en el path. La API de Orders consolida estas operaciones en endpoints estandarizados identificados por el order_id.

Uno de los cambios más significativos entre la API de Órdenes presenciales V2 y la API de Orders es el modelo de status. En la API de Órdenes presenciales V2, 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 API de Orders unifica ese comportamiento en un único campo status en la order. Consulta el mapeo completo a continuación.

Además, la API de Orders 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 API de Orders, 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.

La API de Orders 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 API de Orders. Aplica el cambio a continuación antes de probar cualquier otro recurso.

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.

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 API de Órdenes presenciales V2, 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 API de Orders 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 API de Órdenes presenciales V2, esa información llegaba solo por notificación.

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

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 API de Órdenes presenciales V2, 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 API de Orders, la cancelación opera directamente sobre la order por el order_id, sin depender de la caja en el path.

La API de Orders introduce el endpoint dedicado POST /v1/orders/{order_id}/refundAPI para reembolsos, que no existía en la API de Órdenes presenciales V2. 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
Copiar
curl -X POST \
  'https://api.mercadopago.com/v1/orders/{{ORDER_ID}}/refund' \
  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
  -H 'X-Idempotency-Key: {{IDEMPOTENCY_KEY}}'

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.