Códigos de Acceso

Esta sección documenta los endpoints para realizar cargas y revocaciones masivas de códigos de acceso mediante archivos CSV en MEDISMART 3.0, y para consultar el estado de esos procesos.

Un código de acceso permite que una persona se registre y quede automáticamente asociada a uno o más planes al canjearlo, sin necesidad de que un administrador cree la cuenta manualmente.

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.

Importar Códigos de Acceso

Este endpoint permite crear múltiples códigos de acceso desde un archivo CSV y asociarlos a uno o más planes. El proceso se ejecuta en segundo plano (background) — la respuesta inmediata solo confirma que el proceso fue iniciado, no el resultado final de la carga.

Endpoint


POST /backoffice/api/client/users/access-codes/import/file

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 con los códigos de acceso a crear
`plans`	string	Sí	Arreglo JSON con los IDs de los planes a los que se asociarán los códigos

Importante: Todos los planes indicados en plans deben pertenecer a tu propia empresa (tenant). Si algún plan pertenece a otra empresa, la solicitud es rechazada con 403 antes de procesar el archivo.

Formato del Archivo CSV

El archivo CSV debe tener codificación UTF-8, un tamaño máximo de 30MB, y contener las siguientes columnas (el nombre de columna no distingue mayúsculas/minúsculas ni espacios extra):

Columna	Tipo	Requerido	Descripción
`code`	string	Sí	El código de acceso. Debe ser único — no puede repetirse dentro del archivo ni existir ya en el sistema
`first_name`	string	Sí	Nombre asociado al código (referencial, se muestra en el reporte de resultados)
`last_name`	string	Sí	Apellido asociado al código (referencial, se muestra en el reporte de resultados)
`expires_at`	string	No	Fecha de expiración del código, formato estricto `YYYY-MM-DD` (ej: `2026-12-31`). Si se omite, el código no expira

Validaciones

Cada fila del CSV se valida antes de intentar crear el código. Una fila que falla cualquiera de estas validaciones no se crea, pero no detiene el procesamiento del resto del archivo:

code, first_name y last_name son obligatorios y no pueden estar vacíos
code no puede repetirse dentro del mismo archivo — si dos filas tienen el mismo código, ambas son rechazadas
code no puede coincidir con un código ya existente en el sistema (de cualquier carga anterior)
expires_at, si se envía, debe cumplir estrictamente el formato YYYY-MM-DD — otros formatos (31/12/2026, 12-31-2026, etc.) son rechazados, no se intenta interpretarlos
expires_at, si se envía, debe ser una fecha posterior a hoy

Ejemplo de Archivo CSV


code,first_name,last_name,expires_at
ABC12345,Juan,Pérez,2026-12-31
XYZ98765,María,Gómez,
PROMO2026,Carlos,Soto,2026-06-30

Ejemplo de Solicitud


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

Respuestas

Respuesta Exitosa

Cuando la solicitud es aceptada, el sistema inicia la carga en segundo plano y retorna inmediatamente:


{
    "success": true,
    "message": "Process initiated successfully. 3 access codes will be processed in background.",
    "data": {
        "processId": "691fe85220099b6a665d8c85",
        "sessionId": "bulk-user-creation-1763698765988",
        "totalCodes": 3,
        "inputFileUrl": "https://chile-dev.s3.us-east-1.amazonaws.com/bulk-users/2026-09-17/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 códigos serán procesados
data.processId: ID único del proceso. Úsalo para consultar el estado con los endpoints de abajo
data.sessionId: ID de sesión único para esta carga
data.totalCodes: Número total de filas leídas del CSV (incluye filas que luego serán rechazadas por validación)
data.inputFileUrl: URL del archivo CSV original almacenado, para referencia
data.status: Estado inicial del proceso, siempre "processing" en esta respuesta

Nota: Esta respuesta no indica cuántos códigos se crearon exitosamente. Usa GET .../users/import/status/{processId} con el processId recibido para conocer el resultado final (ver sección siguiente).

Notas Importantes

El token de acceso (access_token) debe ser válido y no expirado
El archivo debe ser un CSV real (Content-Type: text/csv o extensión .csv), tamaño máximo 30MB
Los IDs de planes deben ser válidos, existir en el sistema y pertenecer a tu empresa
El proceso se ejecuta de forma asíncrona — guarda el processId para consultar el resultado posteriormente
Por seguridad, el código en texto plano no se expone de vuelta en ningún endpoint de consulta de estado — solo se muestra parcialmente enmascarado (ej: AB***45)
Todas las solicitudes deben realizarse sobre HTTPS

Códigos de Estado HTTP

202 - Solicitud aceptada, el proceso fue encolado
400 - Solicitud inválida (archivo faltante, plans faltante o mal formado, etc.)
401 - Token de autorización inválido o expirado
403 - Alguno de los planes indicados no pertenece a tu empresa
404 - Alguno de los planes indicados no existe
500 - Error interno del servidor

Revocar Códigos de Acceso

Este endpoint permite revocar múltiples códigos de acceso desde un archivo CSV. Un código revocado deja de poder canjearse. El proceso se ejecuta en segundo plano (background) — la respuesta inmediata solo confirma que el proceso fue iniciado, no el resultado final de la revocación.

Endpoint


POST /backoffice/api/client/users/access-codes/revoke/file

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 con los códigos de acceso a revocar

Importante: Solo puedes revocar códigos de tu propia empresa (tenant). Un código que pertenece a otra empresa es rechazado como si no existiera.

Formato del Archivo CSV

El archivo CSV debe tener codificación UTF-8, un tamaño máximo de 30MB, y contener la siguiente columna (el nombre de columna no distingue mayúsculas/minúsculas ni espacios extra):

Columna	Tipo	Requerido	Descripción
`code`	string	Sí	El código de acceso a revocar. No distingue mayúsculas/minúsculas

Validaciones

Cada fila del CSV se valida antes de revocar. Una fila que falla cualquiera de estas validaciones no se revoca, pero no detiene el procesamiento del resto del archivo:

code es obligatorio y no puede estar vacío
code debe existir en el sistema y pertenecer a tu empresa
code no puede estar ya revocado
code no puede estar ya canjeado — un código canjeado no se puede revocar
code no puede repetirse dentro del mismo archivo — la primera aparición se procesa y las repeticiones se rechazan

Ejemplo de Archivo CSV


code
ABC12345
XYZ98765
PROMO2026

Ejemplo de Solicitud


curl --location 'https://qa-serv.medibuslive.com/backoffice/api/client/users/access-codes/revoke/file' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--form 'file=@"/ruta/al/archivo/revoke-codes.csv"'

Respuestas

Respuesta Exitosa

Cuando la solicitud es aceptada, el sistema inicia la revocación en segundo plano y retorna inmediatamente:


{
    "success": true,
    "message": "Process initiated successfully. 3 access codes will be processed in background.",
    "data": {
        "processId": "691fe85220099b6a665d8c99",
        "sessionId": "bulk-user-creation-1763698799123",
        "totalCodes": 3,
        "inputFileUrl": "https://chile-dev.s3.us-east-1.amazonaws.com/bulk-users/ALL/2026-10-09/bulk-user-creation-1763698799123/bulk-user-creation-1763698799123-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 códigos serán procesados
data.processId: ID único del proceso. Úsalo para consultar el estado con el endpoint de la sección siguiente
data.sessionId: ID de sesión único para este proceso
data.totalCodes: Número total de filas leídas del CSV (incluye filas que luego serán rechazadas por validación)
data.inputFileUrl: URL del archivo CSV original almacenado, para referencia
data.status: Estado inicial del proceso, siempre "processing" en esta respuesta

Nota: Esta respuesta no indica cuántos códigos se revocaron. Usa GET .../users/import/status/{processId} con el processId recibido para conocer el resultado final (ver sección siguiente).

Notas Importantes

El token de acceso (access_token) debe ser válido y no expirado
El archivo debe ser un CSV real (Content-Type: text/csv o extensión .csv), tamaño máximo 30MB y debe incluir la columna code
El proceso se ejecuta de forma asíncrona — guarda el processId para consultar el resultado posteriormente
La revocación no se puede deshacer desde la API
Todas las solicitudes deben realizarse sobre HTTPS

Códigos de Estado HTTP

202 - Solicitud aceptada, el proceso fue encolado
400 - Solicitud inválida (archivo faltante, columna code ausente, etc.)
401 - Token de autorización inválido o expirado
500 - Error interno del servidor

Consultar Estado del Proceso

Este es el mismo endpoint que se usa para consultar el estado de cargas y bajas de usuarios (ver Cargas y Bajas) — funciona para cualquier tipo de proceso masivo, incluyendo la importación y la revocación de códigos de acceso.

Endpoint


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

Parámetros de Ruta

Parámetro	Tipo	Requerido	Descripción
`processId`	string	Sí	ID del proceso obtenido en la respuesta de `POST .../access-codes/import/file` o `POST .../access-codes/revoke/file`

Ejemplo de Solicitud


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

Respuestas

Respuesta Exitosa (proceso completado)


{
    "success": true,
    "data": {
        "processId": "691fe85220099b6a665d8c85",
        "processType": "access_code_import",
        "status": "completed",
        "totalUsers": 3,
        "successfulUsers": 2,
        "failedUsers": 1,
        "totalChunks": 1,
        "chunksCompleted": 1,
        "rowStatusCounts": {
            "created": 2,
            "rejected_validation": 1
        },
        "originalFileName": "access-codes.csv",
        "inputFileUrl": "https://chile-dev.s3.us-east-1.amazonaws.com/bulk-users/.../input.csv",
        "resultFileUrl": "https://chile-dev.s3.us-east-1.amazonaws.com/bulk-users/.../results.xlsx",
        "createdAt": "2026-09-17T02:40:00.182Z",
        "updatedAt": "2026-09-17T02:40:02.129Z",
        "processedAt": "2026-09-17T02:40:02.127Z"
    }
}

Respuesta (proceso en progreso)


{
    "success": true,
    "data": {
        "processId": "691fe85220099b6a665d8c85",
        "processType": "access_code_import",
        "status": "processing",
        "totalUsers": 5000,
        "successfulUsers": 2000,
        "failedUsers": 0,
        "totalChunks": 10,
        "chunksCompleted": 4,
        "rowStatusCounts": {
            "created": 2000,
            "pending": 3000
        },
        "originalFileName": "access-codes.csv",
        "inputFileUrl": "https://chile-dev.s3.us-east-1.amazonaws.com/bulk-users/.../input.csv",
        "resultFileUrl": null,
        "createdAt": "2026-09-17T02:40:00.182Z",
        "updatedAt": "2026-09-17T02:40:05.900Z",
        "processedAt": null
    }
}

Descripción de la Respuesta

data.processId: ID del proceso consultado
data.processType: Tipo de proceso — "access_code_import" para importaciones y "access_code_revoke" para revocaciones
data.status: "processing", "completed" o "error"
data.totalUsers: Total de filas leídas del CSV original (el nombre del campo es genérico — para este tipo de proceso representa códigos, no usuarios)
data.successfulUsers / data.failedUsers: Totales acumulados de códigos procesados con éxito (creados o revocados) y fallidos (solo confiables cuando status es "completed")
data.totalChunks / data.chunksCompleted: Progreso del procesamiento por lotes internos. Cuando son iguales, el proceso terminó
data.rowStatusCounts: Conteo de filas por estado (pending, rejected_validation, error, y created en importaciones o revoked en revocaciones) — útil para mostrar una barra de progreso mientras el proceso corre
data.inputFileUrl: URL del CSV original que se subió
data.resultFileUrl: URL de un Excel con el detalle fila por fila (códigos enmascarados, nunca en texto plano) — null hasta que status es "completed"
data.createdAt / data.updatedAt / data.processedAt: Timestamps del proceso (ISO 8601). processedAt es null hasta que el proceso termina

Notas Importantes

Mientras data.status es "processing", sigue consultando este endpoint periódicamente (polling) hasta que cambie a "completed" o "error"
Solo puedes consultar procesos de tu propia empresa (tenant); consultar el processId de otra empresa retorna 403
Ningún endpoint devuelve el detalle código por código en JSON — para eso descarga resultFileUrl una vez que el proceso termina

Ejemplo: proceso de revocación completado


{
    "success": true,
    "data": {
        "processId": "691fe85220099b6a665d8c99",
        "processType": "access_code_revoke",
        "status": "completed",
        "totalUsers": 3,
        "successfulUsers": 2,
        "failedUsers": 1,
        "totalChunks": 1,
        "chunksCompleted": 1,
        "rowStatusCounts": {
            "revoked": 2,
            "rejected_validation": 1
        },
        "originalFileName": "revoke-codes.csv",
        "inputFileUrl": "https://chile-dev.s3.us-east-1.amazonaws.com/bulk-users/.../input.csv",
        "resultFileUrl": "https://chile-dev.s3.us-east-1.amazonaws.com/bulk-users/.../results.xlsx",
        "createdAt": "2026-10-09T02:40:00.182Z",
        "updatedAt": "2026-10-09T02:40:02.129Z",
        "processedAt": "2026-10-09T02:40:02.127Z"
    }
}

Códigos de Estado HTTP

200 - Solicitud exitosa
400 - processId faltante
401 - Token de autorización inválido o expirado
403 - El proceso consultado no pertenece a tu empresa
404 - Proceso no encontrado
500 - Error interno del servidor

Notas Importantes

Asincronía: La creación y la revocación de códigos de acceso siempre se procesan en segundo plano — usa el processId y el endpoint de consulta de estado para conocer el resultado final
Formato de fecha estricto: expires_at solo acepta YYYY-MM-DD. Cualquier otro formato es rechazado explícitamente, no se intenta adivinar
Códigos nunca en texto plano: La API nunca devuelve el código completo de vuelta — el detalle fila por fila (con códigos enmascarados) solo está disponible descargando el resultFileUrl una vez que el proceso termina
Unicidad: Un código no puede repetirse ni dentro del mismo archivo ni contra códigos ya existentes en el sistema, de cualquier carga anterior
Aislamiento por empresa: Solo puedes crear códigos para planes de tu propia empresa, revocar únicamente códigos de tu empresa, y consultar el estado de tus propios procesos
Códigos canjeados: Un código ya canjeado no se puede revocar; la fila queda rechazada en el reporte de resultados

Soporte

Si tienes preguntas sobre la carga o revocación de códigos de acceso, contacta al equipo de soporte:

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