Primeros pasos

Koibox permite que se utilice una API REST que pone a disposición de sus clientes para que los mismos puedan integrar flujos de trabajo automatizados. Esto también permite integrar con herramientas como Make o Zapier.

Nota

La API requiere que tu centro tenga una suscripción al plan Platinum activa. En caso contrario siempre se devolverá una respuesta 403, incluso aunque tengas claves API activas.

Entendiendo el panel de claves API

Para poder utilizar la API primeramente debes crear una clave. Un administrador puede crearla desde el apartado Configuracion > Claves API. En esta sección se encuentra un listado de las claves API propiedad del centro, junto con su estado. También se pueden crear, activar, desactivar y eliminar claves.

Peligro

Las claves son contraseñas que usan las aplicaciones y deben mantenerse en secreto en todo momento, puesto que permiten hacer cambios en tu centro, incluso cuando no trabajas. ¡No las compartas con nadie!

Es importante que tengas en cuenta que las claves API son por centro, una clave no puede acceder a los recursos de otro centro.

1. Accede al formulario para crear una clave API

   En la barra superior azul, pulsa en el botón de “Nueva Clave API”

   

2. Dale un nombre a la clave

   En el formulario que aparece para crear una clave se te pedirá que le des un nombre. Esto es para que más tarde puedas identificar la clave en caso de necesitar gestionarla. Cuando tengas un buen nombre, pulsa en “Crear nueva clave”.

   

3. Guarda la clave y copiala

   Verás que el formulario ahora muestra un campo nuevo de solo lectura. Es tu nueva clave API. Debes guardarla de manera segura, puesto que esta permite a tu aplicación realizar acciones en tu centro.

   Precaución

   Las claves API solo se muestran cuando se crean y no volvemos a mostrarlas nunca, es tu responsabilidad que queden a buen recaudo.

   Soporte no puede ayudarte a recuperar una clave API perdida, deberás desactivarla, eliminarla y crear una nueva. Soporte tampoco te pedirá nunca esta clave.

   Recuerda que esta clave está vinculada al usuario y al centro que las crea, por lo que en los registros de auditoría se muestra que ha sido ese usuario quien ha realizado determinadas acciones.

Realizar tu primera petición

Una vez hayas creado una clave API puedes empezar a realizar peticiones. Puedes comprobar que tu clave funciona correctamente llamando al endpoint /api/api-key/me.

La clave API debe agregarse en la cabecera X-Koibox-Key, en caso de no agregarla a la petición recibirás un error 401.

Deberías recibir una respuesta 200 con una estructura parecida a esta:

{
  "name": "nombre-de-tu-clave",
  "centro": 1
}

La información que recibes sobre la clave es:

• Su nombre
• El identificador del centro al que pertenece

Consejo

Guarda el identificador del centro, puede servirte para futuras llamadas.

¡Todo listo! Puedes ir a la referencia de la API para obtener más información acerca de las llamadas que puedes realizar para trabajar con la información de tu centro.