Cómo migrar de la Dynamic QR Model API a la Orders API

La Dynamic QR Model API 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 Orders API 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 Dynamic QR Model API solo para el flujo PUT. En la Orders API, 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 Dynamic QR Model API a la Orders API, sigue las indicaciones a continuación.

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. La Orders API 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.

Actualizar el modelo de estado y notificaciones

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

Migrar la creación de orders

La Orders API 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.

3

3

Actualizar el tratamiento de errores en la creación

Los errores del flujo POST y PUT son idénticos en la Dynamic QR Model API. 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 un comportamiento diferente en la Orders API.

HTTP	Dynamic QR Model API	Orders API	Observación
400	Múltiples: invalid_collectorId, invalid_externalPosId, invalid_external_reference, invalid_total_amount, invalid_items.*, invalid_sponsor.* 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 → 401	(autenticación vía middleware, 400)	unauthorized	En la Dynamic QR Model API, era 400. En la Orders API, es 401 explícito.

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 equivalente en la Dynamic QR Model API.

HTTP	Error	Observación
400	sponsor_id_not_valid	Valor inválido como integration_data.sponsor.id.
400	marketplace_not_valid	El Access Token no fue obtenido vía OAuth.
400	empty_required_header	X-Idempotency-Key ausente.
400	unsupported_site	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.
401	unauthorized	Access Token inválido o expirado.
404	pos_not_found	El external_pos_id no pertenece a ninguna caja.
404	marketplace_fee_not_allowed	No se permite enviar marketplace_fee. 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 GET /v1/orders/{order_id}API está disponible para los modos dinámico e híbrido en la Orders API. En la Dynamic QR Model API, 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 Orders API permite consultar el estado completo de la order directamente por el order_id, incluyendo estado, 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}}'

2

2

Actualizar el tratamiento de errores en la consulta

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

Los errores legacy corresponden al endpoint de consulta del flujo PUT únicamente.

Errores que desaparecen

Los siguientes errores existen en la Dynamic QR Model API en el flujo PUT, pero no tienen equivalencia en la Orders API.

HTTP	Dynamic QR Model 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	Dynamic QR Model 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 se unifican 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	Dynamic QR Model API	Orders API	Observación
400 → 401	autenticación vía middleware	unauthorized	En la Dynamic QR Model API, era 400. En la Orders API, es 401 explícito.

Errores introducidos por la Orders API

Los siguientes errores no tienen equivalente en la Dynamic QR Model 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 POST /v1/orders/{order_id}/cancelAPI está disponible para ambos modos en la Orders API. En la Dynamic QR Model API, 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).

2

2

Actualizar el tratamiento de errores en la cancelación

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

Los errores legacy corresponden al endpoint de cancelación del flujo PUT únicamente.

Errores que desaparecen

Los siguientes errores existen en la Dynamic QR Model API en el flujo PUT, pero no tienen equivalencia en la Orders API.

HTTP	Dynamic QR Model API	Observación
400	invalid_collectorId	Eliminado en la Orders API.
400	invalid_externalPosId	Eliminado. El {external_pos_id} deja de ser parámetro de path.
400	pos_deleted_error	Eliminado en la Orders API.
403	forbidden	Eliminado. La identidad se valida internamente por el Access Token.

Errores renombrados

Los siguientes errores fueron renombrados en la Orders API.

HTTP	Dynamic QR Model API	Orders API	Observación
400 → 404	pos_obtainment_by_external_id_error y in_store_order_delete_error (order no encontrada)	order_not_found	En la Dynamic QR Model 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	Dynamic QR Model API	Orders API	Observación
400 → 401	autenticación vía middleware	unauthorized	En la Dynamic QR Model API, era 400. En la Orders API, es 401 explícito.

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 equivalente en la Dynamic QR Model 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 cancelarse 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 Dynamic QR Model API 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
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 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.