Saltar a contenido

Órdenes

Creación, consulta, cancelación y reembolso de órdenes de pago.

Ciclo de vida de una orden

stateDiagram-v2
    [*] --> created: POST /orders
    created --> at_terminal: MP procesa
    at_terminal --> processed: Pago exitoso
    at_terminal --> canceled: Cancelado en terminal
    at_terminal --> failed: Pago rechazado
    at_terminal --> expired: Timeout
    at_terminal --> action_required: Requiere acción
    created --> canceled: POST /orders/cancel
    processed --> refunded: POST /orders/refund (total)
    processed --> partially_refunded: POST /orders/refund (parcial)

    processed --> [*]
    canceled --> [*]
    failed --> [*]
    expired --> [*]
    refunded --> [*]
    partially_refunded --> [*]

Endpoints

POST /orders

Crea una orden de pago en la terminal asociada a la caja del ERP.

Body:

Campo Tipo Requerido Descripción
caja_id string ✅ ID de la caja en el ERP
external_reference string ✅ Referencia del ticket (max 64 chars)
amount string ✅ Monto con coma decimal (ej: 1500,50)
description string ❌ Descripción (max 150 chars)
ticket_number string ❌ Número de factura
print_ticket boolean ❌ Imprimir ticket en terminal (default: false)
payment_method enum ❌ all, debit_card, credit_card, qr
expiration_minutes number ❌ Minutos de expiración 1-180 (default: 16) 
curl -X POST https://api.example.com/orders \
  -H "Content-Type: application/json" \
  -H "x-api-token: mk_client_key" \
  -d '{
    "caja_id": "SUC001-POS001",
    "external_reference": "TICKET-00001",
    "amount": "1500,50",
    "description": "Venta mostrador",
    "print_ticket": true,
    "ticket_number": "FAC-A-00001",
    "payment_method": "credit_card"
  }'

{
  "message": "Order created successfully",
  "order_id": "ORD01...",
  "external_reference": "TICKET-00001",
  "status": "created"
}

Flujo interno:

flowchart LR
    A["ERP envía<br/>caja_id + amount"] --> B["Buscar POS<br/>en DB"]
    B --> C["Buscar terminal<br/>en MP"]
    C --> D["Convertir monto<br/>coma → punto"]
    D --> E["Crear orden<br/>en MP"]
    E --> F["Guardar en DB"]
    F --> G["Responder<br/>al ERP"]

GET /orders/:orderId

Consulta el estado real de una orden en MercadoPago.

curl https://api.example.com/orders/550e8400 \
  -H "x-api-token: mk_client_key"

{
  "order_id": "550e8400",
  "external_reference": "TICKET-00001",
  "caja_id": "SUC001-POS001",
  "sucursal_id": "SUC001",
  "amount": "1500.50",
  "description": "Venta mostrador",
  "ticket_number": "FAC-A-00001",
  "status": "processed",
  "status_detail": "accredited",
  "payments": [
    {
      "id": "PAY01...",
      "amount": "1500.50",
      "paid_amount": "1500.50",
      "status": "approved",
      "payment_method": {
        "type": "credit_card",
        "installments": 1,
        "id": "visa"
      }
    }
  ],
  "refunds": [],
  "created_at": "2025-02-13T15:00:00Z",
  "last_updated_at": "2025-02-13T15:01:30Z"
}

Sincronización

Este endpoint siempre consulta el estado real en MercadoPago y actualiza la DB local si hubo cambios.

POST /orders/cancel

Cancela una orden de pago.

Body:

Campo Tipo Requerido Descripción
order_id string ✅ ID de la orden a cancelar 
curl -X POST https://api.example.com/orders/cancel \
  -H "Content-Type: application/json" \
  -H "x-api-token: mk_client_key" \
  -d '{ "order_id": "550e8400" }'

{
  "message": "Order canceled successfully",
  "status": "canceled",
  "status_detail": "canceled"
}

{ "error": "La orden no se puede cancelar desde la API, debe cancelarse desde la terminal" }

Estado at_terminal

Si la orden ya está en la terminal física (at_terminal), MercadoPago devuelve 409. El operador debe cancelar directamente desde la terminal.

POST /orders/refund

Reembolsa una orden (total o parcial).

Body:

Campo Tipo Requerido Descripción
order_id string ✅ ID de la orden a reembolsar
amount string ❌ Monto parcial con coma. Si no se envía → reembolso total 
curl -X POST https://api.example.com/orders/refund \
  -H "Content-Type: application/json" \
  -H "x-api-token: mk_client_key" \
  -d '{ "order_id": "550e8400" }'

curl -X POST https://api.example.com/orders/refund \
  -H "Content-Type: application/json" \
  -H "x-api-token: mk_client_key" \
  -d '{ "order_id": "550e8400", "amount": "500,00" }'

{
  "message": "Partial refund processed",
  "type": "partial",
  "amount": "500.00",
  "status": "partially_refunded",
  "status_detail": null
}

Reembolso parcial

Solo disponible para pagos con tarjeta, QR con billetera de Mercado Pago u otras billeteras. Si el método de pago no lo soporta, devuelve 422.