API de Integración — Restaurantero Pro
Versión: 1.0.3Base URL:
https://my.restauranteropro.com/api/v1Formato: JSON (inspirado en JSON:API)
Autenticación: Header
X-API-Key
1. Autenticación
Todos los endpoints requieren el header:rpro_test_ durante las pruebas y rpro_live_ en producción.
Errores de autenticación
| Código | Significado | Qué hacer |
|---|---|---|
401 Unauthorized | API Key faltante o malformada | Verifica el header X-API-Key |
403 Forbidden | API Key válida pero sin permiso para este endpoint | Verifica el plan contratado |
429 Too Many Requests | Rate limit excedido | Espera Retry-After segundos |
2. Convenciones generales
Formato de requests y responses
Todos los requests y responses usan JSON con estructura JSON:API:Dinero — siempre en centavos
Fechas y horas
- Fechas:
YYYY-MM-DD - Timestamps: ISO 8601 con timezone:
2026-05-15T23:45:00-07:00 - Hermosillo (sin cambio de horario): usar
-07:00todo el año
Idempotencia — obligatoria en todos los POST de ingesta
Todos losPOST /api/v1/ingest/* requieren el header X-Idempotency-Key.
Para RC: Usa el
identifier UUID del CashRegisterOpening como Idempotency Key.3. Endpoints de Ingesta
Tu POS implementa estos endpoints. Tu sistema llama a estos endpoints para enviarnos datos. Nosotros los procesamos y generamos la inteligencia.
Orden correcto al cerrar un Corte Z
3.1 Corte de caja — POST /api/v1/ingest/cash-register
Registra un corte de caja. Tipos:
- Corte X (
xout): cierre de turno parcial — informativo - Corte Z (
zout): cierre del día — trigger principal que procesa todos los cubos
202 Accepted:
La respuesta es
202 Accepted — el procesamiento es asíncrono. Usa webhooks (snapshot.completed) para saber cuándo los datos están listos.3.2 Ventas — POST /api/v1/ingest/sales
Body del request:
3.3 Pagos por método — POST /api/v1/ingest/payments
| payment_type | Descripción |
|---|---|
cash | Efectivo |
card_credit | Tarjeta crédito |
card_debit | Tarjeta débito |
transfer | Transferencia / SPEI |
rappi | Rappi |
uber_eats | Uber Eats |
didi_food | DiDi Food |
other | Otro |
3.4 Líneas de orden — POST /api/v1/ingest/orders
Envía los productos vendidos. Cada línea genera una fila independiente para Top 10 productos, Star Employees y Ventas por categoría.
3.5 Catálogo de platillos — POST /api/v1/ingest/catalog
Sincroniza el catálogo completo del POS con Restaurantero Pro. Usa upsert por item_identifier o item_sku.
Este endpoint se llama una vez al inicio de la integración y luego cada vez que cambie el catálogo. La forma recomendada es un
ItemObserver en RC que dispare el envío automáticamente.Integración Bakery Pro: Sincroniza las categorías PRIMERO usando
POST /api/v1/ingest/categories (sección 3.6) antes de enviar productos. RC Express necesita las categorías para generar el identification correctamente.- Al configurar la integración por primera vez
- Cuando se crea un
Itemnuevo en RC - Cuando se modifica un
Item(precio, nombre, categoría) - Cuando se desactiva un
Item
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
name | string | ✅ Sí | Nombre del platillo o producto |
item_identifier | uuid | Recomendado | UUID del item en RC — clave de upsert principal |
item_sku | string | Recomendado | identification del item en RC — clave de upsert secundaria |
category | string | No | Nombre de la categoría |
category_type | string | No | food, beverage, bar o other |
type | string | No | Tipo del item (simple, combo, etc.) |
unit_price_cents | integer | No | Precio de venta en centavos |
unit_cost_cents | integer | No | Costo del platillo en centavos |
description | string | No | Descripción del platillo |
status | string | No | active o inactive (default: active) |
200 OK:
3.6 Categorías Bakery Pro — POST /api/v1/ingest/categories
Sincroniza las categorías del catálogo de Bakery Pro hacia RC Express.
Cuándo enviar categorías:
- Al configurar la integración por primera vez
- Cuando se crea una categoría nueva en Bakery Pro
- Cuando se renombra una categoría en Bakery Pro
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
identifier | uuid | ✅ Sí | UUID de la categoría en Bakery Pro — clave de upsert |
name | string | ✅ Sí | Nombre de la categoría |
parent_identifier | uuid | No | UUID de la categoría padre. null si es categoría raíz |
sequence | integer | No | Orden de aparición en el POS |
200 OK:
3.7 Descuentos — POST /api/v1/ingest/discounts
3.8 Cancelaciones — POST /api/v1/ingest/cancellations
4. Catálogo de errores
| Código HTTP | Código interno | Causa | Solución |
|---|---|---|---|
400 | RPRO_ERR_400 | JSON malformado | Verifica estructura data.type, data.attributes |
401 | RPRO_ERR_401 | API Key faltante o inválida | Verifica el header X-API-Key |
403 | RPRO_ERR_403 | Sin permisos | Verifica el plan contratado |
404 | RPRO_ERR_404 | Branch no encontrado | Verifica el UUID del branch |
409 | RPRO_ERR_409 | Idempotency key ya procesada | No reintentar — ya está guardado |
422 | RPRO_ERR_422 | Campo requerido faltante | Lee el campo error.field |
422 | RPRO_ERR_422_CENTS | Monto no es entero | Multiplica por 100 y convierte a int |
429 | RPRO_ERR_429 | Rate limit excedido | Espera Retry-After segundos |
500 | RPRO_ERR_500 | Error interno | Reportar a dev@restauranteropro.com |
5. Checklist de integración
- 1. API Key configurada —
RESTAURANTERO_API_KEYen.envcon prefijorpro_live_ - 2. Branch Identifier correcto — UUID de la sucursal en
RESTAURANTERO_BRANCH_IDENTIFIER - 3. Categorías enviadas (Bakery Pro) —
POST /ingest/categoriescon todas las categorías activas ANTES de enviar productos - 4. Catálogo enviado —
POST /ingest/catalogcon todos los platillos activos al iniciar la integración - 5.
identificationguardado — RC Express devuelveidentificationpor item creado; Bakery Pro lo almacena como SKU - 6. ItemObserver configurado — El catálogo se actualiza automáticamente cuando cambia un Item en RC
- 7. Corte Z detectado — El service se invoca cuando
CashRegisterOpeninges tipozouty statuscompleted - 8. Corte X no envía datos de negocio — Solo
POST /ingest/cash-registerconclosing_type: "xout" - 9. Idempotency Keys únicos — Se usa el
identifierdelCashRegisterOpeningcomo base con sufijos - 10. Montos en centavos — Todos los
*_centsson integers, no decimales - 11.
waiter_nameincluido en cada línea — Requerido para Star Employees - 12.
category_typecorrecto —food,beverage,barootherpor línea - 13. Retry implementado — Al menos 3 intentos con backoff exponencial
- 14. Logging activo — Cada POST exitoso y fallido queda en los logs de RC
- 15. Orden de envío correcto — orders → discounts → cancellations → payments → sales → cash-register
- 16. Prueba con key
rpro_test_— Enviar categorías + catálogo + 3 cortes Z de prueba
6. Flujo completo de integración
6.1 Flujo diario (restaurant_controller)
6.2 Snippet PHP completo
7. Webhooks
| Evento | Cuándo se dispara |
|---|---|
snapshot.completed | Cubos regenerados después de un Corte Z |
alert.triggered | Un KPI cruzó su umbral de alerta |
insight.generated | Controllero IA generó el resumen diario |
cash.variance | Faltante/sobrante excede el umbral configurado |
inventory.low_stock | Ingrediente bajo el mínimo recomendado |
purchase.suggestion_ready | Tiendita generó nueva lista de compra |
10. Changelog
v1.0.3 — Junio 2026
POST /api/v1/ingest/categories— Nuevo endpoint (sección 3.6) para sincronizar categorías de Bakery Pro con RC Express. Soporta jerarquía padre/hijo viaparent_identifier. RC Express debe devolverrc_express_idpor categoría creada.- Sección 3.5 actualizada — Response de
ingest/catalogahora incluye arrayitemscon campoidentificationgenerado por RC Express para cada item nuevo. Requerido para Bakery Pro. - Checklist actualizado — Puntos 3, 4, 5 actualizados para incluir sync de categorías antes de productos.
- Sección 3.6 (Descuentos) renumerada a 3.7 — Para dar lugar a la nueva sección 3.6 de categorías.
v1.0.2 — Mayo 2026
POST /api/v1/ingest/catalog— Nuevo endpoint para sincronizar el catálogo de platillos del POS.- Sección 3.5 — Documentación completa del endpoint de catálogo con mapeo desde RC.
- Checklist — Actualizado a 14 puntos.
v1.0.1 — Mayo 2026
POST /api/v1/ingest/orders— Agregado campowaiter_namepor línea.- Checklist — Actualizado a 13 puntos.
v1.0.0 — Mayo 2026
Release inicial de la API pública de Restaurantero Pro.Restaurantero Pro — API Documentation v1.0.3
Desarrollado por Restaurant Controller · Hermosillo, Sonora, México
Junio 2026 · Confidencial — Solo para partners autorizados