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. 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 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 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.

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

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

Uno de los cambios más significativos entre la API de Órdenes presenciales y la API de Orders es el modelo de status. En la API de Órdenes presenciales, 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 este 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.

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

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 API de Orders 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
Copiar
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"
      }
    ]
  }'

El endpoint de consulta GET /v1/orders/{order_id}API es una novedad exclusiva de la API de Orders. La API de Órdenes presenciales 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 API de Orders permite consultar el estado completo de la order en cualquier momento, incluyendo status, 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 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 API de Órdenes presenciales, 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. 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 de Órdenes presenciales. 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
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 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.