Obtén datos de configuración del usuario

La API de Apps está diseñada para recuperar datos de configuración del usuario. Puedes leer la configuración del usuario actual para todos los usuarios o para un solo usuario, independientemente de su rol o estado. En este resultado, se incluyen los roles personalizados y del sistema.

Este extremo difiere de los que se usan en el proceso de carga masiva de usuarios y proporciona la información necesaria para admitir operaciones masivas. Para obtener más información sobre cómo realizar procesos de administración de usuarios masivos, consulta la API de Bulk User Management.

Capacidades y limitaciones de la API

Cuando recuperes datos del usuario, puedes incluir parámetros para adaptar la respuesta de la API a tus necesidades. Se admiten los siguientes parámetros:

Usuarios específicos
- Opciones de ID: Correo electrónico, ID del sistema o ID de usuario personalizado. Los usuarios pueden especificar uno o varios IDs. Si varios IDs de usuario apuntan al mismo usuario, este solo debe representarse una vez en la respuesta.
Paginación
- Los usuarios pueden recuperar resultados en conjuntos paginados para administrar grandes conjuntos de datos. La respuesta de la API debe indicar si hay páginas adicionales para recuperar.
- Un parámetro de la API permite a los usuarios solicitar una página específica de resultados.
- Los usuarios pueden especificar el tamaño de la página. El tamaño de página predeterminado es 100 y el máximo es 1,000. Cuando se proporciona un número de página específico, no se pueden incluir IDs de usuario en la solicitud.

La respuesta de la API incluye todos los campos de configuración y del perfil del usuario, excepto el campo "Estado". En lugar del campo “Estado”, la API proporcionará un campo deactivated_at. Este campo contendrá lo siguiente:

No hay valor para los usuarios activos.
Fecha y hora en que se desactivó un usuario.

En la siguiente tabla, se enumeran los campos del perfil del usuario que se incluirán en la respuesta de la API:

Tabla 1: Tabla de campos del perfil de usuario

Order	Tipo de columna	Cantidad de columnas	Nombre de la columna	Valores válidos
1	Correo electrónico	1	Correo electrónico	Correo electrónico
2	ID del agente	1	ID del agente	String
3	Nombre	1	Nombre	String
4	Apellido	1	Apellido	String
5	Alias	1	Alias	String
6	Se desactivó el	1	Se desactivó el	Sin valor, fecha y hora
7	Ubicación	1	Ubicación	Es una cadena que es un nombre de ubicación, Empty (sin cambios) o Null (quita la ubicación actual).
8	Simultaneidad de chats	1	Simultaneidad de chats	De 1 a X (donde X es el valor configurado), vacío
9	Estado de simultaneidad de chats	1	Estado de simultaneidad de chats	0, 1, vacío
10	Llamadas internacionales sin restricciones	1	Llamadas internacionales sin restricciones	(Verdadero/Falso)
11	Usuario externo	1	Usuario externo	(Sí/No)
12	URI SIP externo	1	URI SIP externo	String
13	Nombre de usuario de UCaaS	1	Nombre de usuario de UCaaS	String
14	Extensiones de agente	1	Extensiones de agente
15	Funciones	Varias	Rol: Nombre del rol A Rol: Nombre del rol B Rol: Nombre del rol C, etcétera	0, 1, vacío
16	Equipo	Varias	Equipo: Nombre del equipo A Equipo: Nombre del equipo B Equipo: Nombre del equipo C, etcétera	0, 1, vacío
17	Número de teléfono	Varias	Número de entrada directa: 1, Número de entrada directa: 2 Número de entrada directa: 3	Número de teléfono en formato E. Formato 164
18	Filtro	Único	Filtro	String
19	Tiempo de espera del filtro	Único	Tiempo de espera del filtro	Valor numérico entre 0 y 1,440

Limitaciones

Solo se admite un tipo de ID de usuario por solicitud.
La cantidad máxima de IDs por solicitud a la API es de 1,000.
Los usuarios no pueden proporcionar IDs de usuario y una solicitud de número de página en una sola solicitud a la API. La API devolverá todos los usuarios según la solicitud, hasta un máximo de 1,000.

Mensajes de error de la API

La API proporcionará los siguientes mensajes de error para situaciones específicas:

Tamaño de la página: "Se superó la solicitud de tamaño máximo de la página (1,000 es el máximo)"
Tamaño de la página (requisito de entrada numérica): "Solicitud de tamaño de página no válida; debe ser un valor numérico"
Solicitud combinada de ID de usuario y paginación: "No se admite la combinación de ID de usuario y solicitud de paginación"
ID de usuario (superado): "Se superó la cantidad máxima de IDs de usuario (el máximo es 1,000)"

Ejemplo de solicitud y respuesta

En este ejemplo, se muestra cómo recuperar la primera página de usuarios con 100 usuarios por página. El cuerpo de la respuesta incluye un array de objetos de usuario, cada uno de los cuales contiene datos detallados de configuración del usuario.

Solicitud:

Method: GET
Type:
URL: https://{{subdomain}}.{{domain}}/apps/api/v1/users?page=1&per_page=100

Respuesta:

[
  {
    "email": "email",
    "agent_number": "number",
    "first_name": "first",
    "last_name": "last",
    "status": "Active",
    "location": "location",
    "max_chat_limt": 3,
    "max_chat_limit_enabled": true,
    "deleted_at": "2024-07-16T15:57:12.000Z",
    "ucaas_user_name": "username",
    "external_user": true,
    "ucaas_sip_uri": "sip uri",
    "unrestricted_international_calling": false,
    "roles": [
      { "name": "Admin" },
      { "name": "Manager" }
    ],
    "teams": [
      { "name": "name" }
    ],
    "phone_numbers": [
      "123-456-7890",
      "098-765-4321"
    ]
  },
  ...
]

En este ejemplo, se muestra cómo recuperar los detalles de un solo usuario pasando un parámetro de correo electrónico. El cuerpo de la respuesta incluye un objeto de usuario que contiene datos detallados de configuración del usuario.