Saltar al contenido principal

Primeros pasos

TimeTime te permite añadir un motor de reservas a tu aplicación o sitio web de forma sencilla.

En este tutorial vamos a cubrir el caso de uso básico de TimeTime: Crear un usuario y una página de reservas, consultar la disponibilidad y añadir una reserva.

Obtener una API KEY​

El primer paso para interactuar con la API de TimeTime es obtener una clave de acceso a la API. Esta clave de acceso debe ser adjuntada en las peticiones HTTP y permite identificar al autor de las peticiones.

Para generar una clave de acceso a la API simplemente inicia sesión en TimeTime y accede a la sección de "Developers".

https://app.timetime.in/dashboard/profile/developers

Seleciona la opción para generar una nueva clave y guárdala para más tarde. No compartas esta clave con nadie. ¡Cualquier con acceso a esta clave podrá hacer cambios en la aplicación!

Crear un event-type​

El event-type es el concepto fundamental de TimeTime. Un event-type sirve para representar un servicio que puede ser reservado. Por ejemplo, una peluquería puede tener dos tipos de eventos: "Corte de pelo" y "Lavar y peinar".

Cada event-type tendrá sus reglas de disponibilidad particulares, por ejemplo la duración de "corte de pelo" será de 20m mientras que lavar y peinar podría ser de 40m.

Para crear un event type es suficiente con hacer una petición HTTP a nuestra API pasándole todos los parámetros de configuración deseados.

fetch("https://api.timetime.in/v1/event-types/<my-custom-id>", {
  method: "PUT",
  headers: {
    // Es importante especificar que nos comunicamos por JSON
    "Content-Type": "application/json",
    // Añadimos la clave de accesso a la api obtenida previamente
    Authorization: "Bearer: <your-api-key>",
  },
  body: JSON.stringify({
    // La duración de las reservas.
    duration: "PT1H",
    // El nombre del tipo de evento
    name: "Corte de pelo",
    // La frecuencia en la que se generan opciones de reserva
    step: "PT1H",
    // El identificador de la cuenta donde se va a crear el event-type
    userId: "<your-user-id>",
    // Estos campos son obligatorios pero pueden ignorarse de momento.
    busyIntervas: [],
    hosts: [],
    questions: [],
    thirdPartyCalendars: [],
  }),
});

Una descripción detallada de todos los campos y opciones se puede leer en nuestras API SPECS:

https://docs.timetime.in/api/#operation/putEventType

Consultando la disponibilidad​

Una vez tenemos generado un event-type correctamente podemos consultar su disponibilidad. Esto es, en lenguaje coloquial "ver que huecos hay disponibles"

Para esto se puede utilizar el endpoint getEventTypeAvailability de la API pasándole el identificador (ID) del event-type del cual se quiere consultar la disponibilidad.

fetch("https://api.timetime.in/v1/event-types/{id}/availability", {
  method: "GET",
  headers: {
    // Es importante especificar que nos comunicamos por JSON
    "Content-Type": "application/json",
    // Añadimos la clave de accesso a la api obtenida previamente
    Authorization: "Bearer: <your-api-key>",
  },
});

Esta petición devuelve entre otros campos uno llamado timeSlots que contiene un array de huecos donde el event-type podría estar disponible para ser reservado. El parámetro score tendrá un valor positivo si está disponible y un valor 0 si no está disponible.

{
  "timeSlots": [
    {
      "start": "2019-08-24T14:00:00Z",
      "end": "2019-08-24T14:30:00Z",
      "score": 1
    },
    {
      "start": "2019-08-24T14:30:00Z",
      "end": "2019-08-24T15:00:00Z",
      "score": 0
    }
  ]
}

Es este caso, vemos un ejemplo en el que el servidor devuelve dos slots para el mismo día, el primero que dura desde las 14:00 hasta las 14:30 está disponible y el segundo, de 14:30 a 15:00 no lo esta.

Creando una reserva​

Utilizando el método createBooking de la API Rest se puede crear una reserva en cierto hueco para un event-type determinado.

Para crear la reserva es necesario indicar:

  • El identificador del event-type
  • La hora de inicio de la reserva
  • El email de la persona asociada a la reserva
fetch("https://api.timetime.in/v1/bookings", {
  method: "POST",
  headers: {
    // Es importante especificar que nos comunicamos por JSON
    "Content-Type": "application/json",
    // Añadimos la clave de accesso a la api obtenida previamente
    Authorization: "Bearer: <your-api-key>",
  },
  body: JSON.stringify({
    // El identificador del event-type contra el que se realizará la resrva
    eventTypeId: "f899218d-6f2c-4300-8a70-a6910536041b",
    // La hora de inicio
    start: "2019-08-24T14:00:00Z",
    // El email del cliente de la reserva
    bookerEmail: "string",
  }),
});

El servidor contestará con el código 201 si la reserva se ha podido realizar correctamente.