API v1 · REST · self-service

Conecta tu app con Cobre

Tus ventas en tu contabilidad, tus pedidos entrando desde tu propia app o desde plataformas de reparto — sin hablar con soporte: creas tu llave desde tu back office y listo. La API es del plan Premium.

1. Crea tu llave

En tu back office → Configuración → API para desarrolladores: nombre, permisos, y copia la llave (cbr_live_…). Se muestra una sola vez — guárdala como cualquier secreto. Puedes revocarla cuando quieras.

2. Autenticación

curl https://api-production-d13f.up.railway.app/v1/orders \
  -H "Authorization: Bearer cbr_live_TU_LLAVE"

Reglas de la casa: el dinero SIEMPRE viaja en centavos ("totalCents": 12992 = $129.92 MXN), las fechas en ISO-8601 UTC, y el contrato de /v1 no se rompe — cambios incompatibles serían /v2.

3. Leer tus ventas

# últimas 100 (filtros: from, to, status, location, limit ≤ 500)
GET /v1/orders?from=2026-07-01&status=cobrada

{
  "data": [{
    "id": "…", "folio": 42, "type": "Para llevar", "status": "cobrada",
    "currency": "MXN", "totalCents": 12992, "tipCents": 1000,
    "createdAt": "2026-07-08T18:22:00.000Z",
    "items": [{ "name": "Tacos al pastor", "qty": 3, "unitPriceCents": 2900 }]
  }],
  "nextBefore": "2026-07-08T12:00:00.000Z"
}

4. Leer tu catálogo

GET /v1/products
{ "data": [{ "id": "…", "name": "Tacos al pastor", "priceCents": 2900, "currency": "MXN" }] }

5. Inyectar pedidos (tu app, Uber Eats, Rappi…)

Con el permiso Crear pedidos, cualquier canal mete órdenes que caen directo a la cocina en tiempo real:

POST /v1/orders
{
  "channel": "Uber Eats",
  "channelRef": "UE-9912",
  "paid": true,
  "items": [{ "productId": "…", "qty": 2, "notes": "sin cebolla" }]
}

paid: true = la plataforma ya cobró (no entra al cajón de efectivo). La referencia se ve en cocina y en el ticket.

Permisos (scopes)

ScopeQué permite
read:ordersLeer ventas y su detalle
read:catalogLeer productos y precios
read:shiftsLeer cortes de caja
read:inventoryLeer existencias (de la sucursal de la llave)
read:membersLeer socios del gym
write:ordersCrear pedidos desde canales externos
write:checkinsRegistrar check-ins (torniquetes y lectores)

Webhooks — tu app se entera sola

En Configuración → Webhooks: pon tu URL, elige eventos y guarda el secret (se muestra una vez). Te mandamos un POST por evento con firma X-Cobre-Signature (HMAC-SHA256 del body con tu secret — verifícala SIEMPRE):

{ "event": "order.paid", "data": { "orderId": "…", "folio": 42, "totalCents": 12992 }, "at": "…" }

Eventos: order.created · order.paid · order.canceled · shift.closed · member.checkin. Reintentos: 2 (5 s y 30 s). A 20 fallos seguidos el webhook se pausa solo. El botón Probar manda un ping firmado.

Más lecturas

GET /v1/shifts      # cortes cerrados con diferencia
GET /v1/inventory   # existencias de la sucursal
GET /v1/members     # socios del gym (sin códigos QR)
POST /v1/checkins   # { "code": "482913" } → { "allowed": true }

Errores y límites