API de Importación y Exportación de Usuarios

La API de Importación y Exportación de Usuarios permite operaciones masivas de usuarios para escenarios de migración, incorporación y copia de seguridad. Los administradores pueden importar usuarios desde archivos CSV o JSON y exportar el directorio completo de usuarios a cualquiera de los dos formatos.

Las operaciones de importación se procesan de forma asíncrona. Tras subir un archivo, el trabajo de importación avanza por fases de estado mientras se validan las filas y se crean los usuarios. Las operaciones de exportación también son asíncronas — una vez completadas, el archivo generado está disponible para descarga durante 24 horas.

Importar Usuarios

Subir Archivo de Importación

POST/api/users/importRequires: manage:users

Sube un archivo CSV o JSON que contiene registros de usuarios para importar. El archivo se valida y se crea un trabajo de importación. El procesamiento ocurre de forma asíncrona — consulta el estado del trabajo para seguir el progreso. El tamaño máximo del archivo es 10MB.

Cuerpo de la solicitud — multipart/form-data

Campo	Tipo	Requerido	Descripción
`file`	file	Sí	Archivo CSV o JSON (máx. 10MB). La extensión del archivo determina el formato

Respuesta exitosa


{
  "ok": true,
  "data": {
    "id": "imp_abc123",
    "fileName": "users-batch-2025-02.csv",
    "format": "csv",
    "status": "PENDING",
    "totalRows": 150,
    "processedRows": 0,
    "successCount": 0,
    "errorCount": 0,
    "errors": [],
    "createdAt": "2025-02-18T10:00:00Z",
    "updatedAt": "2025-02-18T10:00:00Z"
  }
}

Códigos de error

Código	HTTP	Descripción
`VALIDATION_ERROR`	400	Archivo faltante, formato no compatible, excede el límite de 10MB o el archivo está vacío
`PARSE_ERROR`	400	No se pudo analizar el archivo (CSV mal formado o estructura JSON inválida)

Listar Trabajos de Importación

GET/api/users/importRequires: manage:users

Lista todos los trabajos de importación del tenant. Los trabajos se ordenan por fecha de creación descendente. Usa esto para monitorear importaciones en curso o revisar el historial de importaciones pasadas.

Parámetros de consulta

Parámetro	Tipo	Descripción
`page`	integer	Número de página (por defecto: 1)
`limit`	integer	Elementos por página (por defecto: 20, máx.: 100)

Respuesta exitosa


{
  "ok": true,
  "data": {
    "data": [
      {
        "id": "imp_abc123",
        "fileName": "users-batch-2025-02.csv",
        "format": "csv",
        "status": "COMPLETED",
        "totalRows": 150,
        "processedRows": 150,
        "successCount": 142,
        "errorCount": 8,
        "createdAt": "2025-02-18T10:00:00Z",
        "updatedAt": "2025-02-18T10:05:00Z"
      },
      {
        "id": "imp_def456",
        "fileName": "migration-export.json",
        "format": "json",
        "status": "PARTIAL",
        "totalRows": 500,
        "processedRows": 500,
        "successCount": 487,
        "errorCount": 13,
        "createdAt": "2025-02-17T14:00:00Z",
        "updatedAt": "2025-02-17T14:12:00Z"
      },
      {
        "id": "imp_ghi789",
        "fileName": "bad-file.csv",
        "format": "csv",
        "status": "FAILED",
        "totalRows": 25,
        "processedRows": 3,
        "successCount": 0,
        "errorCount": 3,
        "createdAt": "2025-02-16T09:00:00Z",
        "updatedAt": "2025-02-16T09:00:30Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 3,
      "totalPages": 1
    }
  }
}

Obtener Detalle de Trabajo de Importación

GET/api/users/import/[id]Requires: manage:users

Recupera información detallada sobre un trabajo de importación, incluidos los detalles de errores por fila. Consulta este endpoint mientras el status sea PENDING o PROCESSING para seguir el progreso.

Respuesta exitosa


{
  "ok": true,
  "data": {
    "id": "imp_abc123",
    "fileName": "users-batch-2025-02.csv",
    "format": "csv",
    "status": "COMPLETED",
    "totalRows": 150,
    "processedRows": 150,
    "successCount": 142,
    "errorCount": 8,
    "errors": [
      {
        "row": 12,
        "email": "[email protected]",
        "error": "Email already exists in this tenant"
      },
      {
        "row": 34,
        "email": "invalid-email",
        "error": "Invalid email format"
      },
      {
        "row": 56,
        "email": "[email protected]",
        "error": "Role 'super_admin' does not exist"
      },
      {
        "row": 78,
        "email": "",
        "error": "Email is required"
      },
      {
        "row": 91,
        "email": "[email protected]",
        "error": "Email already exists in this tenant"
      },
      {
        "row": 102,
        "email": "[email protected]",
        "error": "Password does not meet minimum length requirement (8 characters)"
      },
      {
        "row": 119,
        "email": "eve@test",
        "error": "Invalid email format"
      },
      {
        "row": 133,
        "email": "[email protected]",
        "error": "Email already exists in this tenant"
      }
    ],
    "createdAt": "2025-02-18T10:00:00Z",
    "updatedAt": "2025-02-18T10:05:00Z"
  }
}

Códigos de error

Código	HTTP	Descripción
`NOT_FOUND`	404	El trabajo de importación no existe

Progresión del Estado de Importación

Los trabajos de importación avanzan por estos estados:

Estado	Descripción
`PENDING`	Archivo subido y validado, esperando que comience el procesamiento
`PROCESSING`	Las filas están siendo procesadas. `processedRows` se incrementa a medida que se gestiona cada fila
`COMPLETED`	Todas las filas procesadas correctamente (`errorCount` es 0)
`PARTIAL`	Todas las filas procesadas pero algunas tuvieron errores (`errorCount` > 0, `successCount` > 0)
`FAILED`	El procesamiento falló por completo (corrupción del archivo, error del sistema o todas las filas tuvieron errores)

Para importaciones grandes (más de 500 filas), el procesamiento puede tardar varios minutos. Consulta el endpoint de detalle del trabajo cada 2-3 segundos para seguir el progreso. El campo processedRows se actualiza en tiempo real.

Formatos de Archivo de Importación

Formato CSV

La primera fila debe ser una fila de encabezado con los nombres de las columnas. El orden de las columnas no importa. Las columnas se emparejan por nombre (sin distinguir mayúsculas de minúsculas).


email,firstName,lastName,roles,password
[email protected],Jane,Doe,editor,SecurePass123!
[email protected],Bob,Smith,"editor,viewer",AnotherPass456!
[email protected],Alice,Johnson,admin,
[email protected],Carol,Williams,,

Los roles múltiples se separan por comas entre comillas: "editor,viewer"
El campo de contraseña vacío significa que el usuario debe usar magic link o restablecer la contraseña para definir una
El campo de roles vacío significa que el usuario se crea sin roles asignados

Formato JSON

El archivo debe contener un array JSON de objetos de usuario en el nivel superior.


[
  {
    "email": "[email protected]",
    "firstName": "Jane",
    "lastName": "Doe",
    "roles": ["editor"],
    "password": "SecurePass123!"
  },
  {
    "email": "[email protected]",
    "firstName": "Bob",
    "lastName": "Smith",
    "roles": ["editor", "viewer"],
    "password": "AnotherPass456!"
  },
  {
    "email": "[email protected]",
    "firstName": "Alice",
    "lastName": "Johnson",
    "roles": ["admin"]
  },
  {
    "email": "[email protected]",
    "firstName": "Carol",
    "lastName": "Williams"
  }
]

Referencia de Campos

Campo	Tipo	Requerido	Descripción
`email`	string	Sí	Dirección de email del usuario. Debe ser única dentro del tenant
`firstName`	string	No	Nombre del usuario
`lastName`	string	No	Apellido del usuario
`roles`	string/array	No	Nombre(s) de rol a asignar. Deben coincidir con roles existentes en el tenant
`password`	string	No	Contraseña inicial. Debe cumplir los requisitos de política de contraseñas del tenant

Las contraseñas son opcionales. Cuando se omiten, la cuenta de usuario se crea sin contraseña. El usuario debe usar un magic link o el flujo de restablecimiento de contraseña para definir su contraseña en el primer inicio de sesión. Este es el enfoque recomendado para importaciones masivas.

Manejo de Errores por Fila

Cada fila se procesa de forma independiente. Si una fila falla la validación, se omite y el error queda registrado. El procesamiento continúa con las filas restantes. Razones de error comunes:

Error	Descripción
`Email is required`	El campo `email` falta o está vacío
`Invalid email format`	La dirección de email no es sintácticamente válida
`Email already exists in this tenant`	Ya existe un usuario con este email
`Role 'X' does not exist`	El nombre de rol especificado no fue encontrado
`Password does not meet minimum length requirement`	La contraseña es más corta que el mínimo configurado del tenant
`Password does not meet complexity requirements`	La contraseña no cumple los requisitos de mayúsculas/minúsculas/números/caracteres especiales

Exportar Usuarios

Iniciar Exportación

POST/api/users/exportRequires: manage:users

Inicia una exportación de todos los usuarios del tenant. La exportación se ejecuta de forma asíncrona — consulta el estado del trabajo de exportación o el endpoint de listado para saber cuándo el archivo está listo para descargar.

Cuerpo de la solicitud


{
  "format": "csv"
}

Campo	Tipo	Requerido	Descripción
`format`	string	Sí	Formato de salida: `csv` o `json`

Respuesta exitosa


{
  "ok": true,
  "data": {
    "id": "exp_abc123",
    "format": "csv",
    "status": "PENDING",
    "totalUsers": 0,
    "createdAt": "2025-02-18T11:00:00Z",
    "expiresAt": "2025-02-19T11:00:00Z"
  }
}

Las contraseñas nunca se incluyen en las exportaciones. Los hashes de contraseñas son no reversibles y se excluyen por razones de seguridad. Los usuarios exportados que se importen en otro tenant deberán definir nuevas contraseñas.

Listar Trabajos de Exportación

GET/api/users/exportRequires: manage:users

Lista todos los trabajos de exportación del tenant. Los trabajos se ordenan por fecha de creación descendente.

Parámetros de consulta

Parámetro	Tipo	Descripción
`page`	integer	Número de página (por defecto: 1)
`limit`	integer	Elementos por página (por defecto: 20, máx.: 100)

Respuesta exitosa


{
  "ok": true,
  "data": {
    "data": [
      {
        "id": "exp_abc123",
        "format": "csv",
        "status": "COMPLETED",
        "totalUsers": 342,
        "createdAt": "2025-02-18T11:00:00Z",
        "expiresAt": "2025-02-19T11:00:00Z"
      },
      {
        "id": "exp_def456",
        "format": "json",
        "status": "COMPLETED",
        "totalUsers": 342,
        "createdAt": "2025-02-15T09:00:00Z",
        "expiresAt": "2025-02-16T09:00:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 2,
      "totalPages": 1
    }
  }
}

Descargar Archivo de Exportación

GET/api/users/export/[id]/downloadRequires: manage:users

Descarga el archivo de exportación generado. Devuelve una respuesta binaria con los encabezados Content-Type y Content-Disposition apropiados. El archivo está disponible durante 24 horas después de que la exportación se complete.

Encabezados de respuesta


Content-Type: text/csv (or application/json)
Content-Disposition: attachment; filename="users-export-2025-02-18.csv"

El cuerpo de la respuesta es el contenido sin procesar del archivo (CSV o JSON), no envuelto en el sobre estándar { ok, data }.

Códigos de error

Código	HTTP	Descripción
`NOT_FOUND`	404	El trabajo de exportación no existe
`NOT_READY`	400	La exportación aún está procesando (el estado es `PENDING`)
`EXPIRED`	410	El archivo de exportación ha expirado y sido eliminado (pasadas las 24 horas)

Progresión del Estado de Exportación

Estado	Descripción
`PENDING`	Trabajo de exportación creado, generación del archivo en progreso
`COMPLETED`	Archivo generado y listo para descargar
`FAILED`	La generación del archivo falló (error del sistema)

Campos Exportados

El archivo de exportación contiene los siguientes campos para cada usuario:

Campo	Columna CSV	Clave JSON	Descripción
Email	`email`	`email`	Dirección de email del usuario
Nombre	`firstName`	`firstName`	Nombre del usuario
Apellido	`lastName`	`lastName`	Apellido del usuario
Roles	`roles`	`roles`	Nombres de rol separados por comas (CSV) o array de strings (JSON)
Email Verificado	`emailVerified`	`emailVerified`	Si el email ha sido verificado
Habilitado	`isEnabled`	`isEnabled`	Si la cuenta está activa
Creado el	`createdAt`	`createdAt`	Timestamp ISO 8601 de creación de la cuenta
Último inicio de sesión	`lastLoginAt`	`lastLoginAt`	Timestamp ISO 8601 del inicio de sesión más reciente, o vacío/null

Ejemplo de exportación CSV


email,firstName,lastName,roles,emailVerified,isEnabled,createdAt,lastLoginAt
[email protected],Jane,Doe,"admin,editor",true,true,2024-11-01T08:00:00Z,2025-02-18T09:30:00Z
[email protected],Bob,Smith,viewer,true,true,2024-12-15T10:00:00Z,2025-02-17T14:20:00Z
[email protected],Alice,Johnson,editor,false,true,2025-02-10T12:00:00Z,
[email protected],Carol,Williams,,true,false,2025-01-20T09:00:00Z,2025-01-25T11:00:00Z

Ejemplo de exportación JSON


[
  {
    "email": "[email protected]",
    "firstName": "Jane",
    "lastName": "Doe",
    "roles": ["admin", "editor"],
    "emailVerified": true,
    "isEnabled": true,
    "createdAt": "2024-11-01T08:00:00Z",
    "lastLoginAt": "2025-02-18T09:30:00Z"
  },
  {
    "email": "[email protected]",
    "firstName": "Bob",
    "lastName": "Smith",
    "roles": ["viewer"],
    "emailVerified": true,
    "isEnabled": true,
    "createdAt": "2024-12-15T10:00:00Z",
    "lastLoginAt": "2025-02-17T14:20:00Z"
  }
]

Los archivos de exportación expiran después de 24 horas y son eliminados permanentemente. Descarga el archivo rápidamente después de que se complete la generación. Siempre puedes iniciar una nueva exportación si es necesario.

Flujo de Trabajo de Migración

Una migración típica entre tenants sigue este patrón:

Exporta los usuarios del tenant de origen mediante POST /api/users/export con formato json.
Descarga el archivo de exportación mediante GET /api/users/export/[id]/download.
Opcionalmente edita el archivo para ajustar roles o eliminar usuarios.
Importa el archivo en el tenant de destino mediante POST /api/users/import.
Monitorea el trabajo de importación mediante GET /api/users/import/[id] hasta que el estado sea COMPLETED o PARTIAL.
Revisa los errores a nivel de fila en el array errors.
Notifica a los usuarios importados que definan sus contraseñas mediante magic link o restablecimiento de contraseña (ya que las contraseñas no se exportan).

Referencia de Permisos

Permiso	Descripción
`manage:users`	Subir archivos de importación, iniciar exportaciones, descargar archivos de exportación y ver el historial de trabajos

Las operaciones de importación y exportación se registran en el registro de auditoría con los tipos de evento user_import.created y user_export.created, incluyendo el nombre del archivo, el formato, el recuento de filas y el administrador que inició la operación.

Relacionado

Guía de Importación y Exportación — Tutorial paso a paso de migración
Importación y Exportación de Usuarios — Ejecuta importaciones y exportaciones desde la Consola
API de Usuarios — Endpoints de gestión individual de usuarios
API de Aprovisionamiento SCIM 2.0 — Alternativa de aprovisionamiento automatizado