MercadoPago Integration API

API intermediaria entre sistemas ERP y MercadoPago Point. Gestiona OAuth, sucursales, terminales, órdenes de pago, reembolsos y webhooks.

¿Qué hace esta API?

graph LR
    ERP["🖥️ ERP (Histrix)"] -->|API Key| API["⚡ Integration API<br/>Cloudflare Workers"]
    API -->|OAuth Token| MP["💳 MercadoPago API"]
    MP -->|Webhooks| API
    API <-->|Notificaciones <br/> Polling| ERP
    ADMIN["👤 Admin"] -->|Dashboard| API

La API actúa como puente entre el ERP y MercadoPago, abstrayendo toda la complejidad de la integración:

• El ERP usa IDs propios (caja, sucursal, ticket) — nunca ve IDs de MercadoPago
• La API traduce entre ambos mundos y persiste el estado
• MercadoPago procesa los pagos y notifica via webhooks

Funcionalidades principales

Inicio rápido

1. Crear API Key para un cliente

curl -X POST https://mercadopago.histrix.com.ar/api-keys \
  -H "Content-Type: application/json" \
  -H "x-api-token: ADMIN_TOKEN" \
  -d '{"client": "mi-cliente", "description": "Key producción"}'

2. Conectar cuenta de MercadoPago

Abrir en el navegador:

https://mercadopago.histrix.com.ar/oauth/login?client=mi-cliente

3. Crear sucursal con cajas POS

curl -X POST https://mercadopago.histrix.com.ar/stores \
  -H "Content-Type: application/json" \
  -H "x-api-token: mk_client_key_here" \
  -d '{
    "name": "Casa Central",
    "external_id": "SUC001",
    "location": {
      "street_name": "Av. Pellegrini",
      "street_number": "1234",
      "city_name": "Rosario",
      "state_name": "Santa Fe",
      "latitude": -32.94682,
      "longitude": -60.63932
    },
    "pos": [
      { "name": "Caja 1", "external_id": "SUC001-POS001" }
    ]
  }'

4. Asociar terminal física desde la app de MercadoPago

1. Encender la terminal Point — aparece el mensaje "Inicia sesión en este dispositivo con tu cuenta de Mercado Pago"
2. Elegir tipo de cuenta:
   • Soy responsable del negocio — si es el dueño de la cuenta recaudadora
   • Soy un colaborador — si fue señalada como cuenta colaboradora
3. Escanear QR — la terminal muestra un código QR. Abrir la app de MercadoPago en el celular, ir al ícono QR y escanearlo
4. Seleccionar sucursal y caja — la terminal muestra las sucursales creadas (paso 3). Seleccionar la correcta y confirmar la dirección
5. Crear contraseña — ingresar una contraseña para uso seguro de la terminal
6. Listo — la terminal muestra "¡Listo! Ya puedes cobrar con tu Point"

5. Verificar y configurar terminal en modo PDV

# Ver terminales asignadas
curl https://mercadopago.histrix.com.ar/terminals \
  -H "x-api-token: mk_client_key_here"

# Cambiar a modo PDV (controlado por ERP)
curl -X PATCH https://mercadopago.histrix.com.ar/terminals/operating-mode \
  -H "Content-Type: application/json" \
  -H "x-api-token: mk_client_key_here" \
  -d '{
    "caja_id": "SUC001-POS001",
    "operating_mode": "PDV"
  }'

6. Crear una orden de pago

curl -X POST https://mercadopago.histrix.com.ar/orders \
  -H "Content-Type: application/json" \
  -H "x-api-token: mk_client_key_here" \
  -d '{
    "caja_id": "SUC001-POS001",
    "external_reference": "TICKET-00001",
    "amount": "1500,50",
    "description": "Venta mostrador"
  }'

7. Consultar estado

curl https://mercadopago.histrix.com.ar/orders/550e8400-e29b-41d4-a716-446655440000 \
  -H "x-api-token: mk_client_key_here"

Entornos

Documentación interactiva

La API expone documentación OpenAPI con Scalar en /docs.

Repositorio

mundo-it/mercadopago-api