Cargas y Bajas

Esta sección documenta el endpoint para realizar cargas masivas de usuarios mediante archivos CSV en MEDISMART 3.0.

Importar Usuarios

Este endpoint permite importar múltiples usuarios desde un archivo CSV y asignarlos a uno o más planes. El proceso se ejecuta en segundo plano (background) y la respuesta inmediata contiene información sobre el proceso iniciado.

Endpoint

POST /backoffice/api/client/users/import/file

URLs Base

• Entorno QA: https://qa-serv.medibuslive.com
• Entorno de Producción: https://serv.medibuslive.com

Headers

Authorization: Bearer {access_token}
Content-Type: multipart/form-data

Nota: El access_token debe ser obtenido previamente mediante el endpoint de autenticación OAuth2 documentado en la Referencia API.

Parámetros de Solicitud

Formato del Archivo CSV

El archivo CSV debe contener las siguientes columnas:

Importante:

• El campo username es obligatorio y debe ser único para cada usuario
• Si se proporciona email, el sistema requerirá que el usuario cambie su contraseña y verifique su identidad al primer inicio de sesión
• Si se proporciona password, se establecerá como contraseña inicial del usuario
• Si se proporciona email sin password, el sistema generará una contraseña temporal que el usuario deberá cambiar

Ejemplo de Archivo CSV

username,email,firstName,lastName,timezone,phoneNumber,birthDate,holder
johndoe,john.doe@example.com,John,Doe,America/Mexico_City,5551234567,1990-01-15,
janedoe,jane.doe@example.com,Jane,Doe,America/Mexico_City,5551234568,1992-05-20,johndoe
bobsmith,bob.smith@example.com,Bob,Smith,America/Mexico_City,5551234569,1988-03-10,
alicejones,,Alice,Jones,America/Mexico_City,5551234570,1995-07-25,

Ejemplo de Solicitud

curl --location 'https://qa-serv.medibuslive.com/backoffice/api/client/users/import/file' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--form 'file=@"/ruta/al/archivo/users.csv"' \
--form 'plans="[\"68d550de9ff532f6f6e78c6a\", \"68d54f0a9ff532f6f6e78902\"]"'

Respuestas

Respuesta Exitosa

Cuando la solicitud es aceptada, el sistema inicia el proceso de importación en segundo plano y retorna inmediatamente la siguiente respuesta:

{
    "success": true,
    "message": "Process initiated successfully. 2 users will be processed in background.",
    "data": {
        "processId": "691fe85220099b6a665d8c85",
        "sessionId": "bulk-user-creation-1763698765988",
        "totalUsers": 2,
        "inputFileUrl": "https://chile-dev.s3.us-east-1.amazonaws.com/bulk-users/2025-11-21/bulk-user-creation-1763698765988/bulk-user-creation-1763698765988-input.csv",
        "status": "processing"
    }
}

Descripción de la Respuesta

• success: Indica si la solicitud fue aceptada (true) o rechazada (false)
• message: Mensaje descriptivo que indica que el proceso fue iniciado y cuántos usuarios serán procesados
• data.processId: ID único del proceso de importación. Puede ser utilizado para consultar el estado del proceso
• data.sessionId: ID de sesión único para esta importación
• data.totalUsers: Número total de usuarios que serán procesados desde el archivo CSV
• data.inputFileUrl: URL del archivo CSV almacenado en S3 para referencia
• data.status: Estado actual del proceso. Inicialmente será "processing" cuando se inicia la importación

Nota: El proceso de importación se ejecuta de forma asíncrona en segundo plano. La respuesta inmediata confirma que el proceso ha sido iniciado, pero no indica el resultado final de la importación. Para conocer el estado final del proceso, deberás consultar el estado usando el processId proporcionado.

Notas Importantes

• El token de acceso (access_token) utilizado en el header Authorization debe ser válido y no expirado
• El archivo CSV debe tener codificación UTF-8
• Los IDs de planes deben ser válidos y existir en el sistema
• El proceso de importación se ejecuta de forma asíncrona en segundo plano
• La respuesta inmediata confirma que el proceso ha sido iniciado, pero no indica el resultado final
• Guarda el processId de la respuesta para poder consultar el estado del proceso posteriormente
• Si un usuario ya existe (basado en username), la importación de ese usuario fallará durante el procesamiento
• Cuando se proporciona email, el sistema automáticamente:
  • Establece passwordChangeRequired = true
  • Requiere verificación de identidad al primer inicio de sesión
• Cuando se proporciona username, el sistema establece usernameStatus = 'ACTIVE'
• Todas las solicitudes deben realizarse sobre HTTPS

Códigos de Estado HTTP

• 200 - Solicitud exitosa (puede incluir errores parciales)
• 400 - Solicitud inválida (archivo faltante, formato incorrecto, etc.)
• 401 - Token de autorización inválido o expirado
• 500 - Error interno del servidor

Crear Usuario Individual

Este endpoint permite crear un usuario individual de forma síncrona. A diferencia del endpoint de importación masiva, este endpoint procesa la solicitud inmediatamente y retorna el resultado de la creación del usuario.

Endpoint

POST /backoffice/api/client/users

URLs Base

• Entorno QA: https://qa-serv.medibuslive.com
• Entorno de Producción: https://serv.medibuslive.com

Headers

Authorization: Bearer {access_token}
Content-Type: application/json

Nota: El access_token debe ser obtenido previamente mediante el endpoint de autenticación OAuth2 documentado en la Referencia API.

Parámetros de Solicitud

El cuerpo de la solicitud debe ser un objeto JSON con la siguiente estructura:

Estructura del objeto user

Importante:

• Todos los campos del objeto user son opcionales, pero se recomienda proporcionar al menos username o email para identificar al usuario
• Si se proporciona email, debe ser un correo electrónico válido
• El campo username debe ser único en el sistema
• Si se proporciona password, se establecerá como contraseña inicial del usuario

Ejemplo de Solicitud

curl --location 'https://qa-serv.medibuslive.com/backoffice/api/client/users' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--data-raw '{
    "plans": ["68d3e8b89ff532f6f6e73ac8"],
    "user": {
      "username": "testuser123",
      "email": "test@example.com",
      "firstName": "Test",
      "lastName": "User",
      "password": "TestPass123",
      "phoneNumber": "+1234567890",
      "timezone": "America/New_York"
    }
}'

Respuestas

Respuesta Exitosa

Cuando el usuario es creado exitosamente, el sistema retorna la siguiente respuesta:

{
    "success": true,
    "message": "User created successfully",
    "data": {
        "userId": "efa20fca-d93e-493a-93a6-e05b2d5b3c3e",
        "username": "testuser123",
        "email": "test@example.com",
        "firstName": "Test",
        "lastName": "User",
        "plans": ["68d3e8b89ff532f6f6e73ac8"]
    }
}

Respuesta de Error

Si ocurre un error durante la creación del usuario:

{
    "success": false,
    "message": "Error creating user: Username already exists",
    "error": {
        "code": "DUPLICATE_USERNAME",
        "details": "The username 'testuser123' is already registered in the system"
    }
}

Descripción de la Respuesta

• success: Indica si la creación fue exitosa (true) o falló (false)
• message: Mensaje descriptivo del resultado de la operación
• data.userId: ID único del usuario creado en FusionAuth
• data.username: Nombre de usuario del usuario creado
• data.email: Correo electrónico del usuario creado
• data.firstName: Nombre del usuario
• data.lastName: Apellido del usuario
• data.plans: Arreglo de IDs de planes asignados al usuario

Notas Importantes

• El token de acceso (access_token) utilizado en el header Authorization debe ser válido y no expirado
• Este endpoint es síncrono, lo que significa que la respuesta se retorna inmediatamente después de procesar la solicitud
• A diferencia del endpoint de importación masiva, este endpoint crea un solo usuario a la vez
• Los IDs de planes deben ser válidos y existir en el sistema
• Si el username ya existe en el sistema, la creación fallará
• Si se proporciona email, el sistema puede requerir verificación de identidad al primer inicio de sesión
• Todas las solicitudes deben realizarse sobre HTTPS

Códigos de Estado HTTP

• 201 - Usuario creado exitosamente
• 400 - Solicitud inválida (datos faltantes o formato incorrecto)
• 401 - Token de autorización inválido o expirado
• 409 - Conflicto (usuario ya existe)

Baja Individual

Este endpoint permite desactivar un usuario individual de forma síncrona. A diferencia del endpoint de eliminación masiva, este endpoint procesa la solicitud inmediatamente y retorna el resultado de la desactivación del usuario.

Importante: Este endpoint desactiva el usuario (establece active = false), no lo elimina de la base de datos.

Endpoint

DELETE /backoffice/api/client/users

URLs Base

• Entorno QA: https://qa-serv.medibuslive.com
• Entorno de Producción: https://serv.medibuslive.com

Headers

Authorization: Bearer {access_token}

Nota: El access_token debe ser obtenido previamente mediante el endpoint de autenticación OAuth2 documentado en la Referencia API.

Parámetros de Query

*Importante: Debes proporcionar al menos uno de los dos parámetros (email o username). Si proporcionas ambos, el sistema buscará al usuario por cualquiera de los dos identificadores.

Ejemplo de Solicitud

Usando email

curl --location --request DELETE 'https://qa-serv.medibuslive.com/backoffice/api/client/users?email=rojash.camiloe%40gmail.com' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Usando username

curl --location --request DELETE 'https://qa-serv.medibuslive.com/backoffice/api/client/users?username=198801151' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Respuestas

Respuesta Exitosa (Usuario Desactivado)

Cuando el usuario es desactivado exitosamente, el sistema retorna la siguiente respuesta:

{
    "success": true,
    "message": "User deactivated successfully",
    "data": {
        "userId": "c3410674-2698-4f5c-982a-f0d5a0e891f9",
        "email": "rojash.camiloe@gmail.com",
        "username": "198801151",
        "active": false
    }
}

Respuesta (Usuario Ya Desactivado)

Si el usuario ya estaba desactivado previamente:

{
    "success": true,
    "message": "User is already deactivated",
    "data": {
        "userId": "c3410674-2698-4f5c-982a-f0d5a0e891f9",
        "email": "rojash.camiloe@gmail.com",
        "username": "19880115-1",
        "active": false
    }
}

Respuesta de Error

Si el usuario no se encuentra:

{
    "success": false,
    "message": "User not found in tenant"
}

Si no se proporciona ningún parámetro:

{
    "success": false,
    "message": "Either email or username query parameter is required"
}

Descripción de la Respuesta

• success: Indica si la desactivación fue exitosa (true) o falló (false)
• message: Mensaje descriptivo del resultado de la operación
• data.email: Correo electrónico del usuario desactivado
• data.username: Nombre de usuario del usuario desactivado
• data.active: Estado de activación del usuario (siempre false después de la desactivación)

Notas Importantes

• El token de acceso (access_token) utilizado en el header Authorization debe ser válido y no expirado
• Este endpoint es síncrono, lo que significa que la respuesta se retorna inmediatamente después de procesar la solicitud
• A diferencia del endpoint de eliminación masiva, este endpoint desactiva un solo usuario a la vez
• El usuario no se elimina de la base de datos, solo se marca como inactivo (active = false)
• Puedes usar email o username como parámetro de búsqueda, o ambos
• Si el usuario ya estaba desactivado, el endpoint retorna éxito con el mensaje “User is already deactivated”
• Los usuarios desactivados no podrán iniciar sesión en el sistema
• Todas las solicitudes deben realizarse sobre HTTPS

Códigos de Estado HTTP

• 200 - Usuario desactivado exitosamente o ya estaba desactivado
• 400 - Solicitud inválida (parámetros faltantes)
• 401 - Token de autorización inválido o expirado
• 404 - Usuario no encontrado
• 500 - Error interno del servidor

Eliminar Usuarios

Este endpoint permite eliminar múltiples usuarios desde un archivo CSV. El proceso se ejecuta en segundo plano (background) y la respuesta inmediata contiene información sobre el proceso iniciado.

Endpoint

DELETE /backoffice/api/client/users/import/file

URLs Base

• Entorno QA: https://qa-serv.medibuslive.com
• Entorno de Producción: https://serv.medibuslive.com

Headers

Authorization: Bearer {access_token}
Content-Type: multipart/form-data

Nota: El access_token debe ser obtenido previamente mediante el endpoint de autenticación OAuth2 documentado en la Referencia API.

Parámetros de Solicitud

Formato del Archivo CSV

El archivo CSV debe contener las siguientes columnas:

*Importante: Al menos uno de los dos campos (username o email) debe estar presente en cada fila. Puedes usar solo username, solo email, o ambos. Si ambos están presentes, el sistema buscará al usuario por cualquiera de los dos identificadores.

Ejemplo de Archivo CSV

username,email
9991229-2,john.doe@example.com
,jane.doe@example.com
bobsmith,

Ejemplo de Solicitud

curl --location --request DELETE 'https://qa-serv.medibuslive.com/backoffice/api/client/users/import/file' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--form 'file=@"/ruta/al/archivo/delete-users.csv"' \
--form 'emails="[\"admin@company.com\"]"'

Respuestas

Respuesta Exitosa

Cuando la solicitud es aceptada, el sistema inicia el proceso de eliminación en segundo plano y retorna inmediatamente la siguiente respuesta:

{
    "success": true,
    "message": "Deletion process initiated successfully. 2 users will be processed in background.",
    "data": {
        "processId": "69205285355c5c9afa58f081",
        "sessionId": "bulk-user-creation-1763725953289",
        "totalUsers": 2,
        "inputFileUrl": "https://chile-dev.s3.us-east-1.amazonaws.com/bulk-users/2025-11-21/bulk-user-creation-1763725953289/bulk-user-creation-1763725953289-input.csv",
        "status": "processing"
    }
}

Descripción de la Respuesta

• success: Indica si la solicitud fue aceptada (true) o rechazada (false)
• message: Mensaje descriptivo que indica que el proceso fue iniciado y cuántos usuarios serán procesados
• data.processId: ID único del proceso de eliminación. Puede ser utilizado para consultar el estado del proceso
• data.sessionId: ID de sesión único para esta eliminación
• data.totalUsers: Número total de usuarios que serán procesados desde el archivo CSV
• data.inputFileUrl: URL del archivo CSV almacenado en S3 para referencia
• data.status: Estado actual del proceso. Inicialmente será "processing" cuando se inicia la eliminación

Nota: El proceso de eliminación se ejecuta de forma asíncrona en segundo plano. La respuesta inmediata confirma que el proceso ha sido iniciado, pero no indica el resultado final de la eliminación. Para conocer el estado final del proceso, deberás consultar el estado usando el processId proporcionado.

Notas Importantes

• El token de acceso (access_token) utilizado en el header Authorization debe ser válido y no expirado
• El archivo CSV debe tener codificación UTF-8
• Al menos uno de los campos (username o email) debe estar presente en cada fila del CSV
• El proceso de eliminación se ejecuta de forma asíncrona en segundo plano
• La respuesta inmediata confirma que el proceso ha sido iniciado, pero no indica el resultado final
• Guarda el processId de la respuesta para poder consultar el estado del proceso posteriormente
• Puedes proporcionar emails adicionales mediante el parámetro emails además del archivo CSV
• Todas las solicitudes deben realizarse sobre HTTPS

Códigos de Estado HTTP

• 200 - Solicitud exitosa
• 400 - Solicitud inválida (archivo faltante, formato incorrecto, etc.)
• 401 - Token de autorización inválido o expirado
• 500 - Error interno del servidor

Consultar Estado del Proceso

Este endpoint permite consultar el estado y los resultados de un proceso de importación o eliminación de usuarios. Funciona para ambos tipos de procesos (cargas y bajas).

Endpoint

GET /backoffice/api/client/users/import/status/{processId}

URLs Base

• Entorno QA: https://qa-serv.medibuslive.com
• Entorno de Producción: https://serv.medibuslive.com

Headers

Authorization: Bearer {access_token}

Nota: El access_token debe ser obtenido previamente mediante el endpoint de autenticación OAuth2 documentado en la Referencia API.

Parámetros de Ruta

Ejemplo de Solicitud

curl --location 'https://qa-serv.medibuslive.com/backoffice/api/client/users/import/status/691fd10093aa9e3271c8a1c9' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Respuestas

Respuesta Exitosa (Proceso Completado)

{
    "success": true,
    "data": {
        "processId": "691fd10093aa9e3271c8a1c9",
        "processType": "deletion",
        "status": "completed",
        "totalUsers": 2,
        "successfulUsers": 1,
        "failedUsers": 1,
        "url": "salud-qa.medismart.live",
        "originalFileName": "delete-users.csv",
        "inputFileUrl": "https://chile-dev.s3.us-east-1.amazonaws.com/bulk-users/2025-11-21/bulk-user-creation-1763692795558/bulk-user-creation-1763692795558-input.csv",
        "resultFileUrl": "https://chile-dev.s3.us-east-1.amazonaws.com/bulk-users/2025-11-21/bulk-user-creation-1763692795558/bulk-user-creation-1763692795558-results.xlsx",
        "createdAt": "2025-11-21T02:40:00.182Z",
        "updatedAt": "2025-11-21T02:40:02.129Z",
        "processedAt": "2025-11-21T02:40:02.127Z"
    }
}

Respuesta (Proceso en Progreso)

{
    "success": true,
    "data": {
        "processId": "691fd10093aa9e3271c8a1c9",
        "processType": "import",
        "status": "processing",
        "totalUsers": 10,
        "successfulUsers": null,
        "failedUsers": null,
        "url": "salud-qa.medismart.live",
        "originalFileName": "users.csv",
        "inputFileUrl": "https://chile-dev.s3.us-east-1.amazonaws.com/bulk-users/2025-11-21/bulk-user-creation-1763692795558/bulk-user-creation-1763692795558-input.csv",
        "resultFileUrl": null,
        "createdAt": "2025-11-21T02:40:00.182Z",
        "updatedAt": "2025-11-21T02:40:01.500Z",
        "processedAt": null
    }
}

Descripción de la Respuesta

• success: Indica si la consulta fue exitosa (true) o falló (false)
• data.processId: ID único del proceso
• data.processType: Tipo de proceso ("import" para cargas o "deletion" para bajas)
• data.status: Estado actual del proceso:
  • "processing" - El proceso está en ejecución
  • "completed" - El proceso ha finalizado
  • "failed" - El proceso falló
• data.totalUsers: Número total de usuarios que se procesarán
• data.successfulUsers: Número de usuarios procesados exitosamente (solo disponible cuando el proceso está completado)
• data.failedUsers: Número de usuarios que no pudieron ser procesados (solo disponible cuando el proceso está completado)
• data.url: URL de la empresa asociada al proceso
• data.originalFileName: Nombre del archivo CSV original
• data.inputFileUrl: URL del archivo CSV de entrada almacenado en S3
• data.resultFileUrl: URL del archivo Excel con los resultados detallados (solo disponible cuando el proceso está completado)
• data.createdAt: Fecha y hora de creación del proceso (ISO 8601)
• data.updatedAt: Fecha y hora de última actualización del proceso (ISO 8601)
• data.processedAt: Fecha y hora de finalización del proceso (ISO 8601, solo disponible cuando el proceso está completado)

Notas Importantes

• El token de acceso (access_token) utilizado en el header Authorization debe ser válido y no expirado
• Puedes consultar el estado del proceso en cualquier momento usando el processId obtenido en la respuesta inicial
• Cuando el proceso está "processing", los campos successfulUsers, failedUsers, resultFileUrl y processedAt serán null
• Cuando el proceso está "completed", el archivo resultFileUrl contiene un archivo Excel con los detalles de cada usuario procesado, incluyendo errores si los hubo
• Todas las solicitudes deben realizarse sobre HTTPS

Códigos de Estado HTTP

• 200 - Solicitud exitosa
• 401 - Token de autorización inválido o expirado
• 404 - Proceso no encontrado
• 500 - Error interno del servidor

Soporte

Si tienes preguntas sobre la importación o eliminación de usuarios, contacta al equipo de soporte:

• Email: soporte@medismart.com
• Documentación API: Referencia API