# MAURICIO POS & Foodtech API

> Mauricio es la plataforma tecnológica integral para restaurantes en México, proporcionando APIs RESTful para reservaciones públicas, catálogo POS de productos, menús digitales, sincronización Foodtech y hardware de impresión Edge.

## Guías e Integración Rápida
- [OpenAPI 3.0 Specification](https://mau.rest/api/v1/openapi.json): Especificación machine-readable completa en formato JSON.
- [API Reference (Scalar UI)](https://mau.rest/developers/api-reference): Consola interactiva para probar endpoints en tiempo real.
- [Guía de Autenticación & Errores](https://mau.rest/developers/docs): Las peticiones protegidas requieren la cabecera `X-API-Key`.
- [Documentación Completa (llms-full.txt)](https://mau.rest/llms-full.txt): Versión exhaustiva concatenada de toda la API en texto plano.

## Módulos de la API

### 1. Public Booking API
- [POST /api/v1/public/booking/available-slots](https://mau.rest/developers/api-reference): Consulta de disponibilidad de mesas por fecha y número de personas.
- [POST /api/v1/public/booking/create](https://mau.rest/developers/api-reference): Registro y confirmación directa de reservación.
- [GET /api/v1/public/booking/restaurant-info](https://mau.rest/developers/api-reference): Datos públicos y políticas de la sucursal.

### 2. POS & Catalog API
- [GET /api/v1/pos/menus](https://mau.rest/developers/api-reference): Catálogo de menús digitales y categorías.
- [GET /api/v1/pos/products](https://mau.rest/developers/api-reference): Productos, precios, modificadores y estado de stock.
- [GET /api/v1/pos/reservations](https://mau.rest/developers/api-reference): Reservaciones vinculadas al punto de venta.
- [GET /api/v1/pos/schedules](https://mau.rest/developers/api-reference): Horarios operativos y turnos.
- [GET /api/v1/pos/stations](https://mau.rest/developers/api-reference): Estaciones de comanda (Cocina, Barra).

### 3. Foodtech Integrations API
- [GET /api/v1/foodtech/menus](https://mau.rest/developers/api-reference): Carta formateada para agregadores (Rappi / UberEats).
- [GET /api/v1/foodtech/photos](https://mau.rest/developers/api-reference): Galería de imágenes y assets visuales.

### 4. Hardware Print Bridge API (Edge)
- [POST /api/print-bridge/v1/register](https://mau.rest/developers/api-reference): Enrolamiento y re-autenticación de agente Raspberry Pi.
- [POST /api/print-bridge/v1/heartbeat](https://mau.rest/developers/api-reference): Telemetría y estado de impresoras térmicas.
- [POST /api/print-bridge/v1/jobs/claim](https://mau.rest/developers/api-reference): Sondeo de comandas locales ESC/POS.

## Ejemplo de Código (Python Client)
```python
import requests

def get_available_slots(restaurant_slug, date, party_size):
    url = "https://mau.rest/api/v1/public/booking/available-slots"
    payload = {
        "restaurant_slug": restaurant_slug,
        "date": date,
        "party_size": party_size
    }
    response = requests.post(url, json=payload)
    return response.json()
```


===============================================================================
ESPECIFICACIÓN COMPLETA OPENAPI 3.0.3 (JSON CONCATENADO)
===============================================================================

{
  "openapi": "3.0.3",
  "info": {
    "title": "MAURICIO POS & Foodtech API",
    "description": "API RESTful de alta velocidad para la gestión completa de restaurantes: reservaciones públicas, catálogo de productos, menús digitales, sincronización Foodtech y hardware de impresión local Edge.",
    "version": "1.0.0",
    "contact": {
      "name": "MAURICIO Developer Support",
      "url": "https://mau.rest/developers",
      "email": "devs@mau.rest"
    }
  },
  "servers": [
    {
      "url": "https://mau.rest",
      "description": "Servidor de Producción (GCP App Engine)"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    }
  ],
  "tags": [
    {
      "name": "Public Booking API",
      "description": "Endpoints públicos para reservaciones y consulta de horarios en tiempo real."
    },
    {
      "name": "POS & Catalog API",
      "description": "Catálogo de productos, categorías, menús y estado del punto de venta."
    },
    {
      "name": "Foodtech Integrations API",
      "description": "Exportación de menús y assets fotográficos para agregadores de comida (Rappi, UberEats)."
    },
    {
      "name": "Hardware Print Bridge API",
      "description": "Gestión de cola de impresión local ESC/POS, telemetría y agentes Raspberry Pi."
    }
  ],
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key",
        "description": "Clave de API para autenticación de integradores y aplicaciones autorizadas."
      },
      "BridgeBearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Token Bearer asignado al dispositivo Print Bridge local."
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "example": "INVALID_PARAMETERS"
              },
              "message": {
                "type": "string",
                "example": "El parámetro 'restaurant_slug' es requerido."
              },
              "timestamp": {
                "type": "string",
                "example": "2026-09-16T13:00:00Z"
              }
            }
          }
        }
      },
      "AvailableSlotsRequest": {
        "type": "object",
        "required": [
          "restaurant_slug",
          "date",
          "party_size"
        ],
        "properties": {
          "restaurant_slug": {
            "type": "string",
            "example": "petit-gateau",
            "description": "Identificador único de la sucursal."
          },
          "date": {
            "type": "string",
            "format": "date",
            "example": "2026-09-20",
            "description": "Fecha de reservación en formato YYYY-MM-DD."
          },
          "party_size": {
            "type": "integer",
            "example": 4,
            "description": "Número de personas para la reservación."
          }
        }
      },
      "BookingCreateRequest": {
        "type": "object",
        "required": [
          "restaurant_slug",
          "date",
          "time",
          "party_size",
          "customer_name",
          "customer_email",
          "customer_phone"
        ],
        "properties": {
          "restaurant_slug": {
            "type": "string",
            "example": "petit-gateau"
          },
          "date": {
            "type": "string",
            "format": "date",
            "example": "2026-09-20"
          },
          "time": {
            "type": "string",
            "example": "14:30"
          },
          "party_size": {
            "type": "integer",
            "example": 4
          },
          "customer_name": {
            "type": "string",
            "example": "Valeria Gómez"
          },
          "customer_email": {
            "type": "string",
            "format": "email",
            "example": "valeria@example.com"
          },
          "customer_phone": {
            "type": "string",
            "example": "+525512345678"
          },
          "notes": {
            "type": "string",
            "example": "Mesa cerca de la ventana por favor."
          }
        }
      },
      "PrintBridgeRegisterRequest": {
        "type": "object",
        "required": [
          "device_code",
          "restaurant_slug"
        ],
        "properties": {
          "device_code": {
            "type": "string",
            "example": "pi-petit-gateau-01"
          },
          "restaurant_slug": {
            "type": "string",
            "example": "petit-gateau"
          },
          "hostname": {
            "type": "string",
            "example": "raspberrypi-kitchen"
          },
          "operating_system": {
            "type": "string",
            "example": "Linux 6.1 (Raspberry Pi OS)"
          },
          "app_version": {
            "type": "string",
            "example": "1.4.2"
          },
          "setup_token": {
            "type": "string",
            "example": "st_98a72b102c"
          }
        }
      },
      "PrintBridgeHeartbeatRequest": {
        "type": "object",
        "properties": {
          "local_ip": {
            "type": "string",
            "example": "192.168.1.150"
          },
          "cpu_temp": {
            "type": "number",
            "example": 42.5
          },
          "wifi_rssi": {
            "type": "integer",
            "example": -62
          },
          "printers": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "printer_id": {
                  "type": "string",
                  "example": "550e8400-e29b-41d4-a716-446655440000"
                },
                "reachable": {
                  "type": "boolean",
                  "example": true
                },
                "last_error": {
                  "type": "string",
                  "example": null
                }
              }
            }
          }
        }
      }
    }
  },
  "paths": {
    "/api/v1/public/booking/available-slots": {
      "post": {
        "summary": "Consultar Horarios Disponibles",
        "description": "Verifica en tiempo real la disponibilidad de reservación para una fecha y tamaño de grupo.",
        "tags": [
          "Public Booking API"
        ],
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AvailableSlotsRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Lista de slots de reservación disponibles.",
            "content": {
              "application/json": {
                "example": {
                  "status": "success",
                  "restaurant_name": "Petit Gateau",
                  "date": "2026-09-20",
                  "party_size": 4,
                  "available_slots": [
                    "13:00",
                    "13:30",
                    "14:30",
                    "18:00",
                    "19:30"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Parámetros de consulta requeridos faltantes o formato de fecha inválido.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/public/booking/create": {
      "post": {
        "summary": "Crear Reservación Pública",
        "description": "Registra una nueva reservación confirmada en el POS para un cliente final.",
        "tags": [
          "Public Booking API"
        ],
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BookingCreateRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Reservación confirmada exitosamente.",
            "content": {
              "application/json": {
                "example": {
                  "status": "confirmed",
                  "booking_id": "8f3d1b22-9c44-482a-b101-77b5a8e1009a",
                  "confirmation_code": "PG-9821",
                  "message": "Reservación confirmada exitosamente."
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/public/booking/restaurant-info": {
      "get": {
        "summary": "Obtener Información Pública de Sucursal",
        "description": "Retorna datos generales, dirección, teléfono y políticas de reservación de una sucursal.",
        "tags": [
          "Public Booking API"
        ],
        "security": [],
        "parameters": [
          {
            "name": "restaurant_slug",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "petit-gateau"
          }
        ],
        "responses": {
          "200": {
            "description": "Información pública de la sucursal.",
            "content": {
              "application/json": {
                "example": {
                  "id": "restaurant-uuid",
                  "name": "Petit Gateau Cafe",
                  "slug": "petit-gateau",
                  "address": "Mercado Carmen, San Ángel, CDMX",
                  "phone": "+525512345678",
                  "max_party_size": 8,
                  "booking_advance_days": 30
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/pos/menus": {
      "get": {
        "summary": "Obtener Menús Digitales",
        "description": "Retorna las categorías y catálogo de productos activos de una sucursal.",
        "tags": [
          "POS & Catalog API"
        ],
        "parameters": [
          {
            "name": "restaurant_slug",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "petit-gateau"
          }
        ],
        "responses": {
          "200": {
            "description": "Estructura de catálogo y precios.",
            "content": {
              "application/json": {
                "example": {
                  "categories": [
                    {
                      "id": "cat-1",
                      "name": "Postres de Autor",
                      "products": [
                        {
                          "id": "prod-101",
                          "name": "Esfera de Chocolate",
                          "price": 145.0,
                          "available": true
                        }
                      ]
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/pos/products": {
      "get": {
        "summary": "Obtener Catálogo General de Productos",
        "description": "Lista detallada de productos, modificadores, impuestos y disponibilidad de inventario.",
        "tags": [
          "POS & Catalog API"
        ],
        "parameters": [
          {
            "name": "restaurant_slug",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "petit-gateau"
          },
          {
            "name": "category_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "cat-1"
          }
        ],
        "responses": {
          "200": {
            "description": "Lista de productos y precios.",
            "content": {
              "application/json": {
                "example": {
                  "products": [
                    {
                      "id": "prod-101",
                      "name": "Tartaleta de Limón",
                      "price": 120.0,
                      "sku": "TL-01",
                      "in_stock": true
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/pos/reservations": {
      "get": {
        "summary": "Listar Reservaciones en el POS",
        "description": "Obtiene la lista de reservaciones asignadas a mesas para el punto de venta.",
        "tags": [
          "POS & Catalog API"
        ],
        "parameters": [
          {
            "name": "restaurant_slug",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "petit-gateau"
          },
          {
            "name": "date",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date"
            },
            "example": "2026-09-16"
          }
        ],
        "responses": {
          "200": {
            "description": "Reservaciones asociadas al turno.",
            "content": {
              "application/json": {
                "example": {
                  "reservations": [
                    {
                      "id": "res-1",
                      "customer_name": "Carlos Ruiz",
                      "party_size": 2,
                      "time": "15:00",
                      "table_number": "Mesa 4",
                      "status": "CONFIRMED"
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/pos/schedules": {
      "get": {
        "summary": "Obtener Horarios Operativos de Sucursal",
        "description": "Retorna los horarios de apertura, cierre y turnos especiales.",
        "tags": [
          "POS & Catalog API"
        ],
        "parameters": [
          {
            "name": "restaurant_slug",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "petit-gateau"
          }
        ],
        "responses": {
          "200": {
            "description": "Horarios por día de la semana.",
            "content": {
              "application/json": {
                "example": {
                  "schedules": [
                    {
                      "day_of_week": "Monday",
                      "open_time": "09:00",
                      "close_time": "21:00",
                      "is_open": true
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/pos/stations": {
      "get": {
        "summary": "Obtener Estaciones de Producción (Cocina / Barra)",
        "description": "Retorna las estaciones de comanda configuradas para la sucursal.",
        "tags": [
          "POS & Catalog API"
        ],
        "parameters": [
          {
            "name": "restaurant_slug",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "petit-gateau"
          }
        ],
        "responses": {
          "200": {
            "description": "Estaciones de preparación activas.",
            "content": {
              "application/json": {
                "example": {
                  "stations": [
                    {
                      "id": "st-1",
                      "name": "Cocina Caliente",
                      "code": "cocina-caliente"
                    },
                    {
                      "id": "st-2",
                      "name": "Barra de Bebidas",
                      "code": "barra"
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/foodtech/menus": {
      "get": {
        "summary": "Exportar Menús para Foodtech (Rappi / UberEats)",
        "description": "Exporta la carta formateada de acuerdo a especificaciones de agregadores.",
        "tags": [
          "Foodtech Integrations API"
        ],
        "parameters": [
          {
            "name": "restaurant_slug",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "petit-gateau"
          }
        ],
        "responses": {
          "200": {
            "description": "Menú estructurado para Foodtech.",
            "content": {
              "application/json": {
                "example": {
                  "brand": "Petit Gateau",
                  "items": [
                    {
                      "external_id": "prod-101",
                      "title": "Esfera de Chocolate",
                      "price": 145.0
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/foodtech/photos": {
      "get": {
        "summary": "Catálogo de Fotografías de Platillos",
        "description": "Obtiene la lista de assets visuales optimizados para menús digitales y delivery.",
        "tags": [
          "Foodtech Integrations API"
        ],
        "parameters": [
          {
            "name": "restaurant_slug",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "petit-gateau"
          }
        ],
        "responses": {
          "200": {
            "description": "Galería de imágenes por producto.",
            "content": {
              "application/json": {
                "example": {
                  "photos": [
                    {
                      "product_id": "prod-101",
                      "url": "https://storage.googleapis.com/mauricio-assets/esfera.jpg"
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/print-bridge/v1/register": {
      "post": {
        "summary": "Enrolar / Registrar Print Bridge",
        "description": "Registra un nuevo agente local (Raspberry Pi / Servidor Edge) en la nube mediante setup token o re-autenticación Bearer.",
        "tags": [
          "Hardware Print Bridge API"
        ],
        "security": [
          {
            "BridgeBearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PrintBridgeRegisterRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Bridge enrolado exitosamente.",
            "content": {
              "application/json": {
                "example": {
                  "success": true,
                  "bridge_id": "8f3d1b22-9c44-482a-b101-77b5a8e1009a",
                  "access_token": "pbt_77a102bc99d12348"
                }
              }
            }
          },
          "401": {
            "description": "Setup token o token Bearer no autorizado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/print-bridge/v1/heartbeat": {
      "post": {
        "summary": "Latido de Telemetría (Heartbeat)",
        "description": "Notificación periódica del estado de salud del agente local, CPU, IP y alcance de impresoras térmicas.",
        "tags": [
          "Hardware Print Bridge API"
        ],
        "security": [
          {
            "BridgeBearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PrintBridgeHeartbeatRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Latido registrado exitosamente.",
            "content": {
              "application/json": {
                "example": {
                  "success": true,
                  "status": "ONLINE"
                }
              }
            }
          }
        }
      }
    },
    "/api/print-bridge/v1/jobs/claim": {
      "post": {
        "summary": "Reclamar Trabajos de Impresión Pendientes",
        "description": "Sondeo de cola de impresión (FOR UPDATE SKIP LOCKED) para obtener comandas en formato ESC/POS.",
        "tags": [
          "Hardware Print Bridge API"
        ],
        "security": [
          {
            "BridgeBearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Trabajo de impresión asignado o nulo si la cola está vacía.",
            "content": {
              "application/json": {
                "example": {
                  "success": true,
                  "job": {
                    "id": "job-uuid-101",
                    "job_id": "job-uuid-101",
                    "gateway_id": "pi-petit-01",
                    "area": "printing",
                    "device_id": "cocina-caliente",
                    "action": "print",
                    "document_type": "TICKET",
                    "printer_host": "192.168.1.200",
                    "printer_port": 9100,
                    "payload": {
                      "items": [
                        {
                          "name": "Esfera de Chocolate",
                          "qty": 2
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/print-bridge/v1/jobs/{job_id}/printed": {
      "post": {
        "summary": "Confirmar Impresión Exitosa",
        "description": "Notifica al servidor que el ticket fue enviado a la impresora térmica con éxito.",
        "tags": [
          "Hardware Print Bridge API"
        ],
        "security": [
          {
            "BridgeBearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "job_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "job-uuid-101"
          }
        ],
        "responses": {
          "200": {
            "description": "Estado actualizado a PRINTED.",
            "content": {
              "application/json": {
                "example": {
                  "success": true,
                  "status": "PRINTED"
                }
              }
            }
          }
        }
      }
    },
    "/api/print-bridge/v1/jobs/{job_id}/failed": {
      "post": {
        "summary": "Reportar Fallo de Impresión",
        "description": "Informa de un error de transmisión de hardware (papel atascado, sin conexión a red).",
        "tags": [
          "Hardware Print Bridge API"
        ],
        "security": [
          {
            "BridgeBearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "job_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "job-uuid-101"
          }
        ],
        "responses": {
          "200": {
            "description": "Fallo registrado e incremento de contador de reintentos.",
            "content": {
              "application/json": {
                "example": {
                  "success": true,
                  "status": "FAILED_RETRYABLE"
                }
              }
            }
          }
        }
      }
    }
  }
}