Este artículo explica cómo dar de alta y actualizar hasta 1.000 usuarios por solicitud mediante la API de SMARTFENSE, y cómo consultar el resultado de cada operación.
Para qué sirve
Los usuarios pueden cargarse desde la interfaz administrativa o mediante las distintas fuentes de importación y sincronización. La API de alta y actualización masiva suma un camino pensado para los casos en que un sistema externo decide quién debe existir en la plataforma: un sistema de recursos humanos, un proceso de onboarding o una integración propia de la organización o del partner.
La operación funciona en dos pasos:
-
Enviar los usuarios con
POST /api/v1/users/bulk-upsert. La plataforma valida la solicitud y la encola. -
Consultar el resultado con
GET /api/v1/users/bulk-upsert/{request_id}, usando el identificador devuelto en el paso anterior.
Antes de empezar
Necesita una aplicación registrada en Configuración > Integraciones > Aplicaciones registradas. El procedimiento completo de registro está en Integración de APIs en SMARTFENSE.
Seleccione los siguientes alcances según lo que necesite la integración:
| Alcance | Para qué se usa |
|---|---|
write_users |
Obligatorio. Crear y actualizar usuarios, y consultar el estado de la operación. |
read_users |
Consultar el listado de usuarios. |
read_groups |
Listar los grupos existentes. |
write_groups |
Crear grupos con POST /api/v1/groups. |
La API admite los flujos OAuth 2.0 Authorization code y Client Credentials. Para integraciones servidor a servidor se recomienda Client Credentials.
Todas las solicitudes se realizan sobre la URL base
https://tenant.takesecurity.com/. Reemplacetenantpor el subdominio de su instancia de SMARTFENSE.
Paso 1 — Enviar los usuarios
POST /api/v1/users/bulk-upsert Content-Type: application/json Authorization: Bearer <token>
El cuerpo contiene la lista users, con entre 1 y 1.000 registros:
{
"users": [
{
"username": "ana.perez",
"first_name": "Ana",
"last_name": "Pérez",
"email": "ana.perez@ejemplo.com",
"group": "Finanzas",
"is_active": true,
"language_code": "es-ar"
},
{
"username": "juan.gomez",
"group": "Comité de Seguridad"
}
]
}En el ejemplo, el primer registro crea un usuario nuevo y el segundo agrega un grupo a un usuario existente.
Alta o actualización
Cada usuario se identifica por su username:
- Si el username no existe, la plataforma crea el usuario. El registro debe traer todos los campos.
- Si el username existe, solo se modifican los campos enviados. Un campo omitido conserva su valor actual.
Un registro que solo trae el
usernamese rechaza conNO_UPDATE_FIELDS, porque no indica nada para modificar.
Campos del registro
| Campo | Tipo | Descripción |
|---|---|---|
username |
string, hasta 150 caracteres | Obligatorio siempre. Identidad del usuario. |
first_name |
string, hasta 150 caracteres | Nombre. Obligatorio al crear. |
last_name |
string, hasta 150 caracteres | Apellido. Obligatorio al crear. |
email |
string, hasta 254 caracteres | Correo. Obligatorio al crear. |
group |
string, hasta 150 caracteres | Nombre de un grupo existente. Obligatorio al crear. |
is_active |
boolean | Estado del usuario. Obligatorio al crear. |
language_code |
string | Idioma del usuario. Obligatorio al crear. |
username
- Se eliminan los espacios al comienzo y al final, y se convierte a minúsculas. La búsqueda no distingue mayúsculas de minúsculas.
- No puede contener espacios ni caracteres de control, ni comenzar con
=,+,-,@, coma o punto y coma, ni contener<,>o&. - Para crear un usuario, solo admite letras, números y los caracteres
@ . + - _.
Esta operación nunca cambia el username de una cuenta existente, salvo para llevarlo a minúsculas.
first_name y last_name
No admiten caracteres de control, los prefijos =, +, -, @, coma o punto y coma, ni los caracteres <, >, & o el espacio de no separación.
- Se guarda en minúsculas.
- No puede pertenecer a otro usuario de la plataforma ni repetirse entre dos usuarios de la misma solicitud. En ambos casos el registro falla con
USER_CONFLICT. -
No es la identidad del usuario. La identidad es el
username.
group
- La asignación es aditiva: se agrega el grupo indicado y se conservan los grupos que el usuario ya tenía.
- El grupo no se crea desde este endpoint. Si no existe, el registro falla con
GROUP_NOT_FOUND. Créelo antes conPOST /api/v1/groups.
Para quitar usuarios de un grupo, consulte Cómo agregar y quitar usuarios de un grupo por API.
is_active
Debe ser un booleano JSON (true o false), no un texto.
language_code
Debe ser uno de estos códigos, sin distinguir mayúsculas de minúsculas:
ar-sa, id-id, ms-my, bg-bg, ca-ca, cs-cz, da-dk, de-de, et-ee, el-gr, en-au, en-nz, en-gb, en-us, es-ar, es-es, es-eu, es-me, fr-ca, fr-fr, gl-gl, ko-kr, hi-in, hr-hr, it-it, he-il, sw-ke, lv-lv, lt-lt, hu-hu, nl-nl, ja-jp, nb-no, pt-br, pl-pl, pt-pt, ro-ro, ru-ru, sq-al, sk-sk, sl-si, sr-latn, fi-fi, sv-se, th-th, vi-vn, tr-tr, uk-ua, zh-cn, zh-hk, zh-tw.
Si el usuario cambió su idioma desde la plataforma, el idioma enviado no se aplica y el registro no lo informa como cambio.
Valores no admitidos
- Los valores
null, vacíos o solo con espacios se rechazan conEMPTY_FIELD. - Un campo que no figura en la tabla anterior se rechaza con
UNKNOWN_FIELD. - Si un mismo
usernameaparece más de una vez en la solicitud, fallan todas sus apariciones conDUPLICATE_USERNAME.
Respuesta
Si la solicitud se puede leer, la plataforma responde 202 y encola la operación:
{
"request_id": "3f2b9a1e-6c1d-4f8e-9a77-1b2c3d...",
"status": "queued",
"status_url": "https://tenant.takesecurity.com/api/v1/users/bulk-upsert/3f2b9a1e-..."
}Guarde el request_id. Lo necesita para consultar el resultado.
Un
202indica que la solicitud fue aceptada, no que los usuarios ya se aplicaron. El resultado de cada registro se conoce en el paso 2.
Errores de la solicitud completa
Estos errores rechazan la solicitud entera. No se aplica ningún usuario.
| Código HTTP | Causa |
|---|---|
400 |
La solicitud no se puede leer: INVALID_JSON, INVALID_REQUEST, UNKNOWN_FIELD, MISSING_REQUIRED_FIELD, INVALID_FIELD_TYPE o EMPTY_FIELD. |
401 |
Falta el token o no es válido: AUTHENTICATION_REQUIRED, AUTHENTICATION_FAILED. |
403 |
El token no tiene el alcance write_users (PERMISSION_DENIED), o la organización está desactivada o vencida (TENANT_INACTIVE). |
413 |
Más de 1.000 usuarios (TOO_MANY_RECORDS) o más de 4 MB (PAYLOAD_TOO_LARGE). |
415 |
El tipo de contenido no es application/json. |
429 |
Se superó el límite de solicitudes. Espere los segundos indicados en el encabezado Retry-After antes de reintentar. |
Paso 2 — Consultar el resultado
GET /api/v1/users/bulk-upsert/{request_id}
Authorization: Bearer <token>Reemplace {request_id} por el identificador devuelto en el paso 1. Este endpoint también requiere el alcance write_users.
Un lote de 1.000 usuarios termina en pocos minutos como máximo. Consulte el estado cada 5 a 10 segundos hasta que la operación finalice.
Respuesta
{
"request_id": "3f2b9a1e-6c1d-4f8e-9a77-1b2c3d...",
"status": "completed",
"received_at": "2026-10-01T12:00:00Z",
"started_at": "2026-10-01T12:00:01Z",
"finished_at": "2026-10-01T12:00:31Z",
"progress": {
"processed": 1000,
"total": 1000
},
"totals": {
"received": 1000,
"created": 740,
"updated": 230,
"unchanged": 29,
"failed": 1
},
"errors": [ ... ]
}-
status: estado de la operación.
queuedindica que está encolada ycompletedque finalizó. - progress: cantidad de registros procesados sobre el total.
-
totals: resumen del resultado.
- created: usuarios creados.
- updated: usuarios existentes con al menos un campo modificado.
- unchanged: registros que no produjeron cambios, por ejemplo porque ya estaban aplicados.
- failed: registros rechazados.
- errors: detalle de los registros que fallaron, con su código de error.
El resultado de cada operación se puede consultar durante 30 días. Pasado ese plazo, la consulta responde
404.
Errores de la consulta
| Código HTTP | Causa |
|---|---|
401 |
Falta el token o no es válido: AUTHENTICATION_REQUIRED, AUTHENTICATION_FAILED. |
403 |
El token no tiene el alcance write_users (PERMISSION_DENIED), o la organización está desactivada o vencida (TENANT_INACTIVE). |
404 |
JOB_NOT_FOUND: el identificador no es válido, no existe una operación con ese identificador para esta aplicación, o venció su plazo de consulta. |
429 |
Se superó el límite de solicitudes. Espere los segundos indicados en Retry-After. |
La operación solo puede consultarse con la misma aplicación que la envió.
Cómo interpretar los errores por registro
Cada usuario se aplica completo o no se aplica. Un registro que falla no deja cambios a medias ni impide que se apliquen los demás.
| Código | Qué significa | Qué hacer |
|---|---|---|
MISSING_REQUIRED_FIELD |
Falta un campo obligatorio para crear el usuario. | Envíe todos los campos al crear. |
NO_UPDATE_FIELDS |
El registro solo trae el username. |
Agregue al menos un campo a modificar. |
EMPTY_FIELD |
Un campo es null, vacío o solo tiene espacios. |
Complete el valor u omita el campo. |
UNKNOWN_FIELD |
Se envió un campo que no se admite. | Use solo los campos documentados. |
INVALID_RECORD |
El registro no tiene un formato válido. | Revise la estructura del registro. |
INVALID_FIELD_TYPE |
Un campo tiene un tipo de dato incorrecto, por ejemplo is_active como texto. |
Envíe el tipo indicado en la tabla de campos. |
INVALID_USERNAME |
El username no cumple las reglas de formato. |
Revise los caracteres permitidos. |
INVALID_FIELD_VALUE |
Un valor no cumple las reglas del campo. | Revise las restricciones del campo. |
INVALID_EMAIL |
El correo no tiene un formato válido. | Corrija la dirección. |
UNSUPPORTED_LANGUAGE |
El language_code no está en la lista admitida. |
Use uno de los códigos listados. |
INVALID_GROUP_NAME |
El nombre de grupo no tiene un formato válido. | Revise el valor de group. |
GROUP_NOT_FOUND |
El grupo no existe. | Créelo antes con POST /api/v1/groups. |
AMBIGUOUS_GROUP_NAME |
El nombre no identifica un único grupo. | Verifique los grupos con ese nombre. |
DUPLICATE_USERNAME |
El username se repite en la misma solicitud. |
Envíe cada usuario una sola vez. |
USER_CONFLICT |
El correo pertenece a otro usuario o se repite en la solicitud, o el usuario cambió durante la operación. | Corrija el correo. Si el usuario cambió durante la operación, reenvíe el registro. |
INTERNAL_ERROR |
Error interno al procesar el registro. | Reenvíe el registro. |
NOT_PROCESSED |
El registro no llegó a procesarse. | Reenvíe el registro. |
INTERNAL_ERROR,NOT_PROCESSEDyUSER_CONFLICT(cuando el usuario cambió durante la operación) se resuelven reenviando el registro.
Reintentos y concurrencia
-
Repetir una solicitud es seguro. Nunca crea un usuario duplicado, ni duplica ni quita grupos. Los registros ya aplicados se informan como
unchanged. - Dos operaciones simultáneas sobre el mismo usuario se aplican una después de la otra. Prevalece la última, sin mezclar campos de las dos.
Límite de frecuencia
La plataforma puede limitar la cantidad de solicitudes por minuto de cada organización, contando todas las solicitudes a la API, no solo las de este endpoint. Si el límite está activo y se supera, la respuesta es 429 con el encabezado Retry-After. Espere esos segundos antes de reintentar.
💡 Mejores prácticas
- Crear los grupos antes de enviar los usuarios. Este endpoint no crea grupos y el registro falla con
GROUP_NOT_FOUND. - Enviar lotes de hasta 1.000 usuarios y controlar que el cuerpo no supere los 4 MB.
- Guardar el
request_idde cada envío y consultar el estado cada 5 a 10 segundos, sin superar ese ritmo. - Revisar siempre
totals.failedy el bloqueerrorsantes de dar por terminada la carga. - Reenviar solo los registros con
INTERNAL_ERROR,NOT_PROCESSEDoUSER_CONFLICTpor cambio concurrente. Reenviar el lote completo también es seguro, pero consume más solicitudes. - Usar un
usernameestable, que no cambie en el sistema de origen. La plataforma no lo modifica en cuentas existentes. - Enviar
is_activecomo booleano JSON y no como texto. - Respetar el encabezado
Retry-Afterante un429en lugar de reintentar de inmediato. - Registrar una aplicación por integración, con los alcances mínimos que esa integración necesita.