Este artículo explica cómo utilizar el endpoint Create content de la API de SMARTFENSE para crear contenidos propios de su organización de forma automatizada. Incluye los requisitos, la estructura de la solicitud, el manejo de imágenes y los códigos de respuesta.
¿Qué permite hacer este endpoint?
El endpoint Create content crea un contenido de la organización a partir del mismo JSON con el que se cargan los contenidos predefinidos.
Actualmente acepta los siguientes tipos de contenido:
- Newsletters
- Momentos educativos
- Phishing
- Ransomware
- Módulos interactivos
- Exámenes
- Encuestas
- Cursos
El tipo de contenido se define en la ruta de la solicitud. El contenido se guarda como contenido propio de la organización y queda disponible para ser utilizado en campañas.
Importante: el contenido se crea solo en los idiomas incluidos en el JSON. Esos idiomas deben estar activos en la organización. La API no traduce los textos.
Requisitos previos
- Tener una aplicación registrada en Configuración > Integraciones > Aplicaciones registradas, con su Client ID y Client Secret.
- Asignar a la aplicación el alcance (scope)
write_contents_create(Crear contenidos). - Utilizar uno de los flujos OAuth 2.0 soportados: Authorization code o Client credentials.
- Conocer el identificador del catálogo de la aplicación donde se guardará el contenido.
Para obtener más información sobre cómo registrar una aplicación y obtener el token de acceso, consulte el artículo Integración de APIs en SMARTFENSE.
Endpoint
POST https://tenant.takesecurity.com/api/v1/contents/{content_type}Reemplace tenant por el subdominio de su instancia de SMARTFENSE.
Encabezados requeridos:
Authorization: Bearer <access_token>Content-Type: application/json
Parámetro de ruta
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
content_type | string | Sí | Tipo de contenido a crear. Determina el esquema del cuerpo de la solicitud. |
Consulte los valores exactos de
content_typeen la sección Contenidos > Create content de la documentación oficial de la API, disponible enhttps://tenant.takesecurity.com/api/schema/redoc/.
Estructura del cuerpo de la solicitud
El cuerpo de la solicitud varía según el tipo de contenido. La documentación lo presenta como One of con los siguientes esquemas:
- NewsletterContentRequest
- TeachableContentRequest
- PhishingContentRequest
- RansomwareContentRequest
- TrainingContentRequest
- ExamContentRequest
- SurveyContentRequest
- CourseContentRequest
Los campos comunes son los siguientes:
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
active | boolean | No | Define si el contenido se crea activo (disponible para campañas) o inactivo (para revisarlo y activarlo desde la plataforma). Valor por defecto: true. |
difficulty | string | Sí | Dificultad del contenido: low, medium o high. |
compliance_mappings | array of objects | No | Cláusulas de las normativas predefinidas que la organización activó. Cada objeto incluye normative_id y normative_clause_id. |
categories | array of integers | No | Identificadores de categorías predefinidas. |
themes | array of integers | No | Identificadores de temas predefinidos. |
tags | array of integers | No | Identificadores de etiquetas predefinidas. |
catalog_id | integer | Sí | Catálogo donde se guarda el contenido. |
estimated_minutes | integer (>= 0) | Sí | Minutos estimados de lectura. |
presentation_image_url | string | No | Imagen de presentación. Puede ser un archivo de la plataforma (predefinido o de la organización) o una dirección https. |
content | object | Sí | Textos de cada idioma, identificados por su código (por ejemplo, es-ar). |
Las categorías, temas, etiquetas y normativas deben ser predefinidas y estar disponibles para la organización. El contenido solo puede guardarse en un catálogo de la aplicación.
Ejemplo de solicitud (newsletter)
{
"active": false,
"difficulty": "medium",
"compliance_mappings": [
{ "normative_id": 0, "normative_clause_id": 0 }
],
"categories": [0],
"themes": [0],
"tags": [0],
"catalog_id": 0,
"estimated_minutes": 5,
"presentation_image_url": "https://www.ejemplo.com/imagen.png",
"content": {
"es-ar": { }
}
}Reemplace los valores
0por los identificadores reales de su organización. La estructura interna de cada idioma dentro decontentdepende del tipo de contenido. Para newsletters y momentos educativos corresponde al esquema EmailTextsRequest. Consulte el detalle de cada esquema en la documentación oficial de la API.
Manejo de imágenes
Las imágenes pueden indicarse de dos formas:
- Archivo de la plataforma: un archivo predefinido o propio de la organización.
- Dirección https: una URL en el puerto 443 de un servidor público.
Cuando utiliza una dirección https, la plataforma descarga la imagen durante la misma solicitud, antes de crear el contenido. La imagen se guarda como imagen de la organización, igual que si se hubiera subido desde la pantalla. De este modo, el contenido no depende del sitio de origen.
Si una misma dirección aparece en varios campos o idiomas, se descarga una sola vez.
Límites de las imágenes
| Límite | Valor |
|---|---|
| Formatos aceptados | PNG, JPEG y GIF |
| Tamaño máximo por imagen | 4 MB |
| Píxeles máximos | 25 millones |
| Cuadros máximos (GIF) | 100 |
| Direcciones por contenido | Hasta 10 |
| Redirecciones por dirección | Hasta 3 |
| Tiempo máximo de descarga | 12 segundos (todas las descargas) |
Importante: si una imagen no puede descargarse, la respuesta indica el campo afectado y el contenido no se crea.
Respuesta exitosa
Si la solicitud es correcta, la API responde con el código 201 y el siguiente cuerpo:
{
"content_code": "string",
"content_type": "string",
"name": "string"
}| Campo | Descripción |
|---|---|
content_code | Código del contenido. Es el valor que recibe la API de escritura de campañas para asignar el contenido a una campaña. |
content_type | Tipo de contenido, igual que en la ruta. |
name | Nombre del contenido. |
Guarde el content_code. Lo necesitará para asignar el contenido a una campaña mediante la API.
Códigos de error
| Código | Significado |
|---|---|
| 400 | El JSON no es válido o referencia algo que la organización no puede usar. La respuesta indica qué campo y por qué. |
| 405 | La API todavía no crea contenidos de ese tipo. |
| 429 | La aplicación superó la cantidad de solicitudes permitidas por minuto, o hay demasiadas descargas de imágenes en curso. El encabezado Retry-After indica cuántos segundos esperar antes de reintentar. |
💡 Mejores prácticas
- Cree los contenidos con
"active": falsepara revisarlos en la plataforma antes de usarlos en campañas. - Asigne a la aplicación solo el scope write_contents_create si su única función es crear contenidos.
- Verifique que los idiomas del JSON estén activos en la organización antes de enviar la solicitud.
- Aloje las imágenes en servidores públicos y estables, con respuesta rápida, para no superar el límite de 12 segundos.
- Optimice el peso de las imágenes antes de enviarlas para evitar rechazos por tamaño.
- Ante un error 429, respete el tiempo indicado en Retry-After antes de reintentar.
- Registre el content_code de cada contenido creado para automatizar luego la creación de campañas.