# Integración

URL: https://theelena.me/docs/elena/integration
Text: https://theelena.me/docs/elena/integration.txt
Description: Lee catálogo, consulta mesas y crea pedidos con la API de integración de Elena.
Context: environment=production; apiBaseUrl=https://api.theelena.me; appUrl=https://app.theelena.me

# Integración

La API de integración es el contrato server-to-server de Elena para sistemas
externos: lecturas de catálogo, consulta de mesas y creación de pedidos.
Todo vive bajo un prefijo y se autentica con tu API Key:

```txt
https://api.theelena.me/api/v1/integration/catalog
```

```http
x-api-key: tu_api_key_de_elena
```

El `restaurantId` se resuelve desde la metadata de la clave. Nunca lo envíes
en la URL ni en el cuerpo. Si el plan del restaurante no incluye la capacidad
`apiAccess`, la API responde 403 aunque la clave sea válida.

## Flujo recomendado

### 1. Verifica el negocio

```sh
curl "https://api.theelena.me/api/v1/integration/catalog/info" \
  -H "x-api-key: $ELENA_API_KEY"
```

La respuesta incluye nombre, estado de apertura (`isOpen`, `nextOpeningTime`),
horarios, métodos de pago con sus detalles (Yape, Plin, transferencia, QR),
moneda y si la gestión de mesas está activa (`tableManagementActive`).
Verifica `isOpen` antes de ofrecer pedidos.

### 2. Lee el catálogo

```sh
curl "https://api.theelena.me/api/v1/integration/catalog/menu" \
  -H "x-api-key: $ELENA_API_KEY"
```

Devuelve `categories` y `products`. Cada producto trae `basePrice` (texto
decimal), `available`, tipo `menu` o `inventario` y sus grupos de
personalización con opciones y precios adicionales. Acepta `?search=<término>`
(2 a 100 caracteres) para filtrar.

Usa los `id` reales de esta respuesta en los pedidos; no inventes
identificadores.

### 3. Consulta mesas (solo con gestión de mesas activa)

```sh
curl "https://api.theelena.me/api/v1/integration/catalog/tables/available" \
  -H "x-api-key: $ELENA_API_KEY"
```

Si `tableManagementActive` es `false`, estos endpoints fallan: omite la
selección de mesa en tu flujo. Con mesas activas, `GET
/integration/catalog/tables/:id` devuelve el detalle de una mesa específica
(útil para validar un QR o una mesa elegida).

### 4. Crea el pedido

```sh
curl -X POST "https://api.theelena.me/api/v1/integration/catalog/orders" \
  -H "x-api-key: $ELENA_API_KEY" \
  -H "content-type: application/json" \
  -d @pedido.json
```

Cuerpo mínimo para un pedido para llevar:

```json
{
  "tipo": "para_llevar",
  "preferredPaymentMethod": "yape",
  "customer": {
    "name": "María Quispe",
    "phone": "999888777",
    "whatsappOptIn": true
  },
  "items": [{ "productId": "<id real>", "cantidad": 2, "unitPrice": "14.00" }]
}
```

Reglas del cuerpo:

| Campo                     | Uso                                                                                         |
| ------------------------- | ------------------------------------------------------------------------------------------- |
| `tipo`                    | `para_llevar`, `en_mesa` o `reserva`                                                        |
| `customer`                | Requerido para `para_llevar`: nombre, teléfono y `whatsappOptIn`                            |
| `tableId` / `tableNumber` | Para `en_mesa`; usa `tableId` cuando la gestión de mesas está activa                        |
| `reservation`             | Para `reserva`: nombre, teléfono, fecha y hora de llegada, personas y `whatsappOptIn`       |
| `items`                   | 1 a 50 ítems con `productId`, `cantidad` (1-100) y `unitPrice` decimal como texto           |
| `extras`                  | Por ítem: `groupName`, `optionName` y `additionalPrice` tomados del menú                    |
| `preferredPaymentMethod`  | Método elegido de los que publica `info`                                                    |
| `receipt`                 | Opcional: comprobante `none`, `simple`, `boleta_sunat` o `factura_sunat` con datos fiscales |
| `generalNotes`            | Notas libres (máximo 500 caracteres)                                                        |

Una respuesta `201` confirma el pedido con el mismo contrato que usa la carta
pública; el pedido aparece en el panel del restaurante listo para su flujo de
cocina y cobro.

## Buenas prácticas

- guarda la API Key en un gestor de secretos y rotala periódicamente;
- verifica `isOpen` y `available` antes de mostrar o enviar productos;
- usa los precios del menú como texto decimal sin reformatarlos;
- maneja 400 (validación), 401 (clave), 403 (capacidad/plan) y 404 (restaurante);
- ante dudas de esquema, consulta el Swagger de integración en
  [https://api.theelena.me/docs/integration](https://api.theelena.me/docs/integration),
  que se genera del código vigente.