Integración Onlive iCalendar

Para integrar Onlive iCalendar en tu sistema deberás tener en cuenta las definiciones técnicas definidas en este documento.

Entidades del sistema

Las entidades principales del sistema son:

• Organización (Organization): Representa una empresa o entidad que ofrece servicios de citas. Todas las demás entidades están asociadas a una organización.
• Agente (Agent): Representa un empleado que atiende citas, y posee un calendario para gestionar su disponibilidad.
• Grupo (Group): Representa un conjunto de agentes o assets, es útil para gestionar departamentos, equipos de trabajo, etc.
• Recurso (Asset): Representa un recurso que puede ser reservado, como un vehículo o una sala. Cada asset tiene su propio calendario.
• Calendario (Calendar): Representa un calendario de citas, y puede ser de un agente o un asset.
• Cita (Appointment): Representa una reserva en un calendario.
• Cliente (Client): Representa un usuario que reserva una cita.
• Servicio (Service): Representa un servicio reservable, como un test drive, una visita a una propiedad, una consulta médica, etc. Los servicios pueden tener recursos asociados y la definición de la ventana de tiempo en la que se podrán crear citas, su duración, tiempo de anticipación para reservar, etc.
• Disponibilidad Semanal: Representa la disponibilidad de un agente en la semana para uno o varios servicios. Es decir, de lunes a domingo, en que horarios está disponible un agente para un servicio.

API REST

El sistema de gestión de citas expone una API REST para la gestión de citas. La vía de autenticación es mediante un token OAuth 2.0. Este token se obtiene desde el panel de control de Onlive y se deberá renovar tras su expiración usando un token de refresco.

Autenticación

Para autenticarse en la API se debe enviar el token de acceso en la cabecera Authorization con el valor Bearer <token>.

Para renovar un token de acceso se debe hacer una petición POST a la URL /oauth/token con los siguientes parámetros:

• grant_type: refresh_token
• refresh_token: Token de refresco
• client_id: ID del cliente
• client_secret: Secreto del cliente

La respuesta será un json con el nuevo token de acceso y el token de refresco.

{
    "access_token": "asdfasdfasd....asdfasdf",
    "expires_in": 3599,
    "token_type": "Bearer",
    "refresh_token": "xxxdasdfasdfasdfasdf....asdfasdf",
    "scope": "read write"
}

Organización

Las organizaciones se crean de forma interna, no se expone por el momento una API para su gestión.

Agente

• GET /agents: Obtiene la lista de agentes.
• GET /agents/{id}: Obtiene un agente por su ID.
• POST /agents: Crea un nuevo agente.
• PUT /agents/{id}: Actualiza un agente existente.
• DELETE /agents/{id}: Elimina un agente existente.

Grupo

• GET /groups: Obtiene la lista de grupos.
• GET /groups/{id}: Obtiene un grupo por su ID.
• POST /groups: Crea un nuevo grupo.
• PUT /groups/{id}: Actualiza un grupo existente.
• DELETE /groups/{id}: Elimina un grupo existente.

Recurso

• GET /assets: Obtiene la lista de recursos.
• GET /assets/{id}: Obtiene un recurso por su ID.
• POST /assets: Crea un nuevo recurso.
• PUT /assets/{id}: Actualiza un recurso existente.
• DELETE /assets/{id}: Elimina un recurso existente.

Calendario

• GET /calendars: Obtiene la lista de calendarios.
• GET /calendars/{id}: Obtiene un calendario por su ID.
• POST /calendars: Crea un nuevo calendario.
• PUT /calendars/{id}: Actualiza un calendario existente.
• DELETE /calendars/{id}: Elimina un calendario existente.

Cita

• GET /appointments?calendarId={calendarId}: Obtiene la lista de citas de un calendario.
• GET /appointments/{id}: Obtiene una cita por su ID.
• POST /appointments: Crea una nueva cita. Debe incluir el calendarId en el cuerpo de la petición.
• PUT /appointments/{id}: Actualiza una cita existente.
• DELETE /appointments/{id}: Elimina una cita existente.

Cliente

La creación de clientes se realiza de forma interna, no se expone por el momento una API para su gestión.

Servicio

• GET /services: Obtiene la lista de servicios.
• GET /services/{id}: Obtiene un servicio por su ID.
• POST /services: Crea un nuevo servicio.
• PUT /services/{id}: Actualiza un servicio existente.
• DELETE /services/{id}: Elimina un servicio existente.

Disponibilidad Semanal

• GET /weekly-availabilities?agentId={agentId}: Obtiene la lista de disponibilidades semanales de un agente.
• GET /weekly-availabilities/{id}: Obtiene una disponibilidad semanal por su ID.
• POST /weekly-availabilities: Crea una nueva disponibilidad semanal. Debe incluir el agentId en el cuerpo de la petición.
• PUT /weekly-availabilities/{id}: Actualiza una disponibilidad semanal existente.
• DELETE /weekly-availabilities/{id}: Elimina una disponibilidad semanal existente.

Webhooks

Se expone un endpoint para la subcripción a los cambios que se realizan en los eventos de un calendario. El tiempo (tll) máximo de vida del webhook es de 7 días, pasado este tiempo el webhook será eliminado.

Crear un webhook

• POST /calendars/{calendarId}/webhooks: Crea un nuevo webhook. Se deberán incluir los siguientes parámetros

{
    "url": "https://example.com/webhook",
    "ttl": 604800
}

La respuesta será un json con el ID del webhook.

{
    "id": "asdfasdfasdfasdf"
}

Cuando un evento es creado, actualizado o eliminado en un calendario, se enviará una petición POST al endpoint del webhook con el siguiente cuerpo:

{
    "event": "appointment.created",
    "data": {
        "id": "asdfasdfasdfasdf",
    }
}

Con el ID de la cita que ha sido creada, actualizada o eliminada, se podrá consultar la información de la cita en la API.

Los posibles valores de event son:

• appointment.created: Se envía cuando una cita es creada.
• appointment.updated: Se envía cuando una cita es actualizada.
• appointment.deleted: Se envía cuando una cita es eliminada.

Eliminar un webhook

• DELETE /webhooks/{id}: Elimina un webhook existente.