# Simple Integration Service Endpoint (SISE)

Un SISE está diseñado para ser usado a través de un Agente de IA de Induxsoft, por lo que espera como carga útil la estructura que define el [protocolo de integración](https://docs.induxsoft.net/es/iae/agentes/protocolo-integracion.md#invocacion-de-herramienta-externa) para la invocación de herramienta externa.

##### Autenticación

El endpoint requiere un **token personalizado**, configurado en el catálogo de **"Integración, puntos finales"** del sitio V12.


##### Estructura de invocación

El SISE espera la estructura estándar de invocación de herramienta externa.

Ejemplo del payload:
```
{
    ...SISE,
    "params": {
        ...
    },
    "data": {
        ...
    }
}
```

---

### Consultar espacios disponibles

#### Descripción

Este SISE permite consultar los horarios disponibles de uno o varios calendarios.

Está diseñado para ser invocado por agentes de IAE mediante el protocolo de herramientas externas de Induxsoft.

#### Solicitud HTTP

- **Punto final:** `https://{mi-sitio-v12}.induxsoft.net/!/sise/calendar-availability/`
- **Método:** `GET` | `POST`
- **Authorization:** `token` (cadena tal cual) configurado en el catálogo "Integración, puntos finales" del sitio V12.

##### Campos esperados

| Campo | Tipo | Requerido | Predeterminado | Descripción |
| - | - | - | - | - |
| `authorization` | string | *Sí | "calendar-availability" | Cadena configurada para la integración del sitio v12 |
| `calendar_id` | string | Sí | - | Lista de calendarios delimitada por comas |
| `start`       | string | No | Fecha y hora actual | Fecha y hora de inicio |
| `end`         | string | No | - | Fecha y hora final |
| `next_days`   | integer | No | 3 | Días a partir de `start` en los que se consulta la disponibilidad |
| `only_json`   | boolean | No | `false` | Tipo de respuesta |
| `only_on_the_hour` | boolean | No | `false` | Solo sugerencias de horas completas. Ej: 10:00, 11:00, 12:00... |

###### Notas

Solo cuando la solicitud se hace por GET. El campo `authorization` puede proporcionarse desde la URL.

El rango de fecha `end` se obtiene de la operación: `start` + `next_days`.

Si se establece `end`, `next_days` es igual a los días entre `start` y `end`

Cuando `only_json` es `false` se incluye un texto descriptivo; si no hay disponibilidad. "No hay disponibilidad para el periodo `start` a `end`", en caso, se incluye el texto: "Disponibilidad entre `start` y `end`: JSON_ARRAY"

##### Ejemplos

Consultar la disponibilidad de un calendario asumiendo los parámetros por defecto.

```json
{
    ...SISE
    "data": {
        "calendar_id": "6756ef71ae0f406d94ce466fcf36e161"
    }
}
```

Consultar espacios disponibles de los próximos 5 días.

```json
{
    ...SISE
    "data": {
        "calendar_id": "6756ef71ae0f406d94ce466fcf36e161",
        "next_days": 5
    }
}
```

o, asumiendo que actualmente es "2026-05-20".

```json
{
    ...SISE
    "data": {
        "calendar_id": "6756ef71ae0f406d94ce466fcf36e161",
        "end": "2026-05-25 10:00"
    }
}
```

Consultar espacios por GET.

GET: https://`{mi-sitio-v12}`.induxsoft.net/!/sise/calendar-availability/?authorization=`{token}`&calendar_id=6756ef71ae0f406d94ce466fcf36e161&next_days=3

#### Respuesta

##### Respuesta exitosa

`only_json` = false

```text
Disponibilidad entre 2026-05-20 10:00 y 2026-05-22 10:00
{"calendar_id":"6756ef71ae0f406d94ce466fcf36e161","calendar_name":"Demostraciones","availability":"Sí, 3 espacios disponibles","slots":[{"day":"Viernes, 2026-05-22","start":"2026-05-22 18:00","end":"2026-05-22 18:59","duration":59},{"day":"Viernes, 2026-05-22","start":"2026-05-22 19:00","end":"2026-05-22 19:59","duration":59},{"day":"Viernes, 2026-05-22","start":"2026-05-22 20:00","end":"2026-05-22 20:59","duration":59}]}
```

`only_json` = true

```json
{
  "success": 1,
  "data": [
    {
      "calendar_id": "6756ef71ae0f406d94ce466fcf36e161",
      "calendar_name": "Demostraciones",
      "availability": "Sí, 3 espacios disponibles",
      "slots": [
        {
          "day": "Viernes, 2026-05-22",
          "start": "2026-05-22 18:00",
          "end": "2026-05-22 18:59",
          "duration": 59
        },
        {
          "day": "Viernes, 2026-05-22",
          "start": "2026-05-22 19:00",
          "end": "2026-05-22 19:59",
          "duration": 59
        },
        {
          "day": "Viernes, 2026-05-22",
          "start": "2026-05-22 20:00",
          "end": "2026-05-22 20:59",
          "duration": 59
        }
      ]
    }
  ]
}
```

##### Respuesta fallida

`only_json` = false

```text
No fue posible obtener los espacios: ...detalles
```

`only_json` = true

```json
{
    "success": 0,
    "message": "No fue posible obtener los espacios: ...detalles"
}
```

---

### Agregar o actualizar evento

#### Descripción

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.

#### Solicitud HTTP

- **Punto final:** `https://{mi-sitio-v12}.induxsoft.net/!/sise/calendar-event/`
- **Método:** `POST`
- **Authorization:** `token` (cadena tal cual) configurado en el catálogo "Integración, puntos finales" del sitio V12.

##### Campos esperados

Todos los campos esperados por el SISE deben estar en la carga útil enviada por el agente en el campo ```data``` y de no ser así, en el campo ```params```.

- **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**
- **participants** - Un array (`[]`) donde cada elemento (`{}`) representa un participante del evento. **Opcional**, cada elemento puede contener las siguientes propiedades.
    - *name -* Nombre del participante. **Requerido**
    - *email -* Correo del participante. **Opcional**, pero requerido si no se indica *phone*.
    - *phone -* Teléfono con código de país e indicador de número movil del participante. **Opcional**, pero requerido si no se indica *email*.
    - *notes -* Texto informativo de propósito general. **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).

Con la propiedad `participants` puede notificar sobre la cercania del evento a los integrantes, para ello debe configurar las [Notificaciones por tipos de eventos](/es/productos/v12/users/pim/pim_event_type_notif/)

##### Ejemplo de carga útil

```
{
    "agent_id":"Id del agente",
    ...
    "data":{
        "calendar_id": "cal_001,cal_002",
        "type": "reunion_tecnica",
        "caption": "Revisión de arquitectura de software",
        "start": "2024-10-25 14:30",
        "duration": 60,
        "important": true,
        "backcolor": "#f39c12",
        "color": "#ffffff",
        "participants": [
            {
                "name": "Juan Pérez",
                "email": "juan@email.com",
                "phone": "+52 1 123 456 7890"
            }
        ]
        "response_type": "json",
        "suggested_days": 5,
        "only_on_the_hour": false
    }
}
```


#### 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

#### Descripción

Permite cancelar un evento previamente registrado.

#### Solicitud HTTP

- **Punto final:** `https://{mi-sitio-v12}.induxsoft.net/!/sise/calendar-event-delete/`
- **Método:** `POST`
- **Authorization:** `token` (cadena tal cual) configurado en el catálogo "Integración, puntos finales" del sitio V12.

##### 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
```