Saltar al contenido principal

Integración de APIs en SMARTFENSE

  • Actualización

Este artículo explica qué es una API, cómo funciona dentro de SMARTFENSE y cómo registrar una nueva aplicación para interactuar de forma segura con la API de SMARTFENSE.

 

¿Qué es una API?

Definición general

Una API (Interfaz de Programación de Aplicaciones) es un conjunto de protocolos y herramientas que permiten que diferentes aplicaciones de software se comuniquen entre sí.
Actúa como un intermediario que posibilita que un programa acceda a los datos y funciones de otro, sin necesidad de conocer su funcionamiento interno.

En otras palabras, una API ofrece una forma segura y estandarizada de intercambiar información entre sistemas.

 

Aplicaciones registradas

Cada solicitud realizada a la API de SMARTFENSE debe estar autenticada mediante las credenciales de una aplicación registrada.

En la sección Configuración > Integraciones > API, podrás registrar las APIs necesarias con los datos de tu organización.
 

Para mantener la seguridad de la integración:

  • Todas las solicitudes deben realizarse utilizando HTTPS.
  • Es obligatorio incluir las credenciales de la aplicación en el encabezado de autenticación de cada petición.

 

Registrar nueva aplicación

  1. Nombre: permite asignar un nombre descriptivo a la aplicación. Esto facilita su identificación cuando se gestionan varias integraciones.
  2. Client id (campo de solo lectura): identificador único asignado a la aplicación. Se utiliza durante el proceso de autenticación y autorización para reconocer la fuente de la solicitud.

  3. Client secret (campo de solo lectura): clave privada y única que autentica la aplicación.
     

    Nota: este valor solo se muestra una vez al crear la aplicación. No puede recuperarse posteriormente. Guárdelo en un lugar seguro.

     

  4. Tipo de cliente: especifica cómo se utilizará el client secret:
    • Confidencial: para uso en el backend de un servidor, donde las credenciales están protegidas.
    • Público: para uso del lado del cliente; se crea mediante un método de cifrado más robusto.
  5. Tipo de concesión de autorización: define el flujo de autenticación utilizado para obtener un token de acceso.
     
    • Authorization code: flujo más seguro y común, recomendado para aplicaciones con servidor backend.
    • Client Credentials: adecuado para comunicación entre servidores o servicios sin intervención de usuarios finales.
  6. URIs de redirección: permite ingresar una o más URL separadas por coma. Una vez completado el flujo de autenticación, el sistema redirige a una de las direcciones ingresadas.
  7. Alcances (Scopes): definen los permisos específicos que la aplicación necesita para interactuar con la API.
    Por seguridad, seleccione solo los alcances mínimos requeridos. Como se específica en la documentación de la API que queremos obtener datos.
    Puede consultar los permisos disponibles en la sección Authorizations de cada endpoint dentro de la documentación oficial de la API de SMARTFENSE.
  8. Una vez completados todos los campos, haga clic en Guardar para registrar la aplicación.



Documentación oficial de la API de SMARTFENSE

SMARTFENSE pone a disposición la documentación oficial de su API, donde puede consultar todos los endpoints disponibles, sus parámetros y los formatos de respuesta.

Cómo acceder a la documentación

  1. Ingrese a Configuración > Integraciones > API.
  2. Haga clic en el enlace API de SMARTFENSE (se recomienda abrirlo en una nueva pestaña).
  3. Será dirigido a la URL pública de la documentación, con el siguiente formato: https://nombretenant.takesecurity.com/api/schema/redoc/ Donde nombretenant corresponde al nombre de su instancia.

Información disponible en la documentación

La documentación se organiza en un menú lateral con las siguientes secciones generales:

  • Introducción: presentación de la API y de los principios sobre los que está construida (REST, verbos HTTP, códigos de respuesta estándar).
  • URL Base: indica la URL base sobre la que se construyen todas las rutas de los endpoints. Todas las rutas documentadas son relativas a esta URL.
  • Autenticación: explica los flujos de autenticación soportados (OAuth 2.0 Client Credentials y Authorization Code), cómo obtener las credenciales y cómo incluir el bearer token en el encabezado Authorization de cada solicitud.
  • Extras: información complementaria útil para integradores.

Adicionalmente, la documentación incluye secciones por recurso, donde se agrupan los endpoints relacionados. Las secciones disponibles son:

  • Campañas
  • Usuarios
  • Grupos
  • Auditoría
  • Organización
  • Contenidos
  • Gamificación

Información que contiene cada endpoint

Al ingresar al detalle de un endpoint encontrará, organizada en una vista de dos columnas, la siguiente información:

Columna izquierda — definición del endpoint

  1. Método HTTP y ruta: por ejemplo, GET /api/v1/campaigns.
  2. Descripción: explica qué información permite obtener o qué acción realiza el endpoint.
  3. Authorizations: indica el esquema de autorización requerido (por ejemplo, oauth2) y los alcances necesarios.
  4. Query parameters: lista de parámetros admitidos por la consulta. Para cada parámetro se indica:
    • Nombre del parámetro.
    • Tipo de dato (string, integer, etc.).
    • Descripción de su utilidad.
    • Formato esperado, si corresponde (por ejemplo, fechas en formato YYYY-MM-DD hh:mm:ss en GMT).
    • Valores posibles, cuando el parámetro está limitado a un conjunto (por ejemplo, los componentes admitidos: trainings, exams, surveys, videos, videogames, phishing, ransomware, smishing, newsletters, liveSimulations, webGroup).
    • Valor por defecto y valor máximo, cuando aplica (por ejemplo, page = 1, page_size = 100, máximo 100).
  5. Responses: detalla los códigos de respuesta posibles y, para cada uno, el esquema esperado:
    • 200: respuesta exitosa, con el detalle de los campos devueltos (por ejemplo, count, next, previous y el array del recurso consultado).
    • 400 y otros códigos de error: incluyen el campo error con el mensaje correspondiente.

Columna derecha — ejemplos

  1. Request samples: ejemplo de la solicitud en distintos lenguajes, habitualmente cURL y Python, incluyendo encabezados y el bearer token.
  2. Response samples: ejemplo del cuerpo de la respuesta para cada código de estado documentado, en formato application/json.

💡 Mejores prácticas

  • Utilice siempre HTTPS en las solicitudes a la API para proteger los datos transmitidos.
  • Guarde el Client secret en un repositorio seguro, ya que no podrá visualizarlo nuevamente.
  • Seleccione el flujo de autenticación (Authorization code o Client Credentials) según el tipo de integración y nivel de seguridad requerido.
  • Limite los alcances (scopes) al mínimo necesario para reducir riesgos de exposición.
  • Abra la documentación oficial en una nueva pestaña para mantener disponible la pantalla de configuración mientras consulta los endpoints.
  • Antes de implementar una integración, revise en la documentación los parámetros admitidos, los valores posibles y los límites de cada endpoint (por ejemplo, page_size máximo) para diseñar consultas eficientes.
  • Verifique en la sección Authorizations de cada endpoint los alcances exactos que debe asignar a la aplicación registrada.

Relacionada con

Artículos relacionados