Skip to Content
Welcome to MEDISMART 3.0 Documentation 🚀
UsuariosObtener y Actualizar Usuarios

Obtener y Actualizar Usuarios

Esta sección documenta los endpoints para obtener y actualizar información de usuarios en MEDISMART 3.0

URLs Base

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

Headers Requeridos

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

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

Buscar Usuario

Este endpoint permite obtener información de un usuario mediante su email o username.

Endpoint

GET /backoffice/api/client/users

Parámetros de Consulta

ParámetroTipoRequeridoDescripción
emailstringOpcional*Correo electrónico del usuario
usernamestringOpcional*Nombre de usuario en el sistema

*Importante: Al menos uno de los dos parámetros (email o username) debe ser enviado en la solicitud. Ambos son opcionales individualmente, pero no pueden omitirse simultáneamente.

Ejemplos de Solicitud

Opción 1: Buscar por email

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

Opción 2: Buscar por username

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

Respuesta Exitosa

{
    "success": true,
    "message": "User found successfully",
    "data": {
        "userId": "c3410674-2698-4f5c-982a-f0d5a0e891f9",
        "email": "rojash.camiloe@gmail.com",
        "username": "198801151",
        "firstName": "Camilo",
        "lastName": "Rojas",
        "active": true,
        "verified": true,
        "plans": [
            {
                "plan_id": "68d3e8b89ff532f6f6e73ac8",
                "role": "holder",
                "holder": null
            }
        ]
    }
}

Descripción de la Respuesta

  • success: Indica si la solicitud fue exitosa (true) o falló (false)
  • message: Mensaje descriptivo del resultado de la operación
  • data.userId: Identificador único del usuario (UUID)
  • data.email: Correo electrónico del usuario
  • data.username: Nombre de usuario en el sistema
  • data.firstName: Primer nombre del usuario
  • data.lastName: Apellido del usuario
  • data.active: Indica si la cuenta del usuario está activa
  • data.verified: Indica si el correo electrónico del usuario ha sido verificado
  • data.plans: Array de planes asociados al usuario. Cada plan contiene:
    • plan_id: Identificador único del plan
    • role: Rol del usuario en el plan ("holder" para titular, "beneficiary" para beneficiario)
    • holder: Documento del titular (solo presente cuando role es "beneficiary")

Obtener Usuario por Username

Este endpoint permite obtener información de un usuario a partir de su username, con la posibilidad de incluir sus planes y/o sus beneficiarios de forma opcional. A diferencia de GET /client/users, la respuesta base solo trae los datos del usuario en FusionAuth — plans y beneficiaries únicamente se calculan y se incluyen en la respuesta si se solicitan explícitamente mediante el parámetro include.

Endpoint

GET /backoffice/api/client/users/{username}

Parámetros de Ruta

ParámetroTipoRequeridoDescripción
usernamestringSíNombre de usuario (documento) en el sistema

Parámetros de Consulta

ParámetroTipoRequeridoDescripción
includestringNoLista separada por comas de recursos adicionales a incluir en la respuesta. Valores soportados: plans, beneficiaries. Ejemplo: include=plans,beneficiaries

Ejemplos de Solicitud

Opción 1: Solo datos base del usuario

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

Opción 2: Incluyendo planes

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

Opción 3: Incluyendo planes y beneficiarios

curl --location 'https://qa-serv.medibuslive.com/backoffice/api/client/users/198801151?include=plans,beneficiaries' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Respuesta Exitosa (sin include)

{
    "success": true,
    "message": "User found successfully",
    "data": {
        "userId": "c3410674-2698-4f5c-982a-f0d5a0e891f9",
        "email": "rojash.camiloe@gmail.com",
        "username": "198801151",
        "firstName": "Camilo",
        "lastName": "Rojas",
        "active": true,
        "verified": true
    }
}

Respuesta Exitosa (con include=plans,beneficiaries)

{
    "success": true,
    "message": "User found successfully",
    "data": {
        "userId": "c3410674-2698-4f5c-982a-f0d5a0e891f9",
        "email": "rojash.camiloe@gmail.com",
        "username": "198801151",
        "firstName": "Camilo",
        "lastName": "Rojas",
        "active": true,
        "verified": true,
        "plans": [
            {
                "id": "68d3e8b89ff532f6f6e73ac8",
                "name": "Plan Salud Total",
                "role": "holder",
                "state": true
            }
        ],
        "beneficiaries": [
            {
                "username": "43893488K",
                "firstName": "Juan",
                "lastName": "Pérez",
                "plans": [
                    {
                        "id": "68d3e8b89ff532f6f6e73ac8",
                        "name": "Plan Salud Total"
                    }
                ]
            }
        ]
    }
}

Descripción de la Respuesta

  • success: Indica si la solicitud fue exitosa (true) o falló (false)
  • message: Mensaje descriptivo del resultado de la operación
  • data.userId: Identificador único del usuario (UUID)
  • data.email: Correo electrónico del usuario
  • data.username: Nombre de usuario en el sistema
  • data.firstName: Primer nombre del usuario
  • data.lastName: Apellido del usuario
  • data.active: Indica si la cuenta del usuario está activa
  • data.verified: Indica si el correo electrónico del usuario ha sido verificado
  • data.plans: (solo si se envía include=plans) Array con todos los planes del usuario, incluyendo los dados de baja. Cada plan contiene:
    • id: Identificador único del plan
    • name: Nombre del plan
    • role: Rol del usuario en el plan ("holder" para titular, "beneficiary" para beneficiario)
    • state: true si la membresía está activa, false si fue dada de baja
  • data.beneficiaries: (solo si se envía include=beneficiaries) Array con los beneficiarios del titular. Cada beneficiario contiene:
    • username: Documento/username del beneficiario
    • firstName: Primer nombre del beneficiario (si su cuenta en FusionAuth ya lo tiene registrado)
    • lastName: Apellido del beneficiario (si su cuenta en FusionAuth ya lo tiene registrado)
    • plans: Array de planes del beneficiario, cada uno con id y name

Respuesta de Error

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

Nota: Si plans y/o beneficiaries no pueden resolverse (por ejemplo, un error consultando planMemberships), la búsqueda del usuario no falla — la respuesta se degrada a un array vacío ([]) en el campo correspondiente en vez de devolver un error.

Actualizar Usuario

Este endpoint permite actualizar información de un usuario existente.

Endpoint

PATCH /backoffice/api/client/users/{userId}

Parámetros de Ruta

ParámetroTipoRequeridoDescripción
userIdstring (UUID)SíIdentificador único del usuario a actualizar

Cuerpo de la Solicitud

Todos los campos son opcionales. Solo se actualizarán los campos que se envíen en la solicitud.

{
    email?: string;        // Correo electrónico (debe ser válido)
    firstName?: string;    // Primer nombre
    lastName?: string;     // Apellido
    phoneNumber?: string;  // Número de teléfono
    holding?: string;          // Holding
    insurer?: string;          // Aseguradora
    broker?: string;           // Corredora
    policyNumber?: string;     // Número de póliza
    benefitClass?: string;     // Clase
    benefitSubClass?: string;  // Subclase
    businessArea?: string;     // Área
    productLine?: string;      // Línea de producto
    productSubLine?: string;   // Sublínea de producto
    plans?: Array<{        // Planes asociados al usuario
        plan_id: string;   // ID del plan (requerido)
        role?: "holder" | "beneficiary";  // Rol (opcional, por defecto "holder")
        holder?: string;   // Documento del titular (requerido si role es "beneficiary")
    }>;
}

Validaciones

  • email: Debe ser un correo electrónico válido si se proporciona
  • firstName: Debe ser una cadena de texto si se proporciona
  • lastName: Debe ser una cadena de texto si se proporciona
  • phoneNumber: Debe ser una cadena de texto si se proporciona
  • holding, insurer, broker, policyNumber, benefitClass, benefitSubClass, businessArea, productLine, productSubLine: Deben ser cadenas de texto si se proporcionan (ver Campos de póliza)
  • plans: Si se proporciona, debe cumplir con las siguientes reglas:
    • No puede ser un array vacío
    • Cada plan debe incluir plan_id
    • Si no se especifica role, se asume "holder" por defecto
    • Si role es "beneficiary", el campo holder (documento del titular) es requerido

Ejemplo de Solicitud

curl --location --request PATCH 'https://qa-serv.medibuslive.com/backoffice/api/client/users/c3410674-2698-4f5c-982a-f0d5a0e891f9' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--data-raw '{
    "email": "rojash.camiloe@gmail.com",
    "phoneNumber": "+56959218752"
}'

Ejemplo con Múltiples Campos

curl --location --request PATCH 'https://qa-serv.medibuslive.com/backoffice/api/client/users/c3410674-2698-4f5c-982a-f0d5a0e891f9' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--data-raw '{
    "email": "nuevo.email@example.com",
    "firstName": "Juan",
    "lastName": "Pérez",
    "phoneNumber": "+56912345678"
}'

Campos de póliza

Campos opcionales que describen la póliza bajo la cual está cubierto el usuario. Todos son string. Se envían y actualizan igual que phoneNumber: solo se modifican los campos incluidos en la solicitud.

CampoDescripciónEjemplos
holdingHolding o grupo al que pertenece el usuario
insurerAseguradora que emite la póliza y asume el riesgo. Nombre comercialConsorcio, Zurich, BICE Vida, Sura
brokerCorredora que intermedia la póliza.Willis Towers Watson S.A. Corredores de Seguros
policyNumberNúmero de la póliza colectiva, tal como lo emite la aseguradora. Es compartido por todos los asegurados de la póliza. Se guarda como texto para conservar ceros a la izquierda3100012345, 0045871, PC-2025-0012
benefitClassClase de asegurado dentro de la póliza (mismos beneficios, por ejemplo según cargo o nivel de plan).SILVER, Clase 1 - Ejecutivos
benefitSubClassSubdivisión de la clase. Solo tiene sentido junto con benefitClassCon cargas, Sin cargas
businessAreaÁrea: nivel superior de la clasificación comercial (área → línea → sublínea)Colectivos, Individuales, Masivos
productLineLínea de producto dentro del áreaSalud, Vida, Accidentes Personales
productSubLineSublínea: producto específico dentro de la línea. Solo tiene sentido junto con productLineComplementario de Salud, AP Escolar

Nota: businessArea, productLine y productSubLine forman una jerarquía. Ejemplo: Colectivos → Accidentes Personales → AP Escolar.

Ejemplo:

curl --location --request PATCH 'https://qa-serv.medibuslive.com/backoffice/api/client/users/c3410674-2698-4f5c-982a-f0d5a0e891f9' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--data-raw '{
    "insurer": "Zurich",
    "policyNumber": "0045871",
    "businessArea": "Colectivos",
    "productLine": "Accidentes Personales",
    "productSubLine": "AP Escolar"
}'

Ejemplo con Planes

Actualizar usuario como titular de un plan:

curl --location --request PATCH 'https://qa-serv.medibuslive.com/backoffice/api/client/users/c3410674-2698-4f5c-982a-f0d5a0e891f9' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--data-raw '{
    "plans": [
        {
            "plan_id": "68d3e8b89ff532f6f6e73ac8"
        }
    ]
}'

Nota: Cuando solo se envía plan_id, el sistema asume automáticamente role: "holder".

Actualizar usuario como beneficiario de un plan:

curl --location --request PATCH 'https://qa-serv.medibuslive.com/backoffice/api/client/users/c3410674-2698-4f5c-982a-f0d5a0e891f9' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--data-raw '{
    "plans": [
        {
            "plan_id": "68d3e8b89ff532f6f6e73ac8",
            "role": "beneficiary",
            "holder": "198801151"
        }
    ]
}'

Importante: Cuando role es "beneficiary", el campo holder (documento del titular) es obligatorio.

Actualizar usuario con múltiples planes:

curl --location --request PATCH 'https://qa-serv.medibuslive.com/backoffice/api/client/users/c3410674-2698-4f5c-982a-f0d5a0e891f9' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--data-raw '{
    "plans": [
        {
            "plan_id": "68d3e8b89ff532f6f6e73ac8",
            "role": "holder",
            "holder": null
        },
        {
            "plan_id": "68d3e8b89ff532f6f6e73ac9",
            "role": "beneficiary",
            "holder": "198801151"
        }
    ]
}'

Respuesta Exitosa

{
    "success": true,
    "message": "User updated successfully",
    "data": {
        "userId": "c3410674-2698-4f5c-982a-f0d5a0e891f9",
        "email": "rojash.camiloe@gmail.com",
        "username": "198801151",
        "firstName": "Camilo",
        "lastName": "Rojas",
        "phoneNumber": "+56959218752",
        "insurer": "Zurich",
        "policyNumber": "0045871",
        "businessArea": "Colectivos",
        "productLine": "Accidentes Personales",
        "productSubLine": "AP Escolar",
        "active": true,
        "verified": true,
        "plans": [
            {
                "plan_id": "68d3e8b89ff532f6f6e73ac8",
                "role": "holder",
                "holder": null
            }
        ]
    }
}

Nota: La respuesta incluye los campos de póliza que el usuario tenga guardados; los que no tenga valor no aparecen.

Respuesta de Error

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

O si hay errores de validación:

{
    "success": false,
    "message": "Validation failed",
    "errors": [
        {
            "field": "email",
            "message": "email must be an email"
        }
    ]
}

Descripción de la Respuesta

  • success: Indica si la solicitud fue exitosa (true) o falló (false)
  • message: Mensaje descriptivo del resultado de la operación
  • data: Objeto con la información actualizada del usuario
  • errors: (Solo en caso de error) Array con los errores de validación específicos

Activar Usuario

Este endpoint permite activar la cuenta de un usuario individual.

Endpoint

POST /backoffice/api/client/users/{userId}/activate

Parámetros de Ruta

ParámetroTipoRequeridoDescripción
userIdstring (UUID)SíIdentificador único del usuario a activar

Ejemplo de Solicitud

curl --location --request POST 'https://qa-serv.medibuslive.com/backoffice/api/client/users/{userId}/activate' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--data ''

Respuesta Exitosa (usuario activado)

{
    "success": true,
    "message": "User activated successfully",
    "data": {
        "userId": "bb376845-1dd3-4fb3-ae00-ee6bba40601e",
        "email": "rojash.camiloe@gmail.com",
        "username": "198801151",
        "active": true
    }
}

Respuesta cuando el usuario ya estaba activo

{
    "success": true,
    "message": "User is already active",
    "data": {
        "userId": "bb376845-1dd3-4fb3-ae00-ee6bba40601e",
        "email": "rojash.camiloe@gmail.com",
        "username": "198801151",
        "active": true
    }
}

Descripción de la Respuesta

  • success: Indica si la solicitud fue exitosa (true) o falló (false)
  • message: Mensaje descriptivo del resultado ("User activated successfully" o "User is already active")
  • data.userId: Identificador único del usuario (UUID)
  • data.email: Correo electrónico del usuario
  • data.username: Nombre de usuario en el sistema
  • data.active: Estado de la cuenta — siempre true en una respuesta exitosa de este endpoint

Desactivar Usuario

Este endpoint permite desactivar la cuenta de un usuario individual.

Endpoint

POST /backoffice/api/client/users/{userId}/deactivate

Parámetros de Ruta

ParámetroTipoRequeridoDescripción
userIdstring (UUID)SíIdentificador único del usuario a desactivar

Ejemplo de Solicitud

curl --location --request POST 'https://qa-serv.medibuslive.com/backoffice/api/client/users/{userId}/deactivate' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--data ''

Respuesta Exitosa (usuario desactivado)

{
    "success": true,
    "message": "User deactivated successfully",
    "data": {
        "userId": "bb376845-1dd3-4fb3-ae00-ee6bba40601e",
        "email": "rojash.camiloe@gmail.com",
        "username": "198801151",
        "active": false
    }
}

Respuesta cuando el usuario ya estaba desactivado

{
    "success": true,
    "message": "User is already deactivated",
    "data": {
        "userId": "bb376845-1dd3-4fb3-ae00-ee6bba40601e",
        "email": "rojash.camiloe@gmail.com",
        "username": "198801151",
        "active": false
    }
}

Descripción de la Respuesta

  • success: Indica si la solicitud fue exitosa (true) o falló (false)
  • message: Mensaje descriptivo del resultado ("User deactivated successfully" o "User is already deactivated")
  • data.userId: Identificador único del usuario (UUID)
  • data.email: Correo electrónico del usuario
  • data.username: Nombre de usuario en el sistema
  • data.active: Estado de la cuenta — siempre false en una respuesta exitosa de este endpoint

Notas Importantes

  1. Autenticación: Todos los endpoints requieren un token de acceso válido en el header Authorization
  2. Actualización Parcial: El endpoint PATCH solo actualiza los campos enviados, los demás campos permanecen sin cambios
  3. Validación de Email: Si se actualiza el email, debe ser un formato válido
  4. Identificador de Usuario: El userId debe ser un UUID válido para los endpoints de actualización, activación y desactivación
  5. Idempotencia: Los endpoints de activar y desactivar son idempotentes — si el usuario ya se encuentra en el estado solicitado, responden con success: true y un mensaje informativo sin lanzar error
Last updated on
Códigos de AccesoAutenticación SSO