Skip to main content

API de Integración — Restaurantero Pro

Versión: 1.0.3
Base URL: https://my.restauranteropro.com/api/v1
Formato: JSON (inspirado en JSON:API)
Autenticación: Header X-API-Key

1. Autenticación

Todos los endpoints requieren el header:
Las API Keys se generan en el panel de Restaurantero Pro por sucursal. Usa rpro_test_ durante las pruebas y rpro_live_ en producción.

Errores de autenticación

CódigoSignificadoQué hacer
401 UnauthorizedAPI Key faltante o malformadaVerifica el header X-API-Key
403 ForbiddenAPI Key válida pero sin permiso para este endpointVerifica el plan contratado
429 Too Many RequestsRate limit excedidoEspera 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

Todos los campos monetarios son enteros que representan centavos. Nunca se envían decimales.

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:00 todo el año

Idempotencia — obligatoria en todos los POST de ingesta

Todos los POST /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
Body del request:
Response exitoso 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

Tipos de pago estándar:
payment_typeDescripción
cashEfectivo
card_creditTarjeta crédito
card_debitTarjeta débito
transferTransferencia / SPEI
rappiRappi
uber_eatsUber Eats
didi_foodDiDi Food
otherOtro

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.
Cuándo enviar el catálogo:
  • Al configurar la integración por primera vez
  • Cuando se crea un Item nuevo en RC
  • Cuando se modifica un Item (precio, nombre, categoría)
  • Cuando se desactiva un Item
Body del request:
Campos por item:
CampoTipoRequeridoDescripción
namestring✅ SíNombre del platillo o producto
item_identifieruuidRecomendadoUUID del item en RC — clave de upsert principal
item_skustringRecomendadoidentification del item en RC — clave de upsert secundaria
categorystringNoNombre de la categoría
category_typestringNofood, beverage, bar o other
typestringNoTipo del item (simple, combo, etc.)
unit_price_centsintegerNoPrecio de venta en centavos
unit_cost_centsintegerNoCosto del platillo en centavos
descriptionstringNoDescripción del platillo
statusstringNoactive o inactive (default: active)
Si envías 5 o más items, los platillos que no vengan en el payload serán marcados automáticamente como inactive.
Response exitoso 200 OK:
Bakery Pro requiere el campo identification en el response. Por cada item creado, RC Express debe incluir el identification generado por makeIdentificationFromCategoryHierarchy(). Bakery Pro lo almacena como SKU visible del producto en reportes y etiquetas.
Mapeo desde RC para Carlos:
El precio en RC viene del trait Amountable — usa $item->unitPrice->amount (tipo unit_price) y $item->unitCost->amount (tipo unit_cost). Multiplica por 100 para convertir a centavos.

3.6 Categorías Bakery Pro — POST /api/v1/ingest/categories

Sincroniza las categorías del catálogo de Bakery Pro hacia RC Express.
Sincronizar categorías SIEMPRE antes que productos. RC Express necesita el category_id interno para calcular el identification del item. Si se sincronizan productos antes que categorías, el identification generado será incorrecto.
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
Body del request:
Campos por categoría:
CampoTipoRequeridoDescripción
identifieruuid✅ SíUUID de la categoría en Bakery Pro — clave de upsert
namestring✅ SíNombre de la categoría
parent_identifieruuidNoUUID de la categoría padre. null si es categoría raíz
sequenceintegerNoOrden de aparición en el POS
Response exitoso 200 OK:
RC Express debe devolver el rc_express_id de cada categoría en el response. Bakery Pro lo necesita para mapear correctamente las categorías al sincronizar productos.
Mapeo desde Bakery Pro:

3.7 Descuentos — POST /api/v1/ingest/discounts


3.8 Cancelaciones — POST /api/v1/ingest/cancellations


4. Catálogo de errores

Código HTTPCódigo internoCausaSolución
400RPRO_ERR_400JSON malformadoVerifica estructura data.type, data.attributes
401RPRO_ERR_401API Key faltante o inválidaVerifica el header X-API-Key
403RPRO_ERR_403Sin permisosVerifica el plan contratado
404RPRO_ERR_404Branch no encontradoVerifica el UUID del branch
409RPRO_ERR_409Idempotency key ya procesadaNo reintentar — ya está guardado
422RPRO_ERR_422Campo requerido faltanteLee el campo error.field
422RPRO_ERR_422_CENTSMonto no es enteroMultiplica por 100 y convierte a int
429RPRO_ERR_429Rate limit excedidoEspera Retry-After segundos
500RPRO_ERR_500Error internoReportar a dev@restauranteropro.com

5. Checklist de integración

  • 1. API Key configuradaRESTAURANTERO_API_KEY en .env con prefijo rpro_live_
  • 2. Branch Identifier correcto — UUID de la sucursal en RESTAURANTERO_BRANCH_IDENTIFIER
  • 3. Categorías enviadas (Bakery Pro)POST /ingest/categories con todas las categorías activas ANTES de enviar productos
  • 4. Catálogo enviadoPOST /ingest/catalog con todos los platillos activos al iniciar la integración
  • 5. identification guardado — RC Express devuelve identification por 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 CashRegisterOpening es tipo zout y status completed
  • 8. Corte X no envía datos de negocio — Solo POST /ingest/cash-register con closing_type: "xout"
  • 9. Idempotency Keys únicos — Se usa el identifier del CashRegisterOpening como base con sufijos
  • 10. Montos en centavos — Todos los *_cents son integers, no decimales
  • 11. waiter_name incluido en cada línea — Requerido para Star Employees
  • 12. category_type correctofood, beverage, bar o other por 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

EventoCuándo se dispara
snapshot.completedCubos regenerados después de un Corte Z
alert.triggeredUn KPI cruzó su umbral de alerta
insight.generatedControllero IA generó el resumen diario
cash.varianceFaltante/sobrante excede el umbral configurado
inventory.low_stockIngrediente bajo el mínimo recomendado
purchase.suggestion_readyTiendita 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 via parent_identifier. RC Express debe devolver rc_express_id por categoría creada.
  • Sección 3.5 actualizada — Response de ingest/catalog ahora incluye array items con campo identification generado 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 campo waiter_name por 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