API

Introducción

La API de Micuadre POS te permite integrar el punto de venta con sistemas externos, automatizar operaciones y construir integraciones personalizadas. Utilizamos una arquitectura REST combinada con WebSockets para garantizar sincronización en tiempo real.

Todas las respuestas se entregan en formato JSON. La base URL para todas las peticiones es https://api.micuadre.com/v1.

Autenticación

Cada petición debe incluir tu API key en el header X-API-Key. Puedes generar tu API key desde el panel de administración del sistema.

X-API-Key: mca_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

Si la API key es inválida o no se envía, recibirás un error 401 Unauthorized.

Endpoints

Estos son los endpoints disponibles en la versión actual de la API:

WebSockets

Micuadre POS utiliza WebSockets para mantener todos los puntos de venta sincronizados en tiempo real. Puedes suscribirte a eventos específicos para reaccionar a cambios al instante.

Conéctate a wss://api.micuadre.com/v1/ws incluyendo tu API key como query parameter ?api_key=.

const ws = new WebSocket('wss://api.micuadre.com/v1/ws?api_key=mca_live_a1b2c3d4e5');

ws.onmessage = function(event) {
  const data = JSON.parse(event.data);
  console.log('Evento recibido:', data);
};

Los eventos disponibles incluyen sale.created, product.updated, stock.changed y shift.opened.

Ejemplos

A continuación se muestran ejemplos con curl para cada endpoint.

GET /api/state

curl -H "X-API-Key: mca_live_a1b2c3d4e5" \
  https://api.micuadre.com/v1/api/state

POST /api/sale

curl -X POST -H "X-API-Key: mca_live_a1b2c3d4e5" \
  -H "Content-Type: application/json" \
  -d '{
    "products": [
      {"id": "prod_001", "qty": 2, "price": 15},
      {"id": "prod_002", "qty": 1, "price": 35}
    ],
    "payment": "cash",
    "amount_received": 70
  }' \
  https://api.micuadre.com/v1/api/sale

POST /api/product

curl -X POST -H "X-API-Key: mca_live_a1b2c3d4e5" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Galletas María",
    "price": 15,
    "cost": 10,
    "stock": 100,
    "category": "alimentos"
  }' \
  https://api.micuadre.com/v1/api/product

POST /api/settings

curl -X POST -H "X-API-Key: mca_live_a1b2c3d4e5" \
  -H "Content-Type: application/json" \
  -d '{
    "tax_rate": 16,
    "currency": "MXN",
    "store_name": "Tienda Principal",
    "open_hours": {"mon-fri": "08:00-20:00"}
  }' \
  https://api.micuadre.com/v1/api/settings

POST /api/warehouse

curl -X POST -H "X-API-Key: mca_live_a1b2c3d4e5" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "adjust",
    "product_id": "prod_001",
    "quantity": 50,
    "reason": "restock"
  }' \
  https://api.micuadre.com/v1/api/warehouse

POST /api/purchase

curl -X POST -H "X-API-Key: mca_live_a1b2c3d4e5" \
  -H "Content-Type: application/json" \
  -d '{
    "supplier": "Distribuidora ABC",
    "items": [
      {"product_id": "prod_001", "qty": 100, "unit_cost": 9}
    ],
    "total": 900
  }' \
  https://api.micuadre.com/v1/api/purchase

POST /api/history/revert

curl -X POST -H "X-API-Key: mca_live_a1b2c3d4e5" \
  -H "Content-Type: application/json" \
  -d '{
    "transaction_id": "txn_abc123",
    "reason": "Devolución del cliente"
  }' \
  https://api.micuadre.com/v1/api/history/revert

GET /api/download

curl -H "X-API-Key: mca_live_a1b2c3d4e5" \
  "https://api.micuadre.com/v1/api/download?type=pdf&from=2026-01-01&to=2026-06-30" \
  -o reporte.pdf

Códigos de error

La API utiliza códigos de estado HTTP convencionales para indicar el resultado de cada operación.