# Referencia de API

URL: https://theelena.me/docs/elena/api-reference
Text: https://theelena.me/docs/elena/api-reference.txt
Description: Endpoints de integración y catálogo público con sus contratos reales.
Context: environment=production; apiBaseUrl=https://api.theelena.me; appUrl=https://app.theelena.me

# Referencia de API

La fuente canónica de esquemas es el Swagger generado por el backend:
[https://api.theelena.me/docs](https://api.theelena.me/docs) (completa) y
[https://api.theelena.me/docs/integration](https://api.theelena.me/docs/integration)
(solo integración). Esta referencia resume los endpoints de las superficies
públicas.

## Convenciones

- Base: `https://api.theelena.me/api/v1`
- Integración: header `x-api-key` en cada request.
- Catálogo público: sin credencial; identificación por `slug`.
- `X-Visitor-Id`: identidad anónima del visitante en pedidos y tracking
  públicos; tiene prioridad sobre el `sessionId` del cuerpo.
- `idempotency-key`: opcional al crear pedidos públicos; hace tolerantes a
  reintentos la creación.

## API de integración

Autenticación por API Key. Requiere la capacidad `apiAccess` y suscripción
activa.

| Método | Ruta                                    | Descripción                                                                   |
| ------ | --------------------------------------- | ----------------------------------------------------------------------------- |
| GET    | `/integration/catalog/info`             | Información del restaurante: estado, horarios, métodos de pago, moneda, mesas |
| GET    | `/integration/catalog/menu`             | Catálogo completo (`categories` + `products`); acepta `?search=`              |
| POST   | `/integration/catalog/orders`           | Crea un pedido; devuelve `201` con la confirmación                            |
| GET    | `/integration/catalog/tables/available` | Mesas disponibles (requiere gestión de mesas activa)                          |
| GET    | `/integration/catalog/tables/:id`       | Detalle de una mesa por ID                                                    |

### Cuerpo de creación de pedido

| Campo                    | Tipo                                                                                               | Notas                                                                                       |
| ------------------------ | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| `tipo`                   | `para_llevar` \| `en_mesa` \| `reserva`                                                            | Obligatorio                                                                                 |
| `customer`               | `{ name, phone, whatsappOptIn }`                                                                   | Obligatorio en `para_llevar`                                                                |
| `tableNumber`            | string ≤ 10                                                                                        | `en_mesa` legacy sin gestión de mesas                                                       |
| `tableId`                | string                                                                                             | Mesa cuando `tableManagementActive` es `true`                                               |
| `reservation`            | `{ name, phone, arrivalDate, arrivalTime, peopleCount, preferredTable?, tableId?, whatsappOptIn }` | Obligatorio en `reserva`                                                                    |
| `generalNotes`           | string ≤ 500                                                                                       | Opcional                                                                                    |
| `preferredPaymentMethod` | string ≤ 50                                                                                        | Debe existir en los métodos del negocio                                                     |
| `receipt`                | `{ type, documentType?, documentNumber?, businessName?, address? }`                                | `type`: `none`, `simple`, `boleta_sunat`, `factura_sunat`                                   |
| `items`                  | 1–50 ítems                                                                                         | `productId`, `cantidad` (1–100), `unitPrice` decimal como texto, `specialNotes?`, `extras?` |
| `extras[]`               | `{ groupName, optionName, additionalPrice }`                                                       | Tomados de los grupos de personalización del menú                                           |

## Catálogo público

Sin autenticación. Límites de tasa por IP y por visitante; ante 429 respeta el
header `Retry-After`.

| Método | Ruta                                                           | Descripción                                                                |
| ------ | -------------------------------------------------------------- | -------------------------------------------------------------------------- |
| GET    | `/public/catalog/:slug`                                        | Información pública del restaurante con estado de apertura                 |
| GET    | `/public/catalog/:slug/menu`                                   | Menú completo; acepta `?search=`                                           |
| POST   | `/public/catalog/:slug/orders`                                 | Crea un pedido público (mismo cuerpo que integración + `sessionId` legacy) |
| GET    | `/public/catalog/:slug/access/:publicKey`                      | Resuelve un punto de acceso (QR físico)                                    |
| POST   | `/public/catalog/:slug/access/:publicKey/orders`               | Crea un pedido desde un punto de acceso                                    |
| GET    | `/public/catalog/:slug/tracking/:trackingToken`                | Estado en vivo de un pedido por token de tracking                          |
| GET    | `/public/catalog/:slug/sales/:receiptToken`                    | Consulta de venta por token de recibo                                      |
| GET    | `/public/catalog/:slug/sales/:receiptToken/pdf`                | Recibo en PDF                                                              |
| POST   | `/public/catalog/:slug/tracking/:trackingToken/payment-claims` | Reporta un pago (ej. Yape) sobre un pedido                                 |
| GET    | `/public/catalog/:slug/orders/:orderId`                        | Pedido visible solo para su visitante (`X-Visitor-Id`)                     |
| POST   | `/public/catalog/:slug/live-session`                           | Reporta actividad del navegador para la vista en vivo del staff            |

## Salud

| Método | Ruta | Descripción                                        |
| ------ | ---- | -------------------------------------------------- |
| GET    | `/`  | Estado del backend: `{ message, version, status }` |