Cómo migrar de la API QR Modelo dinámico a la API de Orders

La API de Orders unifica el procesamiento de pagos con Código QR en Mercado Pago, consolidando en un único endpoint los dos métodos de creación de la API QR Modelo dinámico y extendiendo los recursos de consulta y cancelación para ambos modos. Además, todas las nuevas funcionalidades de Mercado Pago se desarrollarán sobre la API de Orders.

La API QR Modelo dinámico poseía dos métodos de creación con comportamientos distintos:

• POST /qrs, modo QR dinámico: crea un pedido y retorna una trama QR única por transacción en el campo qr_data, sin asociarla a ninguna caja. La aplicación es responsable de convertir qr_data en Código QR y mostrarlo al cliente.
• PUT /qrs, modo QR híbrido: crea un pedido, lo asocia a la caja indicada con el {external_pos_id}, actualizando el QR estático vinculado, y retorna también el QR dinámico en el campo qr_data.

La API de Orders unifica estos dos métodos en un único endpoint POST /v1/ordersAPI, diferenciando el comportamiento por el parámetro config.qr.mode: el valor dynamic corresponde al flujo POST legacy y el valor hybrid corresponde al flujo PUT legacy.

Esta distinción impactaba también los recursos de consulta y cancelación, disponibles en la API QR Modelo dinámico solo para el flujo PUT. En la API de Orders, estos recursos pasan a estar disponibles para los dos flujos vía order_id.

Para realizar la migración de tu integración de la API QR Modelo dinámico a la API de Orders, sigue las indicaciones a continuación.

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. La API de Orders unifica los dos métodos de creación en un único POST /v1/ordersAPI y extiende los recursos de consulta y cancelación para ambos modos.

Uno de los cambios más significativos entre la API QR Modelo dinámico y la API de Orders es el modelo de estado. En la API QR Modelo dinámico, 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 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 todos los endpoints. El Access Token debe enviarse vía header Authorization. Aplica el cambio a continuación antes de probar cualquier otro recurso.

La API de Orders unifica los dos métodos de creación en un único POST /v1/ordersAPI, diferenciando el comportamiento por el parámetro config.qr.mode. El endpoint POST /qrs, modo QR dinámico, equivale a config.qr.mode: dynamic, y el endpoint PUT /qrs, modo QR híbrido, equivale a config.qr.mode: hybrid. En ambos casos, el {user_id} deja de ser parámetro de path, el {external_pos_id} pasa al body, y el campo type: "qr" pasa a ser obligatorio. Sigue los pasos a continuación para adaptar la solicitud, la respuesta y el tratamiento de errores de cada modo.

El endpoint de consulta GET /v1/orders/{order_id}API está disponible para los modos dinámico e híbrido en la API de Orders. En la API QR Modelo dinámico, la consulta existía solo para el flujo PUT y consultaba por caja, no por order. El flujo POST no tenía endpoint de consulta. El estado se obtenía exclusivamente vía notificaciones de payments y merchant_orders.

La API de Orders permite consultar el estado completo de la order directamente por el order_id, incluyendo estado, pagos, reembolsos y datos del medio de pago.

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

El endpoint de cancelación POST /v1/orders/{order_id}/cancelAPI está disponible para ambos modos en la API de Orders. En la API QR Modelo dinámico, la cancelación existía solo para el flujo PUT y cancelaba la order asociada a la caja vía DELETE. El flujo POST no tenía endpoint de cancelación.

El método HTTP cambia de DELETE a POST, el {user_id} y el {external_pos_id} salen del path, y la operación pasa a identificar la order por el order_id. El response pasó de vacío (HTTP 204) al objeto completo de la order con status: "canceled" (HTTP 200).

La API de Orders introduce el endpoint dedicado POST /v1/orders/{order_id}/refundAPI para reembolsos, que no existía en la API QR Modelo dinámico en ninguno de los dos flujos. Antes 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 se realiza directamente sobre la order, para ambos modos.

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 opera correctamente en todos los flujos antes de ir a producción.

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