Gestión de Planes

Esta sección documenta los endpoints para asignar y dar de baja planes de forma masiva mediante archivos CSV en MEDISMART 3.0, y para consultar el estado de esos procesos.

Un plan se asigna a una persona como titular (holder) o como beneficiario (beneficiary) de un titular. Estos endpoints gestionan únicamente los planes de tu propio tenant: el tenant se determina a partir del token de acceso.

URLs Base

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

Headers Requeridos


Authorization: Bearer {access_token}

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

Asignar Planes (Alta Masiva)

Este endpoint permite asignar uno o más planes a múltiples personas desde un archivo CSV. 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/plans/bulk-add

Headers


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

Parámetros de Solicitud

Parámetro	Tipo	Requerido	Descripción
`file`	file	Sí	Archivo CSV (`.csv`, máximo 30 MB) con los documentos de las personas
`plansToAdd`	string	Sí	Arreglo JSON con los IDs de los planes a asignar (al menos uno)
`emails`	string	No	Arreglo JSON con los correos que recibirán el reporte del proceso

Nota: El tenant se obtiene del token de acceso. Cualquier tenantId enviado en la solicitud se ignora.

Formato del Archivo CSV

El archivo CSV debe tener una fila de encabezado.

Columna	Tipo	Requerido	Descripción
Primera columna (ej: `username`)	string	Sí	Documento de identidad de la persona según el país: RUT (Chile), CURP o RFC (México)
`holder`	string	No	Documento del titular. Si se informa, la persona se asigna como beneficiario de ese titular. Si se deja vacío, se asigna como titular

Importante:

La primera columna que no se llame holder se toma como el documento de la persona, sin importar su nombre de encabezado

El documento se valida y normaliza según el país de operación. Un documento con formato inválido (incluido un correo electrónico) falla solo en esa fila

Para asignar un beneficiario, el titular indicado debe tener activo el mismo plan

Cada plan define un máximo de beneficiarios por titular (max_number_of_beneficiaries). Si es 0, el plan no admite beneficiarios. Las filas se evalúan en el orden del archivo: las primeras entran hasta completar el cupo del titular y las siguientes fallan con error

Una persona no puede tener el mismo plan como titular y como beneficiario a la vez

Un plan inactivo no se puede asignar

La persona no necesita tener una cuenta creada para recibir la asignación

Ejemplo de Archivo CSV


username,holder
12345678-9,
98765432-1,12345678-9
11111111-1,

En este ejemplo, 12345678-9 y 11111111-1 se asignan como titulares y 98765432-1 como beneficiario de 12345678-9.

Ejemplo de Solicitud


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

Respuestas

Respuesta Exitosa


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

Descripción de la Respuesta

success: Indica si la solicitud fue aceptada (true) o rechazada (false)
message: Mensaje descriptivo con la cantidad de filas que serán procesadas
data.processId: ID único del proceso. Se usa para consultar su estado
data.sessionId: ID de sesión único del proceso
data.totalUsers: Número de filas del archivo que serán procesadas
data.inputFileUrl: URL del archivo CSV almacenado, para referencia
data.status: Estado inicial del proceso ("processing")

Nota: El proceso se ejecuta de forma asíncrona. La respuesta inmediata confirma que fue iniciado, pero no indica el resultado final. Guarda el processId para consultar el estado.

Resultado por Fila

Cada fila termina con uno de estos estados:

Estado	Descripción
`added`	El plan fue asignado
`error`	La fila no se pudo procesar. El detalle indica el motivo (documento inválido, titular sin el plan, plan inactivo, conflicto de rol, etc.)

Códigos de Estado HTTP

202 - Solicitud aceptada, el proceso se inició en segundo plano
400 - Solicitud inválida (archivo faltante o que no es CSV, plansToAdd vacío o con formato JSON inválido, CSV sin identificadores válidos)
401 - Token de autorización inválido o expirado
403 - El token no tiene acceso a un tenant
500 - Error interno del servidor

Dar de Baja Planes (Baja Masiva)

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

Importante: La baja de planes no elimina ni desactiva la cuenta de la persona. Solo quita su acceso a los planes indicados.

Endpoint


POST /backoffice/api/client/users/plans/bulk-remove

Headers


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

Parámetros de Solicitud

Parámetro	Tipo	Requerido	Descripción
`file`	file	Sí	Archivo CSV (`.csv`, máximo 30 MB) con los documentos de las personas
`plansToRemove`	string	Sí	Arreglo JSON con los IDs de los planes a quitar (al menos uno)
`emails`	string	No	Arreglo JSON con los correos que recibirán el reporte del proceso

Nota: El tenant se obtiene del token de acceso. Cualquier tenantId enviado en la solicitud se ignora.

Formato del Archivo CSV

El archivo CSV debe tener una fila de encabezado y una columna con el documento de la persona.

Columna	Tipo	Requerido	Descripción
Primera columna (ej: `username`)	string	Sí	Documento de identidad de la persona según el país

Nota: Si el archivo incluye una columna holder, se ignora. La baja siempre se aplica sobre el plan de la persona, sea titular o beneficiario.

Ejemplo de Archivo CSV


username
12345678-9
98765432-1

Ejemplo de Solicitud


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

Respuestas

Respuesta Exitosa


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

La descripción de los campos de la respuesta es la misma que en la alta masiva.

Reglas de la Baja

La baja es inmediata: la persona pierde el acceso al plan en el momento en que se procesa su fila
Si se da de baja a un titular, también se quita el plan a todos sus beneficiarios de ese plan. Esos beneficiarios no necesitan estar en el archivo
Si una persona tiene varios de los planes indicados, se le quitan todos
Los demás planes de un beneficiario (con otro titular) no se ven afectados
Si la persona se vuelve a asignar al plan después, sus beneficiarios no se restauran automáticamente: hay que asignarlos de nuevo

Resultado por Fila

Estado	Descripción
`removed`	Se quitó al menos un plan. Si era titular, el detalle incluye la cantidad de beneficiarios afectados en cascada (`cascadeCount`)
`no_active_membership`	La persona no tenía ninguno de los planes indicados activo. No es un error
`error`	La fila no se pudo procesar. El detalle indica el motivo (por ejemplo, documento con formato inválido)

Códigos de Estado HTTP

202 - Solicitud aceptada, el proceso se inició en segundo plano
400 - Solicitud inválida (archivo faltante o que no es CSV, plansToRemove vacío o con formato JSON inválido, CSV sin identificadores válidos)
401 - Token de autorización inválido o expirado
403 - El token no tiene acceso a un tenant
500 - Error interno del servidor

Consultar Estado de un Proceso

Permite consultar el avance y el resultado de una alta o baja masiva de planes usando el processId recibido al iniciarla.

Endpoint


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

Headers


Authorization: Bearer {access_token}

Parámetros de Ruta

Parámetro	Tipo	Requerido	Descripción
`processId`	string	Sí	ID del proceso obtenido al iniciar el alta o la baja masiva

Ejemplo de Solicitud


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

Respuestas

Respuesta Exitosa (Proceso Completado)


{
    "success": true,
    "data": {
        "processId": "691fe85220099b6a665d8c99",
        "processType": "plan_remove",
        "status": "completed",
        "totalUsers": 2,
        "successfulUsers": 1,
        "failedUsers": 0,
        "totalChunks": 1,
        "chunksCompleted": 1,
        "rowStatusCounts": {
            "removed": 1,
            "no_active_membership": 1
        },
        "url": "salud-qa.medismart.live",
        "originalFileName": "remove-plans.csv",
        "inputFileUrl": "https://chile-dev.s3.us-east-1.amazonaws.com/bulk-plans/2025-11-21/bulk-plan-remove-1763698765999/bulk-plan-remove-1763698765999-input.csv",
        "resultFileUrl": "https://chile-dev.s3.us-east-1.amazonaws.com/bulk-plans/2025-11-21/bulk-plan-remove-1763698765999/bulk-plan-remove-1763698765999-results",
        "createdAt": "2025-11-21T02:40:00.182Z",
        "updatedAt": "2025-11-21T02:40:02.129Z",
        "processedAt": "2025-11-21T02:40:02.127Z"
    }
}

Descripción de la Respuesta

data.processType: "plan_add" para altas o "plan_remove" para bajas
data.status: Estado del proceso:
- "processing" - El proceso está en ejecución
- "completed" - El proceso finalizó
- "error" - El proceso falló
data.totalUsers: Número de filas del archivo
data.successfulUsers: Filas procesadas con éxito
data.failedUsers: Filas con error
data.chunksCompleted / data.totalChunks: Avance del procesamiento (el archivo se procesa por lotes)
data.rowStatusCounts: Cantidad de filas por estado (added, removed, no_active_membership, error, y pending mientras no han sido procesadas)
data.inputFileUrl: URL del archivo CSV enviado
data.resultFileUrl: URL del archivo de resultados con el estado y el detalle de cada fila. Es null mientras el proceso no termina
data.errorMessage: Mensaje de error si el proceso falló

Nota: El detalle fila por fila se obtiene del archivo de resultFileUrl. Solo puedes consultar procesos de tu propio tenant; consultar uno de otro tenant devuelve 403.

Códigos de Estado HTTP

200 - Consulta exitosa
401 - Token de autorización inválido o expirado
403 - El proceso pertenece a otro tenant
404 - Proceso no encontrado
500 - Error interno del servidor