API de Integración — Restaurantero Pro

Versión: 1.0.4
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:

X-API-Key: rpro_live_XXXXXXXXXXXXXXXX

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ó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

Verificar conexión — `GET /api/v1/ping`

Primer endpoint a llamar al configurar una integración nueva. Confirma que la API Key es válida y regresa información básica de la sucursal.

GET /api/v1/ping
X-API-Key: rpro_test_xxx

Response:

{
  "data": {
    "type": "ping",
    "attributes": {
      "status": "ok",
      "branch_name": "Pitic",
      "branch_id": "b1c2d3e4-f5a6-7890-abcd-ef1234567890",
      "plan": "pro",
      "environment": "test",
      "subscription_status": "active",
      "message": "Conexión establecida correctamente con Restaurantero Pro.",
      "api_version": "v1",
      "timestamp": "2026-07-18T02:25:54+00:00"
    }
  }
}

Campo subscription_status:

Valor	Significado	Comportamiento esperado del POS
`active`	Cuenta al corriente	Operación normal — sin acción requerida
`suspended`	Pago atrasado, en periodo de gracia	Mostrar aviso no bloqueante (banner), permitir seguir operando
`blocked`	Cuenta bloqueada por falta de pago prolongada	Bloquear nuevas ventas hasta que el status regrese a `active`

Todas las sucursales existentes tienen subscription_status: "active" hoy — este campo es informativo, sin ningún cliente afectado actualmente. Se recomienda llamar a /ping al iniciar sesión/turno y periódicamente durante el día (cada 15-30 min), no antes de cada venta individual.

2. Convenciones generales

Formato de requests y responses

Todos los requests y responses usan JSON con estructura JSON:API:

{
  "data": {
    "type": "sales",
    "attributes": {
      "branch_identifier": "uuid-aqui",
      "date": "2026-05-15",
      "total_sales_cents": 534550
    },
    "meta": {
      "pos_name": "restaurant_controller",
      "pos_version": "3.2.1",
      "sent_at": "2026-05-15T23:45:00Z"
    }
  }
}

Dinero — siempre en centavos

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

$150.00 MXN  →  15000
$534.50 MXN  →  53450
$1,200.00 MXN → 120000

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.

Intento 1:  Inmediato
Intento 2:  5 segundos después
Intento 3:  30 segundos después
Intento 4:  5 minutos después
Intento 5:  Marcar como pendiente y reintentar al arrancar RC

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

# SETUP — una sola vez al iniciar la integración
0a. POST /api/v1/ingest/categories     # categorías de Bakery Pro (PRIMERO si usa Bakery)
0b. POST /api/v1/ingest/catalog        # catálogo de platillos

# AL CERRAR EL CORTE Z — cada noche
1. POST /api/v1/ingest/orders          # líneas de lo que se vendió
2. POST /api/v1/ingest/discounts       # descuentos del turno
3. POST /api/v1/ingest/cancellations   # cancelaciones y voids
4. POST /api/v1/ingest/payments        # cómo se pagó
5. POST /api/v1/ingest/sales           # resumen de ventas
6. POST /api/v1/ingest/cash-register   # el corte (dispara el procesamiento)

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:

{
  "data": {
    "type": "cash-register",
    "attributes": {
      "branch_identifier": "b1c2d3e4-f5a6-7890-abcd-ef1234567890",
      "closing_type": "zout",
      "start_at": "2026-05-15T06:00:00-07:00",
      "end_at": "2026-05-15T23:45:00-07:00",
      "status": "completed",
      "summaries": [
        { "type": "cash_sales", "name": "Efectivo", "amount_cents": 125000 },
        { "type": "card_sales", "name": "Tarjeta", "amount_cents": 409550 },
        { "type": "tips_received", "name": "Propinas", "amount_cents": 30000 },
        { "type": "cash_theoretical", "name": "Efectivo teórico", "amount_cents": 125500 },
        { "type": "cash_actual", "name": "Efectivo real", "amount_cents": 125000 },
        { "type": "cash_variance", "name": "Diferencia", "amount_cents": -500 }
      ]
    },
    "meta": {
      "pos_name": "restaurant_controller",
      "pos_version": "3.2.1",
      "pos_variant": "full_dining",
      "sent_at": "2026-05-15T23:46:00Z",
      "cashier_name": "Ana García"
    }
  }
}

cash_theoretical y cash_actual son opcionales pero recomendados. Sin ellos, Restaurantero Pro solo puede mostrar la diferencia (cash_variance) sin el desglose completo. La convención de signos es: cash_variance = cash_actual - cash_theoretical — negativo es faltante, positivo es sobrante.

Response exitoso 202 Accepted:

{
  "data": {
    "type": "cash-register-ingest",
    "attributes": {
      "queued": true,
      "message": "Corte Z recibido. Los cubos se regenerarán en los próximos segundos."
    }
  }
}

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:

{
  "data": {
    "type": "sales",
    "attributes": {
      "branch_identifier": "b1c2d3e4-f5a6-7890-abcd-ef1234567890",
      "date": "2026-05-15",
      "shift": "dinner",
      "closing_type": "zout",
      "total_sales_cents": 534550,
      "total_sales_no_iva_cents": 461681,
      "food_sales_cents": 366614,
      "beverage_sales_cents": 167936,
      "bar_sales_cents": 0,
      "covers": 87,
      "tables_served": 24,
      "avg_ticket_cents": 6144
    },
    "meta": {
      "pos_name": "restaurant_controller",
      "sent_at": "2026-05-15T23:46:00Z"
    }
  }
}

3.3 Pagos por método — `POST /api/v1/ingest/payments`

{
  "data": {
    "type": "payments",
    "attributes": {
      "branch_identifier": "b1c2d3e4-f5a6-7890-abcd-ef1234567890",
      "date": "2026-05-15",
      "closing_type": "zout",
      "payments": [
        {
          "payment_type": "cash",
          "payment_type_name": "Efectivo",
          "amount_cents": 125000,
          "tips_cents": 8000,
          "change_cents": 3500,
          "transaction_count": 18
        },
        {
          "payment_type": "card_credit",
          "payment_type_name": "Tarjeta Crédito",
          "amount_cents": 280000,
          "tips_cents": 15000,
          "change_cents": 0,
          "transaction_count": 31
        }
      ]
    }
  }
}

Tipos de pago estándar:

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.

{
  "data": {
    "type": "orders",
    "attributes": {
      "branch_identifier": "b1c2d3e4-f5a6-7890-abcd-ef1234567890",
      "date": "2026-05-15",
      "closing_type": "zout",
      "lines": [
        {
          "item_identifier": "550e8400-e29b-41d4-a716-446655440001",
          "item_sku": "010501",
          "name": "Aguachile Mar y Tierra",
          "category": "Mariscos",
          "category_type": "food",
          "quantity": 2,
          "unit_price_cents": 28500,
          "subtotal_cents": 57000,
          "discount_cents": 0,
          "net_total_cents": 57000,
          "waiter_name": "Carlos López",
          "ordered_at": "2026-05-15T20:15:00-07:00"
        }
      ]
    }
  }
}

ordered_at está documentado pero hoy no llega poblado en producción. Es la hora exacta (hora, minuto, segundo) en que se ordenó ese producto — necesaria para el heatmap de ventas por hora del dashboard. Confirma en tu POS si ya capturas este dato internamente (por ejemplo, el created_at de la línea de orden) y empieza a incluirlo tal cual, en formato ISO 8601 con zona horaria. No es necesario un campo nuevo — este ya es el contrato oficial.

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:

{
  "data": {
    "type": "catalog",
    "attributes": {
      "branch_identifier": "b1c2d3e4-f5a6-7890-abcd-ef1234567890",
      "items": [
        {
          "item_identifier": "550e8400-e29b-41d4-a716-446655440001",
          "item_sku": "010501",
          "name": "BOLLO ALEMÁN",
          "description": "Bollo de mantequilla",
          "category": "BOLLITOS",
          "category_type": "food",
          "type": "simple",
          "unit_price_cents": 2800,
          "unit_cost_cents": 1200,
          "status": "active"
        }
      ]
    },
    "meta": {
      "pos_name": "restaurant_controller",
      "sent_at": "2026-06-25T10:00:00Z"
    }
  }
}

Campos por 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`)

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:

{
  "data": {
    "type": "catalog-ingest",
    "attributes": {
      "created": 1,
      "updated": 0,
      "total_sent": 1,
      "message": "Catálogo sincronizado: 1 nuevo, 0 actualizados.",
      "items": [
        {
          "item_identifier": "550e8400-e29b-41d4-a716-446655440001",
          "identification": "010501",
          "name": "BOLLO ALEMÁN"
        }
      ]
    }
  }
}

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:

// En RestauranteroProService.php — método sendCatalog()
$items = Item::with(['category', 'unitPrice', 'unitCost'])
    ->where('status', 'active')
    ->get()
    ->map(fn($item) => [
        'item_identifier'  => $item->identifier,
        'item_sku'         => $item->identification,
        'name'             => $item->name,
        'description'      => $item->description,
        'category'         => $item->category?->name,
        'category_type'    => $this->mapCategoryType($item->category),
        'type'             => $item->type,
        'unit_price_cents' => $item->unitPrice
            ? (int) ($item->unitPrice->amount * 100)
            : 0,
        'unit_cost_cents'  => $item->unitCost
            ? (int) ($item->unitCost->amount * 100)
            : 0,
        'status' => $item->status === 'active' ? 'active' : 'inactive',
    ])->toArray();

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:

{
  "data": {
    "type": "categories",
    "attributes": {
      "branch_identifier": "b1c2d3e4-f5a6-7890-abcd-ef1234567890",
      "categories": [
        {
          "identifier": "uuid-categoria-bakery-001",
          "name": "BOLLITOS",
          "parent_identifier": null,
          "sequence": 1
        },
        {
          "identifier": "uuid-subcategoria-bakery-002",
          "name": "Bollitos Especiales",
          "parent_identifier": "uuid-categoria-bakery-001",
          "sequence": 2
        }
      ]
    }
  }
}

Campos por categoría:

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

Response exitoso 200 OK:

{
  "data": {
    "type": "categories-ingest",
    "attributes": {
      "created": 2,
      "updated": 0,
      "categories": [
        {
          "identifier": "uuid-categoria-bakery-001",
          "rc_express_id": 5,
          "name": "BOLLITOS"
        },
        {
          "identifier": "uuid-subcategoria-bakery-002",
          "rc_express_id": 6,
          "name": "Bollitos Especiales"
        }
      ]
    }
  }
}

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:

// En CatalogSyncService.php — método pushCategoriesToRCExpress()
$categories = FinishedGoodsCategory::where('group_id', $branch->group_id)
    ->orderBy('parent_id')  // raíces primero, hijos después
    ->get()
    ->map(fn($cat) => [
        'identifier'        => $cat->identifier,
        'name'              => $cat->name,
        'parent_identifier' => $cat->parent?->identifier,
        'sequence'          => $cat->sequence ?? 0,
    ])->toArray();

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

{
  "data": {
    "type": "discounts",
    "attributes": {
      "branch_identifier": "b1c2d3e4-f5a6-7890-abcd-ef1234567890",
      "date": "2026-05-15",
      "closing_type": "zout",
      "discounts": [
        {
          "item_identifier": "550e8400-e29b-41d4-a716-446655440001",
          "item_sku": "010501",
          "item_name": "BOLLO ALEMÁN",
          "quantity": 1,
          "amount_cents": 500,
          "reason": "Cortesía del chef",
          "authorized_by": "Marco Olivas",
          "discounted_at": "2026-05-15T20:30:00-07:00"
        }
      ]
    }
  }
}

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

{
  "data": {
    "type": "cancellations",
    "attributes": {
      "branch_identifier": "b1c2d3e4-f5a6-7890-abcd-ef1234567890",
      "date": "2026-05-15",
      "closing_type": "zout",
      "cancellations": [
        {
          "item_identifier": "550e8400-e29b-41d4-a716-446655440001",
          "item_sku": "010501",
          "item_name": "BOLLO ALEMÁN",
          "quantity": 1,
          "amount_cents": 2800,
          "reason": "Error de captura",
          "cancelled_by": "Ana García",
          "authorized_by": "Marco Olivas",
          "cancelled_at": "2026-05-15T20:35:00-07:00"
        }
      ]
    }
  }
}

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

6. Flujo completo de integración

6.1 Flujo diario (restaurant_controller)

AL INICIAR LA INTEGRACIÓN
──────────────────────────
0a. POST /api/v1/ingest/categories     ← categorías Bakery Pro (si aplica)
0b. POST /api/v1/ingest/catalog        ← catálogo completo de platillos

DURANTE EL SERVICIO
─────────────────────
- GET /api/v1/live/sales/today         ← ventas del turno en tiempo real
- GET /api/v1/live/alerts/active       ← alertas del turno

AL CERRAR EL CORTE Z
─────────────────────
1. POST /api/v1/ingest/orders
2. POST /api/v1/ingest/discounts
3. POST /api/v1/ingest/cancellations
4. POST /api/v1/ingest/payments
5. POST /api/v1/ingest/sales
6. POST /api/v1/ingest/cash-register   ← dispara procesamiento → webhook snapshot.completed

AL DÍA SIGUIENTE
─────────────────
- GET /api/v1/intelligence/pnl
- GET /api/v1/intelligence/kpis
- GET /api/v1/intelligence/alerts

6.2 Snippet PHP completo

<?php

namespace App\Services;

use App\Models\CashRegisterOpening;
use Illuminate\Support\Facades\Http;
use Illuminate\Support\Facades\Log;

class RestauranteroProService
{
    private string $baseUrl;
    private string $apiKey;
    private string $branchIdentifier;

    public function __construct()
    {
        $this->baseUrl          = config('restaurantero.base_url', 'https://my.restauranteropro.com/api/v1');
        $this->apiKey           = config('restaurantero.api_key');
        $this->branchIdentifier = config('restaurantero.branch_identifier');
    }

    public function sendZOut(CashRegisterOpening $closing): void
    {
        $closingId = $closing->identifier;

        $this->post('/ingest/orders',        $this->buildOrdersPayload($closing),       $closingId . '-orders');
        $this->post('/ingest/discounts',     $this->buildDiscountsPayload($closing),    $closingId . '-discounts');
        $this->post('/ingest/cancellations', $this->buildCancellationsPayload($closing),$closingId . '-cancellations');
        $this->post('/ingest/payments',      $this->buildPaymentsPayload($closing),     $closingId . '-payments');
        $this->post('/ingest/sales',         $this->buildSalesPayload($closing),        $closingId . '-sales');
        $this->post('/ingest/cash-register', $this->buildCashRegisterPayload($closing), $closingId);
    }

    public function sendCatalog(array $items): void
    {
        $this->post('/ingest/catalog', [
            'data' => [
                'type' => 'catalog',
                'attributes' => [
                    'branch_identifier' => $this->branchIdentifier,
                    'items' => $items,
                ],
                'meta' => [
                    'pos_name' => 'restaurant_controller',
                    'sent_at'  => now()->toIso8601String(),
                ],
            ],
        ], 'catalog-' . now()->format('Y-m-d'));
    }

    public function sendCategories(array $categories): array
    {
        // Devuelve el response con rc_express_id por categoría
        return $this->postWithResponse('/ingest/categories', [
            'data' => [
                'type' => 'categories',
                'attributes' => [
                    'branch_identifier' => $this->branchIdentifier,
                    'categories'        => $categories,
                ],
            ],
        ], 'categories-' . now()->format('Y-m-d'));
    }

    private function post(string $endpoint, array $payload, string $idempotencyKey): void
    {
        $attempts = 0;
        $delays   = [0, 5, 30];

        while ($attempts < 3) {
            try {
                $response = Http::withHeaders([
                    'X-API-Key'         => $this->apiKey,
                    'X-Idempotency-Key' => $idempotencyKey,
                    'Content-Type'      => 'application/json',
                ])->timeout(15)->post($this->baseUrl . $endpoint, $payload);

                if ($response->successful()) {
                    Log::info("RestauranteroProService: {$endpoint} OK");
                    return;
                }

                Log::warning("RestauranteroProService: {$endpoint} falló", [
                    'status' => $response->status(),
                    'body'   => $response->body(),
                ]);
            } catch (\Exception $e) {
                Log::error("RestauranteroProService: {$endpoint} excepción", ['error' => $e->getMessage()]);
            }

            $attempts++;
            if ($attempts < 3) sleep($delays[$attempts]);
        }
    }
}

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

8. Módulo Live — Datos en tiempo real

Estos endpoints devuelven el estado actual del turno, no datos históricos. Se referenciaban en el flujo de integración (sección 6.1) pero no estaban documentados — corregido en esta versión.

8.1 Ventas del turno en curso

GET /api/v1/live/sales/today

Response:

{
  "data": {
    "type": "live_sales",
    "attributes": {
      "as_of": "2026-07-26T21:30:00-07:00",
      "date": "2026-07-26",
      "sales_so_far_cents": 526000,
      "covers_so_far": 8,
      "avg_ticket_cents": 65750,
      "vs_same_day_last_week": {
        "sales_pct_change": 8.3,
        "covers_pct_change": 5.1
      },
      "data_available": true
    }
  }
}

La comparación es siempre contra el mismo día de la semana anterior (ej. martes vs. martes pasado), nunca contra “ayer” — evita comparar un fin de semana contra un día entre semana.

8.2 Saldo de caja en tiempo real

GET /api/v1/live/cash/balance

Response:

{
  "data": {
    "type": "live_cash",
    "attributes": {
      "as_of": "2026-07-26T21:30:00-07:00",
      "cash_sales_cents": 78500,
      "tips_paid_cents": 12000,
      "withholding_cents": 4000,
      "expected_balance_cents": 62500,
      "variance_cents": 0,
      "variance_pct": 0.0,
      "status": "green",
      "data_available": true
    }
  }
}

Este endpoint no reemplaza el Corte Z — es una estimación en tiempo real basada en ventas registradas hasta el momento, no un arqueo físico.

8.3 Alertas del turno activo

GET /api/v1/live/alerts/active

Response:

{
  "data": {
    "type": "live_alerts",
    "attributes": {
      "alerts": [
        {
          "severity": "yellow",
          "type": "cash_variance_live",
          "message": "Varianza en caja de hoy: $450.00 MXN",
          "triggered_at": "2026-07-26T20:45:00-07:00"
        }
      ]
    }
  }
}

8.4 Eventos de mesa en tiempo real — `POST /api/v1/live/update`

Endpoint opcional. Actívalo cuando quieras alimentar la vista “En vivo” del salón (mesas abiertas, qué llevan pedido, cuánto tiempo llevan) en el dashboard del dueño.

Body del request:

{
  "table_number": "5",
  "event": "item_added",
  "waiter_name": "Ana García",
  "covers": 4,
  "items": [
    {
      "item_name": "Aguachile Mar y Tierra",
      "quantity": 2,
      "unit_price_cents": 57000,
      "ordered_at": "2026-07-26T13:45:22-07:00"
    }
  ],
  "opened_at": "2026-07-26T12:22:00-07:00"
}

Campo	Tipo	Requerido	Descripción
`table_number`	string	✅ Sí	Número o identificador de la mesa
`event`	string	✅ Sí	`table_opened`, `item_added`, `item_removed` o `table_closed`
`waiter_name`	string	No	Mesero asignado
`covers`	integer	No	Comensales en la mesa
`items`	array	No	Ver advertencia abajo
`opened_at`	datetime ISO 8601	No	Hora de apertura (solo en `table_opened`)

items siempre debe llevar la lista COMPLETA y ACTUAL de productos de la mesa — nunca solo el cambio. Restaurantero Pro reemplaza la lista completa con cada evento, no calcula diferencias.

Response:

{
  "data": {
    "type": "live_table_update",
    "attributes": {
      "status": "ok",
      "table_number": "5",
      "event": "item_added"
    }
  }
}

10. Changelog

v1.0.5 — Julio 2026

Nueva Sección 8 — Módulo Live — documenta GET /live/sales/today, GET /live/cash/balance y GET /live/alerts/active, que ya estaban implementados y referenciados en el flujo de integración (6.1) pero nunca documentados con su forma de respuesta.
POST /api/v1/live/update — Nuevo endpoint opcional (sección 8.4) para eventos de mesa en tiempo real (apertura, productos, cierre). Alimenta la vista “En vivo” del dashboard.
Sección 3.1 (Corte de caja) — Agregados los tipos opcionales cash_theoretical y cash_actual al arreglo summaries, con la convención de signos documentada (cash_variance = cash_actual - cash_theoretical).
Sección 3.4 (Líneas de orden) — Aclarado que ordered_at es el campo oficial para la hora exacta del pedido (ya documentado desde antes, pero nunca llega poblado en producción) — no se agregó ningún campo nuevo para esto, evitando confundirlo con meta.sent_at (que tiene un significado distinto: hora de envío del payload completo).

v1.0.4 — Julio 2026

Sección 1 — Nueva sub-sección “Verificar conexión” — documenta GET /api/v1/ping, ausente hasta ahora en esta referencia aunque ya estaba en uso real por integradores.
Campo subscription_status agregado a la respuesta de /ping (active / suspended / blocked). Hoy informativo — todas las sucursales están en active, sin ningún cliente afectado. Documenta el comportamiento esperado del POS por cada valor.
integracion-rc.mdx — comando restaurantero:test actualizado para mostrar subscription_status en su tabla de verificación.

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.5
Desarrollado por Restaurant Controller · Hermosillo, Sonora, México
Julio 2026 · Confidencial — Solo para partners autorizados

Referencia

API de Integración v1.0.4

API de Integración — Restaurantero Pro

1. Autenticación

Errores de autenticación

Verificar conexión — `GET /api/v1/ping`

2. Convenciones generales

Formato de requests y responses

Dinero — siempre en centavos

Fechas y horas

Idempotencia — obligatoria en todos los POST de ingesta

3. Endpoints de Ingesta

Orden correcto al cerrar un Corte Z

3.1 Corte de caja — `POST /api/v1/ingest/cash-register`

3.2 Ventas — `POST /api/v1/ingest/sales`

3.3 Pagos por método — `POST /api/v1/ingest/payments`

3.4 Líneas de orden — `POST /api/v1/ingest/orders`

3.5 Catálogo de platillos — `POST /api/v1/ingest/catalog`

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

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

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

4. Catálogo de errores

5. Checklist de integración

6. Flujo completo de integración

6.1 Flujo diario (restaurant_controller)

6.2 Snippet PHP completo

7. Webhooks

8. Módulo Live — Datos en tiempo real

8.1 Ventas del turno en curso

8.2 Saldo de caja en tiempo real

8.3 Alertas del turno activo

8.4 Eventos de mesa en tiempo real — `POST /api/v1/live/update`

10. Changelog

v1.0.5 — Julio 2026

v1.0.4 — Julio 2026

v1.0.3 — Junio 2026

v1.0.2 — Mayo 2026

v1.0.1 — Mayo 2026

v1.0.0 — Mayo 2026

​API de Integración — Restaurantero Pro

​1. Autenticación

​Errores de autenticación

​Verificar conexión — GET /api/v1/ping

​2. Convenciones generales

​Formato de requests y responses

​Dinero — siempre en centavos

​Fechas y horas

​Idempotencia — obligatoria en todos los POST de ingesta

​3. Endpoints de Ingesta

​Orden correcto al cerrar un Corte Z

​3.1 Corte de caja — POST /api/v1/ingest/cash-register

​3.2 Ventas — POST /api/v1/ingest/sales

​3.3 Pagos por método — POST /api/v1/ingest/payments

​3.4 Líneas de orden — POST /api/v1/ingest/orders

​3.5 Catálogo de platillos — POST /api/v1/ingest/catalog

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

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

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

​4. Catálogo de errores

​5. Checklist de integración

​6. Flujo completo de integración

​6.1 Flujo diario (restaurant_controller)

​6.2 Snippet PHP completo

​7. Webhooks

​8. Módulo Live — Datos en tiempo real

​8.1 Ventas del turno en curso

​8.2 Saldo de caja en tiempo real

​8.3 Alertas del turno activo

​8.4 Eventos de mesa en tiempo real — POST /api/v1/live/update

​10. Changelog

​v1.0.5 — Julio 2026

​v1.0.4 — Julio 2026

​v1.0.3 — Junio 2026

​v1.0.2 — Mayo 2026

​v1.0.1 — Mayo 2026

​v1.0.0 — Mayo 2026

API de Integración — Restaurantero Pro

1. Autenticación

Errores de autenticación

Verificar conexión — `GET /api/v1/ping`

2. Convenciones generales

Formato de requests y responses

Dinero — siempre en centavos

Fechas y horas

Idempotencia — obligatoria en todos los POST de ingesta

3. Endpoints de Ingesta

Orden correcto al cerrar un Corte Z

3.1 Corte de caja — `POST /api/v1/ingest/cash-register`

3.2 Ventas — `POST /api/v1/ingest/sales`

3.3 Pagos por método — `POST /api/v1/ingest/payments`

3.4 Líneas de orden — `POST /api/v1/ingest/orders`

3.5 Catálogo de platillos — `POST /api/v1/ingest/catalog`

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

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

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

4. Catálogo de errores

5. Checklist de integración

6. Flujo completo de integración

6.1 Flujo diario (restaurant_controller)

6.2 Snippet PHP completo

7. Webhooks

8. Módulo Live — Datos en tiempo real

8.1 Ventas del turno en curso

8.2 Saldo de caja en tiempo real

8.3 Alertas del turno activo

8.4 Eventos de mesa en tiempo real — `POST /api/v1/live/update`

10. Changelog

v1.0.5 — Julio 2026

v1.0.4 — Julio 2026

v1.0.3 — Junio 2026

v1.0.2 — Mayo 2026

v1.0.1 — Mayo 2026

v1.0.0 — Mayo 2026