Imprimir

Tutorial: La API De Reservas

Opciones para la Integración de Back-end

El sistema SuperSaaS está respaldado por una base de datos que almacena información sobre sus clientes, sus reservas, y su configuración. SuperSaaS proporciona APIs (Application Programming Interfaces) para facilitar la integración con sus sistemas back-end, para que pueda ampliar nuestro sistema para proporcionar una funcionalidad personalizada.

Actualmente, dos partes de la base de datos se exponen a través de las APIs:

  1. API de la Base de Datos de Usuarios. (Leer, Actualizar y Escribir). Si su web tiene su propio sistema de entrada y base de datos con información de usuarios puede sincronizarla con la base de datos de SuperSaaS. Esto le permite proporcionar a sus usuarios una forma de registrar y entrar una sola vez.
  2. API de la Base de Datos de Reservas. (Mayormente sólo lectura). Puede obtener información de reservas organizada por horario o por usuario y filtrada por fecha. Véase el resto de esta página para más detalles.

Acceso a la Base de Datos de Reservas

Las APIs se pueden usar para leer información de reservas de la base de datos. Sólo algunas de las APIs apoyan escribir información a la base de datos, y no para todos los tipos de horario. En particular, el horario de servicios no apoya escritura, y en un horario de capacidad se pueden crear reservas pero no ranuras.

Tres Maneras de Hacer la Autenticación

La API es compatible con varios tipos de autenticación. Para comunicación de servidor a servidor puede enviar su nombre de cuenta y contraseña como parámetros de URL, o en un encabezado de autenticación básica HTTP y, opcionalmente, proteger la conexión con SSL. Por supuesto, no debe poner su contraseña de la cuenta en el código HTML para acceder a la API desde un navegador de un cliente, porque eso revelaría su contraseña a quien busque en la fuente de la página.

A fin de facilitar llamar a la API desde un script del lado del cliente se puede autenticar con un hash MD5 en vez de enviar su contraseña. El hash se calcula a partir de una cadena concatenada que incluya su nombre de cuenta, el nombre de usuario y la contraseña de su cuenta. Ya que incluye la contraseña de cuenta que es sólo conocido por usted y SuperSaaS, no se puede calcular por nadie más. Debido a que la suma de comprobación incluye el nombre del visitante es diferente para cada visitante y lo puede poner sin peligro en una llamada AJAX ejecutado por el navegador. La mayoría de lenguajes proporcionan una manera fácil de calcular un hash MD5, por ejemplo:

PHP: $user = 'nombre_usuario@cliente.com';$checksum = md5("Su_nombre_de_cuentaSu_contraseña$user")
Ruby: checksum = Digest::MD5.hexdigest("Su_nombre_de_cuentaSu_contraseña#{'nombre_usuario@cliente.com'}")

La API de "Cambios Recientes"

Puede obtener un documento XML con los cambios recientes en el horario enviando una solicitud HTTP GET al servidor. La solicitud debe tener el siguiente formato:

http://www.supersaas.com/api/changes/<schedule_id>.xml?from=<última_solicitud>&password=<contraseña_admin>
Valores de Entrada
ParámetroValor
schedule_idEl número del horario que desea descargar. Puede obtener este número mirando la página Configurar Resumen, es el último número de la dirección de esa página
fromEl tiempo transcurrido desde la última solicitud en formato "AAAA-MM-DD HH:MM:SS" en UTC
passwordLa contraseña de administrador para la cuenta a la que pertenece el horario. También puede omitir este campo y utilizar la suma de comprobación o autenticación básica HTTP.
slotAl agregar el parámetro "slot=true" información adicional acerca de las ranuras correspondientes se incluirá con las reservas(sólo horario de capacidad)

Todos los valores de entrada deben ser codificados para URL. El sistema responderá con un documento XML que enumera todas las reservas que han visto un cambio de cualquier tipo desde el momento de "última solicutud".

<bookings>
   <booking>
      ...
   </booking>
   <booking>
      ...
   </booking>
</bookings>

Si ha incluido el parámetro slot=true en la solicitud para un horario de tipo capacidad, el documento será formateado como un árbol de ranuras que contienen las reservas pertinentes:

<slots>
   <slot>
      ...
      <bookings>
         <booking>
            ...
         </booking>
         <booking>
            ...
         </booking>
      </bookings>
   </slot>
   <slot>
      ...
   </slot>
</slots>
Campos de Salida
ParámetroValor
idUn identificador de reservas único que se puede utilizar para comparar con descargas anteriores
resourceSi su horario contiene más de un recurso este es el recurso que fue seleccionado (sólo horario de recursos)
slotInformación sobre la ranura a la que pertenece la reserva(sólo horario de capacidad)
serviceUn identificador de servicios (sólo horario de servicios)
startHora de inicio en formato "AAAA-MM-DD HH:MM:SS" en la zona horaria local
finishHora de finalización en formato "AAAA-MM-DD HH:MM:SS" en la zona horaria local
deletedtrue o false dependiendo de si la reserva haya sido borrada
created_onHora de creación en formato "AAAA-MM-DD HH:MM:SS" en UTC (ojo: no local)
updated_onHora de último cambio en formato "AAAA-MM-DD HH:MM:SS" en UTC (esta será la hora de borradura si el campo "deleted" tiene valor true)
created_by
updated_by
Nombre del creador / actualizador. Blanco si una reserva anónima o un cambio de sistema como una actualización del estado por PayPal
waitlisted Si la reserva está en la lista de espera este campo contiene la letra "W" (sólo horario de capacidad)
<más>campos adicionales según seleccionados en la pantalla Configurar Proceso

Todas las horas se devuelven en formato "AAAA-MM-DD HH:MM:SS" independiente del formato especificado en la configuración de la cuenta.

Alternativas al Uso de la API

La API de "Cambios Recientes" requiere sondear ("polling") el servidor SuperSaaS a intervalos para ver si algo ha cambiado. Si desea mantener un sistema de back-end actualizado con los cambios realizados en un horario SuperSaaS hay varias opciones.

La API de la Agenda

Esta API le permite recuperar las reservas de un solo usuario en formato XML. La autenticación se puede hacer con un hash unidireccional para permitir la recuperación por una solicitud AJAX del lado del cliente. Campos de salida son idénticos a los mencionados anteriormente.

http://www.supersaas.com/api/agenda/<schedule_id>.xml?user=<id_usuario>&password=<contraseña_admin>
Valores de Entrada
ParámetroValor
schedule_idEl número del horario que desea descargar. Puede obtener este número mirando la página Configurar Resumen, es el último número de la dirección de esa página. Si se omite muestra todos los horarios de la cuenta, es necesario añadir un parámetro "cuenta" en ese caso.
userO el nombre o la ID del usuario o cero para obtener las reservas del administrador.
from(Opcional) Si presente, solamente solicitar reservas después de este tiempo. Debe estar en el formato "AAAA-MM-DD HH:MM:SS" en la zona horaria local
passwordLa contraseña de administrador para la cuenta a la pertenece el horario. También puede omitir este campo y utilizar la suma de comprobación o autenticación básica HTTP.
checksumUn hash MD5 que contiene el nombre de cuenta, contraseña y nombre de usuario. Ignorado si envía la contraseña de la cuenta.
slotAl agregar el parámetro "slot=true" información adicional acerca de las ranuras correspondientes se incluirá con las reservas (sólo horario de capacidad)

Si se omite la ID de horario se listarán todos los horarios. Por ejemplo, lo siguiente mostrará todas las reservas para un usuario para cada horario en la cuenta:

http://www.supersaas.com/api/agenda.xml?user=<id_usuario>&password=<contraseña_admin>&account=<nombre_cuenta>

Todos los valores de entrada deben ser codificados para URL. El sistema responderá con un documento XML que enumera todas las reservas que ocurren después del tiempo "from". Los campos de salida son idénticos a los de la API de "Cambios Recientes".

<bookings>
   <booking>
      ...
   </booking>
   <booking>
      ...
   </booking>
</bookings>

La API de Disponibilidad

Esta API permite recuperar una lista de los espacios libres en JSON o XML.

http://www.supersaas.com/api/free/<schedule_id>.xml?from=<desde>&password=<contraseña_admin>
Valores de Entrada
ParámetroValor
schedule_idEl número del horario que desea descargar. Puede obtener este número mirando la página Configurar Resumen, es el último número de la dirección de esa página.
fromSolamente solicitar espacios libres después de este tiempo. Debe estar en el formato "AAAA-MM-DD HH:MM:SS" en la zona horaria local
passwordLa contraseña de administrador para la cuenta a la que pertenece el horario. También puede omitir este campo y utilizar la suma de comprobación o autenticación básica HTTP.
checksum
user
Un hash MD5 que contiene el nombre de cuenta, contraseña y nombre de usuario. Ignorado si envía la contraseña. Puede utilizar un valor aleatorio para el nombre de usuario.
length(Opcional) Limitar la búsqueda de espacios libres a por lo menos esta longitud en minutos. Se utilizará la duración predeterminada si este parámetro no está presente (sólo horario de recursos).
resource(Opcional) Limitar la búsqueda de espacios libres al recurso especificado (sólo horario de recursos).
maxresults(Opcional) Limitar la cantidad de resultados obtenidos. El valor predeterminado es 10.

Se recomienda que se agregue un encabezado HTTP "If-Modified-Since" para reducir la carga del servidor. Esto resultará en una respuesta 304 "Not Modified" si nada ha cambiado desde su última solicitud. Tenga en cuenta que la cantidad de espacios libres también puede cambiar debido al paso del tiempo, por ejemplo porque un horario no permite hacer reservas en el pasado. La respuesta "Not Modified" no toma esto en cuenta. El sistema responderá con un documento XML que enumera todos los espacios libres después del tiempo "from".

<slots>
   <slot start="2016-01-18 13:00:00" finish="2016-01-18 15:00:00">
      ...
   </slot>
   <slot start="2016-01-18 15:00:00" finish="2016-01-18 18:00:00">
      ...
   </slot>
</slots>
Campos de Salida
ParámetroValor
slotContiene las propiedades "start" y "finish" que especifican el principio y el final de la ranura en formato "AAAA-MM-DD HH:MM:SS" en la zona horaria local. La propiedad "finish" puede estar vacío si una ranura se extiende indefinidamente.
titleEl título de la ranura, contiene una propiedad id que se puede utilizar para compararla con otras ranuras.
descriptionDescripción de la ranura si disponible (sólo horario de capacidad).
locationUbicación de la ranura si disponible (sólo horario de capacidad).
countEspecifica cuántos espacios están disponibles en esta ranura. Para horarios de recursos siempre será 1. Será 0 para ranuras marcadas como sin límite de capacidad.

Todas las horas se devuelven en la hora local en formato "AAAA-MM-DD HH:MM:SS" independiente del formato especificado en la configuración de la cuenta.

Leer, Crear, Actualizar y Borrar Reservas

Actualmente, todas las acciones de la API se ejecutan como administrador, crear o actualizar como un usuario normal aún no se apoya. Puede utilizar la autenticación de suma de comprobación (hash) mencionado anteriormente si desea crear una reserva desde un script del lado del cliente dentro de un navegador.

Crear una Nueva Reserva

POST /api/bookings

La solicitud debe contener un documento XML que describe la nueva reserva, o contener los campos como parámetros codificados para URI. Consulte el final del documento para el formato. Si la reserva se crea correctamente la respuesta será un encabezado con código de estado 201 ("Created"). El campo Location de la respuesta contendrá la URL que puede utilizar para actualizar la reserva luego, por ejemplo:
Location: http://www.supersaas.com/api/bookings/1234.xml
Si luego necesita actualizar la reserva a través de la API tiene que extraer la ID (1234) del objeto creado de esta URL. La respuesta será un 404 ("Not Found") si el horario no existe y un 403 ("Not Authorized") si la contraseña o la suma de comprobación no es correcta. Si el objeto no pasa la validación, tal vez debido a una dirección de correo.e inválida, el estado 422 ("Unprocessable Entity") le será devuelto, con el cuerpo de la respuesta conteniendo los mensajes de error.

Leer una Reserva

GET /api/bookings/{id}.xml?schedule_id={schedule_id}
Si la reserva existe y la autorización es correcta, la respuesta será un 200 ("OK") con el cuerpo de la respuesta conteniendo un documento XML que describe la reserva.
<booking>
   ...
</booking>

Leer Múltiples Reservas

Hay tres APIs especializadas para recuperar múltiples reservas, filtrando por usuario, por fecha, o por cambios recientes. Consulte el comienzo de esta sección para más detalles. Además de las tres APIs, puede recuperar todas las reservas de un horario con:

GET /api/bookings?schedule_id={schedule_id}

Puede pasar el parámetro limit=X para limitar la cantidad de resultados devueltos a X. Como un caso especial, en un horario de recursos puede pasar un parámetro start que devuelve sólo resultados después de ese tiempo. Esto le permite recuperar la próxima reserva (la primera reserva futura) con una solicitud como
GET /api/bookings?schedule_id=123&start=2016-10-10&limit=1.

Actualizar una Reserva

PUT /api/bookings/{id}.xml
El sistema busca la reserva con la ID proporcionada y la actualiza. Similarmente a la API de "crear" puede proporcionar un documento XML o parámetros codificados para URI. El resultado será una respuesta vacía con un 200 ("OK") o un 404 ("Not Found") si la ID no se encuentra, tal vez porque la reserva haya sido borrada. Si el objeto contiene campos inválidos la respuesta será un 422 ("Unprocessable Entity") con un documento XML de error. Si el software que está utilizando no es compatible con el envío del verbo HTTP PUT puede hacer un POST normal.

Borrar una Reserva

DELETE /api/bookings/{id}.xml
El sistema buscará la ID en la base de datos y devolverá un 200 ("OK") si la reserva se ha borrado con éxito, o un 404 ("Not Found") si (ya) no existe. Si el software que está utilizando no es capaz de enviar el verbo HTTP DELETE, también puede hacer un POST con el parámetro adicional "_method=DELETE".

Formato de Datos

Los campos que puede proporcionar se determinan por la configuración en la pantalla Configurar, pestaña Proceso. Esta pantalla también determina qué valores son opcionales, y cuales obligatorios. Tenga en cuenta que en los mensajes XML las rayitas de subrayado se sustituirán por guiones.

CampoComentario
schedule_idEl número del horario. Puede obtener este número mirando la página Configurar Resumen, es el último número de la dirección de esa página.
password, checksum(Opcional) Véase más arriba, opcionalmente puede pasar uno o ambos de estos parámetros como parte del proceso de autenticación.
booking[start], booking[finish](Sólo horario de recursos) Hora de inicio y de finalización de la reserva en hora local.
booking[slot_id](Sólo horario de capacidad) La ID de la ranura para la que desea crear la reserva.
booking[resource_id](Sólo horario de recursos, opcional) Si el horario tiene más de un recurso puede indicar cuál. Si no sabe la ID puede pasar el nombre en su lugar.
booking[full_name, address, mobile, phone]Si cualquiera de estos atributos están presentes, se almacenan sin cambios como cadenas codificadas de UTF-8.
booking[country]Si presente, un código de país ISO 3166-1 de dos caracteres.
booking[email]La dirección de correo.e del usuario. Se ignora si se utiliza la dirección de correo.e como nombre de usuario.
booking[field_1, field_2, field_1_r, field_2_r, super_field]Los valores de los dos campos personalizados en el objeto de usuario, los dos campos personalizados en la reserva, y el campo de supervisor, independientemente de la etiqueta que les haya dado usted en la interfaz de usuario.

Leendo datos el documento XML recuperado contendrá los siguientes campos además de los mencionados anteriormente:
CampoComentario
idLa ID interna asignado a esta reserva que se puede utilizar para actualizar la reserva.
created-onLa hora de creación de esta reserva en UTC.
updated-onLa hora de última modificación de esta reserva en UTC.
created-by,
updated-by,
user-id
El nombre y la ID de la persona que ha creado/modificado la reserva si está disponible.
statusMensaje de estado del pago o el proceso de aprobación, en su caso.
pricePrecio cobrado por la reserva, en su caso.
res-name(Sólo horario de recursos) Nombre del recurso a la que pertenece esta reserva.

Uso Ilustrativo

Para crear una reserva en el horario con ID 123 enviaría la siguiente solicitud HTTP POST (codificación URI omitida para mayor claridad)

http://www.supersaas.com/api/bookings?schedule_id=123&password=secreto&booking[start]=2016-10-10 12:00&booking[finish]=2016-10-10 13:00&booking[full_name]=Prueba

Próximo capítulo: Utilización en dispositivos móviles | Volver a Índice de tutoriales