O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Acessar dados de configuração do usuário

O endpoint /apps/api/v1/users da API Apps recupera dados de configuração do usuário. É possível ler a configuração atual de todos os usuários ou de um único usuário, independentemente da função ou se a conta está ativa ou desativada. Essa saída inclui papéis do sistema e personalizados. Para recuperar dados de status e presença em tempo real apenas para agentes ativos, consulte os endpoints de agente da API Manager.

Esse endpoint é diferente dos usados no processo de upload em massa de usuários e fornece as informações necessárias para dar suporte a operações em massa. Para mais informações sobre como realizar processos de gerenciamento de usuários em massa, consulte API Bulk User Management.

Recursos e limitações da API

Ao recuperar dados do usuário, é possível incluir parâmetros para personalizar a resposta da API de acordo com suas necessidades. Os parâmetros a seguir são compatíveis:

Usuários específicos
- Opções de ID: e-mail, ID do sistema ou ID do usuário personalizado. Os usuários podem especificar um ou vários IDs. Se vários IDs de usuário apontarem para o mesmo usuário, ele deverá ser representado apenas uma vez na resposta.
Paginação
- Os usuários podem recuperar resultados em conjuntos paginados para gerenciar grandes conjuntos de dados. A resposta da API indica se há outras páginas para recuperar.
- Um parâmetro de API permite que os usuários solicitem uma página específica de resultados.
- Os usuários podem especificar o tamanho da página. O tamanho de página padrão é 100, e o máximo é 1.000. Quando um número de página específico é fornecido, os IDs do usuário não podem ser incluídos na solicitação.

A resposta da API inclui todos os campos de perfil de usuário e de configuração, exceto o campo "Status". Em vez do campo "Status", a API vai fornecer um campo deactivated_at. Esse campo vai conter:

Não há valor para usuários ativos.
A data e a hora em que um usuário foi desativado.

A tabela a seguir lista os campos do perfil de usuário que serão incluídos na resposta da API:

Tabela 1. Tabela de campos do perfil de usuário

Ordem	Tipo de coluna	Número de colunas	Nome das colunas	Valores válidos
1	E-mail	1	E-mail	E-mail
2	ID do agente	1	ID do agente	String
3	Nome	1	Nome	String
4	Sobrenome	1	Sobrenome	String
5	Alias	1	Alias	String
6	Desativado em	1	Desativado em	Sem valor, data/hora
7	Local	1	Local	Uma string que é um nome de local, Empty (sem alteração), Null (remover local atual).
8	Simultaneidade de chat	1	Simultaneidade de chat	1 a X (em que X é o valor configurado), vazio
9	Status de simultaneidade do chat	1	Status de simultaneidade do chat	0, 1, vazio
10	Chamadas internacionais sem restrições	1	Chamadas internacionais sem restrições	(Verdadeiro/Falso)
11	Usuário externo	1	Usuário externo	(Sim/Não)
12	URI de SIP externo	1	URI de SIP externo	String
13	Nome de usuário da UCaaS	1	Nome de usuário da UCaaS	String
14	Extensões de agente	1	Extensões de agente
15	Papéis	Várias	Função: Nome da função A Função: Nome da função B Função: Nome da função C etc.	0, 1, vazio
16	Equipe	Várias	Equipe: Nome da equipe A, Equipe: Nome da equipe B, Equipe: Nome da equipe C etc.	0, 1, vazio
17	Número de telefone	Várias	Número de entrada direta: 1, Número de entrada direta: 2, Número de entrada direta: 3	Número de telefone no formato E. Formato 164
18	Filtro	Individual	Filtro	String
19	Tempo limite do filtro	Individual	Tempo limite do filtro	Valor numérico entre 0 e 1.440

Limitações

Só é possível usar um tipo de ID do usuário por solicitação.
O número máximo de IDs por solicitação de API é 1.000.
Os usuários não podem fornecer IDs do usuário e uma solicitação de número de página em uma única solicitação de API. A API vai retornar todos os usuários com base na solicitação, até 1.000.

Mensagens de erro da API

A API vai fornecer as seguintes mensagens de erro para cenários específicos:

Tamanho da página: "A solicitação excedeu o tamanho máximo da página (o máximo é 1.000)"
Tamanho da página (requisito de entrada de número): "Solicitação de tamanho de página inválida. Precisa ser um valor numérico"
Solicitação combinada de ID do usuário e paginação: "A combinação de ID do usuário e solicitação de paginação não é aceita"
ID do usuário (excedido): "O número máximo de IDs de usuário foi excedido (o máximo é 1.000)"

Exemplo de solicitação e resposta

Este exemplo demonstra como recuperar a primeira página de usuários com 100 usuários por página. O corpo da resposta inclui uma matriz de objetos de usuário, cada um contendo dados detalhados de configuração do usuário.

Solicitação:

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

Resposta:

[
  {
    "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"
    ]
  },
  ...
]

Este exemplo demonstra como recuperar os detalhes de um único usuário transmitindo um parâmetro de e-mail. O corpo da resposta inclui um objeto de usuário que contém dados detalhados de configuração do usuário.