# API de Integracion de Serenatas

Esta API permite que un agente externo, n8n, Chatwoot o una IA registre y consulte serenatas usando un token personal de un usuario del panel propietario.

## Modelo de acceso

- La autenticacion es por token personal de usuario.
- Cada token pertenece a un usuario especifico.
- El token hereda los permisos y grupos mariachi accesibles de ese usuario.
- Si el usuario pierde permisos o se desactiva, el token deja de servir.
- Si un token se filtra, se puede revocar sin afectar a otros usuarios.

## Quien puede tener token

Usuarios del panel propietario:

- `CLIENT`
- `OWNER_STAFF`

El usuario debe:

- estar activo
- tener organizacion asignada
- tener los permisos necesarios para la accion

## Crear un token

Hoy el token se crea por consola, no desde la interfaz web.

Comando:

```bash
php artisan api-token:issue usuario@correo.com "n8n chatwoot"
```

Tambien puedes usar el ID del usuario:

```bash
php artisan api-token:issue 25 "n8n chatwoot"
```

Salida esperada:

```text
Token creado correctamente.
token_id: 7
user: usuario@correo.com
name: n8n chatwoot
secret: 7|xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

Importante:

- El valor de `secret` se muestra una sola vez.
- Ese valor completo es el que debe guardar la integracion.
- No se debe enviar por chats abiertos ni guardarlo en texto plano en sitios inseguros.

## Listar tokens de un usuario

```bash
php artisan api-token:list usuario@correo.com
```

## Revocar un token

```bash
php artisan api-token:revoke 7
```

## Autenticacion HTTP

Enviar siempre:

```http
Authorization: Bearer 7|xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Accept: application/json
Content-Type: application/json
```

## Base URL

Ejemplos:

- local: `http://127.0.0.1:8000`
- servidor: `https://tu-dominio.com`

La API vive bajo:

```text
/api/v1
```

## Endpoints disponibles

### 1. Ver usuario autenticado

```http
GET /api/v1/me
```

Respuesta:

```json
{
  "user": {
    "id": 25,
    "name": "API User",
    "email": "api@example.com",
    "role": "CLIENT",
    "organization_id": 3
  }
}
```

### 2. Ver catalogo para registrar serenatas

```http
GET /api/v1/catalog?event_date=2026-06-01&mariachi_group_id=1
```

Devuelve:

- grupos accesibles
- metodos de pago
- paquetes
- obsequios
- artistas
- otros costos

Usalo para que la IA o n8n conozcan IDs y codigos validos antes de crear la serenata.

### 3. Crear serenata

```http
POST /api/v1/serenatas
```

Payload minimo recomendado:

```json
{
  "external_reference": "chatwoot-12345",
  "mariachi_group_id": 1,
  "payer_name": "Laura Gomez",
  "payer_email": "laura@example.com",
  "service_address": "Calle 123 #45-67",
  "neighborhood": "Chapinero",
  "locality": "Bogotá",
  "contact_phone_1": "3001234567",
  "reason": "Cumpleaños",
  "from_name": "Carlos",
  "to_name": "Mamá",
  "event_date": "2026-06-01",
  "event_time": "20:30",
  "payment_method": "Transferencia",
  "base_price": 250000
}
```

Campos utiles:

- `external_reference`: identificador externo unico. Recomendado para Chatwoot, n8n o CRM.
- `submission_token`: opcional. Sirve para evitar dobles envios.
- `serenata_package_id`: opcional.
- `discount_amount`: opcional.
- `internal_notes`: opcional.
- `client_notes`: opcional.
- `gift_items`: opcional.
- `artist_items`: opcional.
- `other_cost_items`: opcional.

Ejemplo con items de catalogo:

```json
{
  "external_reference": "chatwoot-12345",
  "mariachi_group_id": 1,
  "payer_name": "Laura Gomez",
  "service_address": "Calle 123 #45-67",
  "neighborhood": "Chapinero",
  "locality": "Bogotá",
  "contact_phone_1": "3001234567",
  "reason": "Cumpleaños",
  "from_name": "Carlos",
  "to_name": "Mamá",
  "event_date": "2026-06-01",
  "event_time": "20:30",
  "payment_method": "Transferencia",
  "base_price": 250000,
  "gift_items": [
    {
      "code": "ROSA-ROJA",
      "quantity": 1
    }
  ],
  "artist_items": [
    {
      "code": "TROMPETA-EXTRA",
      "quantity": 1
    }
  ]
}
```

Respuesta cuando crea:

```json
{
  "created": true,
  "serenata": {
    "id": 18,
    "code": "MAB-1001",
    "external_reference": "chatwoot-12345",
    "payment_status": "Pendiente",
    "service_status": "Pendiente"
  }
}
```

Si vuelves a enviar la misma `external_reference`, la API no duplica y responde con la serenata existente:

```json
{
  "created": false,
  "serenata": {
    "id": 18,
    "code": "MAB-1001",
    "external_reference": "chatwoot-12345"
  }
}
```

### 4. Consultar serenata

```http
GET /api/v1/serenatas/{reference}
```

`reference` puede ser:

- el `id`
- el `code`
- el `external_reference`

Ejemplos:

```http
GET /api/v1/serenatas/18
GET /api/v1/serenatas/MAB-1001
GET /api/v1/serenatas/chatwoot-12345
```

## Reglas importantes para la IA o integracion

- Antes de crear, llamar a `GET /api/v1/catalog` para conocer grupos, paquetes y metodos validos.
- Usar siempre `external_reference` unica por conversacion o ticket.
- Si no conoces el `mariachi_group_id`, no inventarlo; toma uno del catalogo.
- Si no conoces un `payment_method`, no inventarlo; toma uno del catalogo.
- `event_date` debe ir en formato `YYYY-MM-DD`.
- `event_time` debe ir en formato `HH:MM` de 24 horas.
- `contact_phone_1` debe enviarse aunque llegue con espacios o simbolos; el backend lo normaliza.
- Si el usuario del token no tiene acceso a un grupo mariachi, la API responde error.

## Errores comunes

### `401 Token API inválido.`

El `Bearer` token no existe, fue revocado o esta mal escrito.

### `403`

El usuario del token no tiene permiso para esa accion o ya no esta activo.

### `422`

Faltan datos o algun valor no cumple validacion.

Ejemplos:

- `mariachi_group_id` no accesible
- `payment_method` invalido
- `contact_phone_1` vacio
- `event_date` con formato incorrecto

## Recomendacion para Chatwoot + n8n + IA

Flujo recomendado:

1. La IA recopila datos de la conversacion.
2. n8n llama `GET /api/v1/catalog`.
3. n8n arma el payload final con IDs y nombres validos.
4. n8n llama `POST /api/v1/serenatas`.
5. Guarda `id`, `code` y `external_reference`.
6. Si necesita confirmar estado despues, consulta `GET /api/v1/serenatas/{reference}`.

## Pendiente opcional

Si quieres, se puede agregar despues una pantalla en el panel para:

- crear tokens
- ver ultimo uso
- revocar tokens
- limitar tokens por nombre o integracion