### Simple Integration Service Endpoint (SISE)

---

#### Agregar o actualizar evento

**Punto final:** `/!/sise/calendar-event/`

Endpoint unificado para crear nuevos eventos o actualizar eventos existentes en un calendario.

Permite crear nuevas entradas asociadas a una fecha y hora específicas, o modificar eventos ya registrados. El endpoint valida solapamientos, respeta reglas de disponibilidad y almacena el evento para su posterior consulta.

##### Campos esperados

- **event_id** - Identificador del evento a actualizar. Si se omite, se crea un nuevo evento. Si se proporciona, actualiza el evento existente (opcional).
- **calendar_id** - Identificador de un calendario existente o una lista de identificadores delimitada por comas para usar balanceo de carga entre varios calendarios. **Requerido para eventos nuevos**. Opcional para actualizaciones (se mantiene el calendario original).
- **type** - Tipo de evento. **Requerido para eventos nuevos**. Opcional para actualizaciones (se mantiene el tipo original).
- **caption** - Descripción del evento. **Requerido para eventos nuevos**. Opcional para actualizaciones (se mantiene la descripción original).
- **start** - Fecha y hora del evento en formato `yyyy-MM-dd H:mm`. **Requerido**.
- **duration** - Duración del evento en minutos (opcional).
- **important** - Sí o No (true/false) (opcional).
- **backcolor** - Color de fondo del evento. Predeterminado: Color configurado en el tipo de evento (opcional).
- **color** - Color de texto del evento. Predeterminado: Color configurado en el tipo de evento (opcional).
- **detsrc** - Un identificador del tipo de elemento de datos o proceso donde se generó el evento (opcional).
- **srcid** - Un identificador numérico (entero) correspondiente a la instancia del tipo de elemento de datos que originó el evento (opcional).
- **tag** - Una cadena con información de propósito general (opcional).
- **data** - Un objeto con datos de propósito general asociados al evento (opcional).
- **response_type** - Si se omite, la respuesta será texto en lenguaje natural. Si se establece como `"json"`, la respuesta será estructurada (opcional).
- **suggested_days** - La cantidad de días en el futuro a partir de la fecha solicitada que devolverá disponibilidades si la hora indicada no está libre (opcional, valor predeterminado: 7).
- **only_on_the_hour** - Solo se sugieren horas completas, es decir, 10:00, 11:00, 12:00... (opcional).

##### Tipos de eventos

Puede proporcionar tanto el id como el nombre del tipo de evento para `type`.
Los eventos corresponden a la tabla `pim_events_type` de la base de datos V12 usada para la gestión de los calendarios.

**Tipos de eventos predeterminados en la instalación de V12:**

- `01cf7e04160f470092bf5469cb15b2c8` - Llamada.
- `b03cfc4698c742108e9e56283f5ff51a` - Video conferencia.
- `7ccfe477bc31474ca686d123b5d8275a` - Reunión presencial.
- `9e7c5942b2934476ad1f3b03338364b7` - Visita a domicilio.
- `e7d120f36732461f8c1096401b7a768b` - Reservado.

##### Balanceo de carga entre calendarios (solo eventos nuevos)

Cuando `calendar_id` contiene múltiples calendarios separados por comas (ej: `cal1,cal2,cal3`), el sistema aplica balanceo de carga dinámico:

1. Consulta la cantidad de **eventos pendientes** de cada calendario
2. Ordena los calendarios de menor a mayor carga
3. Intenta registrar el evento en el primer calendario de la lista ordenada
4. Si no hay disponibilidad en ese horario, continúa con el siguiente calendario
5. Si ninguno tiene disponibilidad, retorna slots alternativos del calendario con menor carga

**Eventos pendientes:** eventos no cancelados ni completados con fecha posterior al momento actual.

Este mecanismo distribuye automáticamente la carga de trabajo entre múltiples recursos (profesionales, salas, equipos) optimizando la utilización.

##### Comportamiento de actualización

Al actualizar un evento existente (cuando se proporciona `event_id`):

1. El sistema intenta reagendar en el **mismo calendario** del evento original
2. Valida disponibilidad en la nueva fecha/hora solicitada
3. Si hay disponibilidad, actualiza el evento y confirma
4. Si no hay disponibilidad, retorna error con slots alternativos del mismo calendario
5. Preserva todos los campos no especificados en la solicitud

Este comportamiento prioriza la **continuidad** — mantener al mismo profesional o recurso asignado al evento.

##### Integración con la plataforma de agentes de Induxsoft

Si no se indican en la solicitud del servicio los campos `detsrc`, `tag` o `data`, serán llenados automáticamente por los valores provistos por el invocador del agente IA de la siguiente forma:

- `detsrc` = `"ai_chat"` (cadena constante)
- `tag` = Id del agente (agent_id)
- `data` = La carga útil completa definida en el [protocolo de integración](https://docs.induxsoft.net/es/iae/agentes/protocolo-integracion.md)

##### Retorno

**Respuesta exitosa (evento nuevo):**

```
Se ha agregado el evento {nombre_tipo_evento} (event_id:{id del evento}) al calendario {nombre_del_calendario} (calendar_id:{id_calendario}) el {fecha_y_hora} con una duración prevista de {minutos} minutos.
```

**Respuesta exitosa (evento actualizado):**

```
El evento {nombre_tipo_evento} (event_id:{id del evento}) ha sido reagendado al {nueva_fecha_y_hora} en el calendario {nombre_del_calendario}.
```

**Respuesta fallida:**

```
No se ha podido agendar el evento {fecha_y_hora} porque es un día u horario no laborable o sin disponibilidad.
Las siguientes fechas y horarios están disponibles cerca de esa fecha:
- 2025-12-23
    - 13:30
    - 14:00
    - 16:00
    - 17:30
- 2025-12-26
    - 8:00
    - 8:30
...
```

o

```
No fue posible agendar el evento: ...detalles
```

---

#### Cancelar evento

**Punto final:** `/!/sise/calendar-event-delete/`

Permite cancelar un evento previamente registrado.

##### Campos esperados

- **calendar_id** - Identificador del calendario que contiene el evento. **Requerido**
- **event_id** - Identificador del evento a cancelar. **Requerido**

##### Retorno

**Respuesta exitosa:**

```
El evento (event_id:{id del evento}) ha sido cancelado exitosamente.
```

**Respuesta fallida:**

```
No fue posible cancelar el evento: ...detalles
```