Saltar al contenido principal

Ayuda Docebo

¿Cómo podemos ayudarle?

Información general sobre las API

Última actualización
Docebo module
Tiempo de lectura
Nivel de usuario
  • Administrators

Presentación

Las API de Docebo le permiten conectar el sistema de gestión del aprendizaje con otras aplicaciones. Puede utilizarlas, por ejemplo, como ayuda para automatizar tareas y compartir información entre sistemas.

Las API proporcionan extremos a través de los cuales puede llevar a cabo diversas acciones en su plataforma, como gestionar usuarios, administrar cursos, recuperar datos, etc. Para más información sobre las acciones disponibles, consulte el artículo Descripción general de los servicios y extremos de API.

Asimismo, puede interactuar con las API mediante el navegador de API, que le permite probar y utilizar los extremos desde una interfaz web, sin necesidad de programar una integración.

Este artículo ofrece información general aplicable a todas las API de Docebo.

Navegador de API

Dentro de la plataforma tiene a su disposición la documentación de referencia y un entorno de pruebas para todas las API disponibles públicamente de Docebo, a través de la interfaz Navegador de API, ubicada en:

<yourplatform URL>/api-browser

Esta documentación se actualiza constantemente junto con su plataforma.

Para obtener una introducción sobre cómo utilizar el navegador de API, consulte el artículo Primeros pasos con el navegador de API de Docebo.

URL de base para las llamadas a las API

La URL de base para todas las llamadas a las API es la URL de su plataforma. Por ejemplo, si en el navegador de API ve una ruta de extremo indicada como:

/course/v1/courses

Significa que la URL de la solicitud completa debe tener la siguiente estructura:

<your platform URL>/course/v1/courses

Versión actual

La versión predeterminada de la API expuesta actualmente es la versión 1 (v1). No obstante, es posible que en el futuro haya microservicios específicos que ya expongan versiones posteriores (v2, v3...). La versión de la API que tenga previsto utilizar se especificará dentro de la URL del extremo. Por ejemplo:

GET /learn/v1/location

Verbos de las solicitudes HTTP

En conformidad con las directrices REST, las API de Docebo requieren el uso de un método HTTP adecuado para los tipos de llamadas concretas que se realicen al servidor. La estructura de API de Docebo sigue estas directrices siempre que sea técnicamente posible, lo que incluye:

  • GET Solicitudes: Se utilizan para recuperar representaciones de recursos
  • POST Solicitudes: Se utilizan para crear nuevos recursos
  • PUT Solicitudes: Se utilizan para actualizar un recurso existente
  • DELETE Solicitudes: Se utilizan para eliminar recursos

Esquema

Se puede acceder a todas las API utilizando tanto el protocolo HTTP como el protocolo HTTPS. Sugerimos encarecidamente el uso del protocolo HTTPS con el fin de proteger la información sensible que se transfiera desde su sistema a Docebo (y viceversa). Todas las solicitudes y respuestas de la API deben estar en formato JSON.

curl -i -X GET http://yourdomain.docebosaas.com/manage/v1/group -H 'Authorization: Bearer f7bfc5f78877f6ec321a650b10e8aa3d32a18f32'

Respuesta:

HTTP/1.1 200 OK
Server: openresty
Date: Tue, 29 May 2018 08:35:06 GMT
Content-Type: application/json; charset=UTF-8
Content-Length: 479
Connection: keep-alive
Access-Control-Allow-Credentials: true
Access-Control-Expose-Headers: X-Docebo-Api-Version
X-Docebo-Api-Version: 1.0.0
X-UA-Compatible: IE=Edge,chrome=1
X-Frame-Option: SAMEORIGIN
X-XSS-Protection: 1
Access-Control-Allow-Origin: *
X-Docebo-Backyard: manage
Front-End-Https: on

Extremos de lotes

En relación con las reglas anteriormente descritas para los verbos de las solicitudes HTTP, se aplican algunas excepciones a extremos determinados que se utilizan para la creación o actualización masiva de recursos. En estos casos, las llamadas HTTP POST también pueden utilizarse para actualizar recursos existentes y crear otros nuevos en la misma llamada a la API. El objetivo de esto es minimizar el número de llamadas a la API efectuadas por el cliente y explotar al máximo el mecanismo de fragmentación inherente a este tipo de llamadas. Estos extremos se identifican normalmente con el sufijo /batch:

POST https://yourdomain.docebosaas.com/manage/v1/user/batch
A tener en cuenta: No puede enviar llamadas simultáneas a API por lotes.

Parámetros

Hay tres formas de transmitir parámetros a las API de Docebo: ruta, secuencia de consulta y cuerpo de la solicitud.

Parámetros de ruta

En algunos casos, los parámetros se introducen directamente en la estructura de la URL del extremo. Este tipo de parámetros contiene por lo general ID inmutables, pero en algunos casos pueden contener nombres de recursos sin identificadores.

A continuación se muestra una URL de ejemplo de un extremo que acepta un parámetro de ruta:

PUT https://yourdomain.docebosaas.com/learn/v1/courses/{id}

Parámetros de secuencia de consulta

Los parámetros de secuencia de consulta se utilizan principalmente para permitirle filtrar, paginar y (en términos generales) modificar la respuesta que devolverá una llamada a la API. El formato de los parámetros de secuencia de consulta es la URL completa del recurso seguida de un signo de interrogación y los parámetros opcionales:

GET https://yourdomain.docebosaas.com/learn/v1/enrollments?id_user{user_id}

Parámetros del cuerpo de la solicitud

Para las llamadas a la API PUT y POST, debe transmitir los parámetros dentro del cuerpo de la solicitud en formato JSON. En la Referencia de la API, debería ver para cada extremo los parámetros adecuados que pueden enviarse a un extremo determinado.

Parámetros no ID (identificadores secundarios)

Para algunos recursos, las API de Docebo admiten referencias de parámetros no ID, como códigos de ramas. No obstante, resulta importante recordar que, al contrario que los ID únicos, estos valores son mutables y pueden no ser únicos dentro de su plataforma. La API responderá en dichos casos con un error HTTP 400.

Si tiene planeado utilizar API con referencias no ID, debería comprobar y asegurar la unicidad de dichas referencias. Además, le aconsejamos comunicar de forma explícita al extremo que debe funcionar en modo no ID configurando el parámetro use_secondary_identifier como true.

Por ejemplo, el extremo GET /manage/v1/orgchart/{branch_id} puede aceptar tanto el identificador interno único como el código alfanumérico de rama. Si desea utilizar el código de rama, debe transmitir la secuencia de parámetros de consulta use_secondary_identifier configurada como true.

En el caso de una rama cuyo código asignado sea code1562, la URL de la solicitud resultante será:

https://yourdomain.docebosaas.com/manage/v1/orgchart/code1562?use_secondary_identifier=true

Bibliotecas de clientes de API

En este momento, Docebo no proporciona ninguna biblioteca de clientes para las API de Docebo. Deberá configurar su propio paquete para empezar a programar en las API de Docebo.

Limitaciones de las llamadas a las API

Para mantener un rendimiento ideal y asegurar que las API estén disponibles para todos los clientes, Docebo aplica límites de frecuencia a la actividad de las API. Estos límites pueden variar en función de la configuración de su plataforma. Para más información sobre los límites del sistema, visite nuestra página del Trust center (se abre en una nueva pestaña).

Advertencia: Las llamadas a API de ramas nunca deben ejecutarse simultáneamente, ya que pueden producirse resultados impredecibles y la estructura de las ramas puede correr el riesgo de corromperse. Las llamadas a API afectadas son:

  • POST /manage/v1/user/batch
    (solo si la llamada también crea las ramas al mismo tiempo que importa los usuarios)
  • POST /manage/v1/orgchart
  • DELETE /manage/v1/orgchart/{id}
  • PUT /manage/v1/orgchart/{branch_id}
  • POST /manage/v1/orgchart/{id}/move
  • DELETE /manage/v1/orgchart/batch
  • POST /manage/v1/orgchart/batch

Asegúrese de que estas llamadas a API de ramas se ejecuten de forma secuencial.

Gestión de redireccionamientos HTTP

Actualmente, ninguna de las API de Docebo utiliza redireccionamientos. Sin embargo, entendemos que esto puede ser necesario en el futuro para gestionar algunos casos específicos. Por esta razón, le invitamos a considerar un código 3xx HTTP como posible respuesta para todos los extremos. Dado que no es un código que represente un error, debe seguir el redireccionamiento en sí.

Paginación y clasificación

Todas las solicitudes que devuelven un número variable (y potencialmente grande) de elementos se paginan de forma predeterminada. El valor predeterminado para el número de elementos por página está ajustado a 10 elementos. Tenga en cuenta que este valor podría ser diferente para algunos extremos por motivos de rendimiento. Puede modificar este límite utilizando el parámetro page_size, que es transmitido al extremo por la secuencia de consulta. El parámetro acepta valores comprendidos entre 1 y 200. Los valores que estén fuera de estos umbrales no se considerarán válidos. El parámetro de página le permite obtener datos de una página específica dentro de los resultados devueltos. El valor predeterminado para este parámetro es 1, que corresponde a la primera página de resultados. Incluso en este caso, el parámetro puede ser transmitido a la API a través de una secuencia de consulta:

curl -X GET https:///courses?page_size=5&page=2' -H 'Authorization: Bearer 2af6ac532cfef197b00f69639aeeef86621d1975'

Los enlaces de navegación entre las páginas de resultados pueden ser generados previamente por la misma API, proporcionando una matriz de enlaces HTTP en la respuesta que puede seguir directamente. Esta función está deshabilitada de forma predeterminada. Para activarla, puede ajustar el parámetro get_cursor a 1 dentro de la secuencia de consulta de la llamada a la API:

curl -X GET https:///courses?get_cursor=1 -H 'Authorization: Bearer 2af6ac532cfef197b00f69639aeeef86621d1975'

Respuesta:

{
 {[...OMITTED-JSON...]
 "_links": {
   "self": {
     "href": "https:///learn/v1/courses?cursor=6b1af27dd7d849c6a0a399439a12ad791abb6708&page=1"
   },
   "next": {
     "href": "https:///learn/v1/courses?cursor=6b1af27dd7d849c6a0a399439a12ad791abb6708&page=2"
   },
   "goto": {
     "href": "https:///learn/v1/courses?cursor=6b1af27dd7d849c6a0a399439a12ad791abb6708&page=__page__"
   },
   "first": {
     "href": "https:///learn/v1/courses?cursor=6b1af27dd7d849c6a0a399439a12ad791abb6708&page=1"
   },
   "last": {
     "href": "https:///learn/v1/courses?cursor=6b1af27dd7d849c6a0a399439a12ad791abb6708&page=2"
   }
 }
}

También puede controlar el orden de clasificación de los registros devueltos por la llamada a la API. El parámetro con el que puede determinarse el orden es sort_attr. Puede ser transmitido a través de una secuencia de consulta. Los valores que puede asumir este parámetro difieren de un extremo al siguiente, ya que los recursos devueltos son diferentes. Le aconsejamos comprobar los valores disponibles para estos parámetros en cada descripción de un extremo en la referencia de la API. En cualquier caso, puede especificar solo un atributo para su uso con fines de clasificación, y no puede especificar atributos de clasificación consecutivos. El valor predeterminado para el parámetro depende del extremo. La dirección de clasificación puede determinarse con el parámetro sort_dir. Los valores aceptables son asc para un orden ascendente y desc para un orden descendente. El valor predeterminado siempre es descendente:

curl -X GET https:///courses?sort_attr=name&sort_dir=asc' -H 'authorization: Bearer 2af6ac532cfef197b00f69639aeeef86621d1975'

Códigos de error

Las API de Docebo devuelven los códigos de error HTTP estándar para indicar si una solicitud se realizó correctamente o no. En concreto, cada cliente debe ser capaz de gestionar los siguientes códigos HTTP:

Código HTTP Descripción
200 - OK Correcto - Se ha realizado la tarea solicitada a la API.
400 - Bad Request La solicitud no era correcta, normalmente debido a un problema de parámetros.
401 - Unauthorized La llamada no se autenticó correctamente.
403 - Forbidden La solicitud del cliente tiene una forma correcta, pero la API se niega a cumplirla. Por ejemplo, en caso de que el usuario no tenga los permisos necesarios para el recurso.
404 - Not Found El recurso solicitado no existe.
408 - Request Timeout El servidor no recibió un mensaje de solicitud completo dentro del periodo de tiempo requerido.
429 - Too Many Requests Se ha superado el límite de velocidad de la API, deberá reintentar la llamada más tarde.
500 - Server Errors La llamada ha generado un error por parte de Docebo.
503 - Service Unavailable Actualmente, el servidor no puede gestionar la solicitud debido a una sobrecarga o mantenimiento temporal.

Política de cambios en las API

Docebo hace todo lo posible para mantener los cambios en las API compatibles con versiones anteriores, pero cuando esto no es posible los clientes son informados de acuerdo con las políticas establecidas en este capítulo.

Cambios compatibles con versiones anteriores

Considere los cambios enumerados a continuación como compatibles con versiones anteriores. Le invitamos a estructurar su código de tal manera que pueda admitir estos cambios en las API. Este tipo de cambios suele producirse sin notificación alguna a los clientes. Entre ellos pueden incluirse:

  • Adición de nuevos extremos
  • Adición de nuevos parámetros opcionales a extremos de API existentes
  • Adición de nuevas propiedades a las respuestas de la API
  • Cambios en el orden de las propiedades en las respuestas de la API
  • Cualquier actualización de la documentación de referencia de la API

Cambios no compatibles con versiones anteriores

En caso de que se produzcan cambios en la API que puedan afectar a las integraciones existentes, se notificará a los clientes con antelación mediante un aviso en la página Actualizaciones de productos. El periodo de preaviso puede variar debido a consideraciones técnicas y de uso, pero por lo general la comunicación previa tendrá lugar al menos un mes antes de que el cambio entre en vigor.

Consejo: Esta regla no se aplica en caso de vulnerabilidades de seguridad críticas. En tales casos, se aplica una corrección inmediatamente y puede aparecer una comunicación en la página Actualizaciones de productos durante la corrección o poco después de esta.

Registro de cambios de la API

Docebo informa a los clientes de cualquier cambio no compatible con versiones anteriores o eliminaciones por obsolescencia en las APIs de Docebo a través de la página general Actualizaciones de productos. Una vez que vea la comunicación relacionada con las API en esta página, puede consultar la referencia oficial de la API (https://<yoursubdomain.docebosaas.com>/api-browser/) para comprender al máximo los cambios que se hayan producido.

Además, el artículo Llamadas a API obsoletas y modificadas proporciona detalles sobre los extremos de las API modificados o eliminados a partir de enero de 2023 (no obstante, no incluye las llamadas a API que se han introducido o lanzado).