Usuários
Usuários são as pessoas que entram no Pedagogo. Corresponde à tela Usuários do módulo Administrativo. Cada usuário pertence a um grupo de acesso, que define as telas que ele enxerga, e pode ser vinculado a um departamento e a uma empresa.
A chave usada na integração também é gerada aqui, pelo endpoint
PATCH /administrative/users/{uuid}/generate-key. Veja a
Autenticação para o uso da chave.
Endpoints
| Método | Caminho | Descrição |
|---|---|---|
| GET | /administrative/users | Lista os usuários |
| POST | /administrative/users | Cadastra um usuário |
| GET | /administrative/users/export-users | Exporta a lista de usuários em planilha |
| GET | /administrative/users/access-groups | Lista de apoio: grupos de acesso |
| GET | /administrative/users/companies | Lista de apoio: empresas do cliente |
| GET | /administrative/users/departments | Lista de apoio: departamentos |
| GET | /administrative/users/{uuid} | Consulta um usuário |
| PUT | /administrative/users/{uuid} | Altera um usuário |
| DELETE | /administrative/users/{uuid} | Apaga um usuário |
| PATCH | /administrative/users/{uuid}/generate-key | Gera a chave de API do usuário |
GET /administrative/users
Lista os usuários do cliente, em ordem alfabética pelo nome, salvo se
columnName e orderData forem informados.
Parâmetros de URL
| Parâmetro | Descrição |
|---|---|
| search | Texto livre que busca no nome, no e-mail e no celular |
| name | Trecho do nome |
| Trecho do e-mail | |
| access_group_uuid | Traz só os usuários do grupo de acesso informado |
| online | Quando informado com valor verdadeiro, traz só os usuários online |
| columnName | Coluna para ordenar |
| orderData | Sentido da ordenação: asc ou desc |
| per_page | Quantidade de registros por página |
| page | Número da página, quando per_page é informado |
Resposta (200): lista de usuários, direta ou paginada. Campos principais:
uuid, id, name, email, cellphone, access_group_id, access_group,
company_id, company_name, department_id, department_name, inactive,
photo_url, online, lastAcess e user_update_name. A senha e o token de
API não são devolvidos nas consultas; a chave de API só é devolvida, uma vez, por generate-key.
Exemplo:
curl "https://api.pedagogo.app/administrative/users?search=ana&per_page=15" \
-H "Accept: application/json" \
-H "Authorization: Bearer <token-de-sessao>"
POST /administrative/users
Cadastra um usuário. Se a senha não for informada, o sistema gera uma senha de 8 caracteres e envia o e-mail de boas-vindas ao novo usuário.
Se o e-mail informado já pertencer a um usuário existente (inclusive um usuário apagado), esse cadastro é reativado e atualizado com os dados enviados, e o e-mail de boas-vindas não é enviado.
Corpo (JSON)
| Campo | Obrigatório | Tipo | Descrição |
|---|---|---|---|
| name | Sim | Texto | Nome completo do usuário |
| Sim | E-mail do usuário. É usado para entrar no sistema | ||
| access_group_id | Não | Número inteiro | id do grupo de acesso, que define as telas do usuário |
| access_group_uuid | Não | Texto (uuid) | Alternativa a access_group_id: uuid do grupo de acesso |
| department_id | Não | Número inteiro | id do departamento do usuário. Veja Departamentos |
| company_id | Não | Número inteiro | id da empresa do usuário. Veja a lista de apoio de empresas nesta página |
| cellphone | Não | Texto | Celular do usuário |
| password | Não | Texto | Senha de acesso. Se omitida, o sistema gera uma senha de 8 caracteres |
Resposta (201): o usuário criado, sem a senha.
Exemplo:
curl -X POST https://api.pedagogo.app/administrative/users \
-H "Accept: application/json" \
-H "Authorization: Bearer <token-de-sessao>" \
-H "Content-Type: application/json" \
-d '{"name": "Usuário exemplo", "email": "[email protected]", "access_group_uuid": "<uuid-do-grupo-de-acesso>"}'
GET /administrative/users/{uuid}
Devolve um usuário do cliente pelo uuid, com os mesmos campos da listagem.
PUT /administrative/users/{uuid}
Altera um usuário. Envie apenas os campos que devem mudar, com os mesmos nomes da tabela do cadastro.
Corpo (JSON)
| Campo | Obrigatório | Tipo | Descrição |
|---|---|---|---|
| name | Não | Texto | Nome completo do usuário |
| Não | E-mail do usuário | ||
| access_group_id | Não | Número inteiro | id do grupo de acesso |
| access_group_uuid | Não | Texto (uuid) | Alternativa a access_group_id |
| department_id | Não | Número inteiro | id do departamento |
| company_id | Não | Número inteiro | id da empresa |
| cellphone | Não | Texto | Celular do usuário |
| password | Não | Texto | Nova senha. Ao informar uma senha, o sistema envia ao usuário um e-mail avisando da alteração |
Resposta (200): o usuário alterado.
DELETE /administrative/users/{uuid}
Apaga o usuário. A exclusão é lógica: o usuário deixa de aparecer nas listas e não consegue mais entrar no sistema. O histórico continua registrado.
Resposta (200): sem conteúdo relevante (null).
PATCH /administrative/users/{uuid}/generate-key
Gera uma nova chave de API para o usuário e a devolve em texto. A chave é a
credencial usada para obter o token de sessão em POST /auth/login-by-token.
A chave aparece uma única vez, na resposta desta chamada. Guarde-a em um cofre de segredos ou em variável de ambiente, porque o Pedagogo não a mostra de novo. Para obter outra, gere uma nova chave: a anterior deixa de valer na hora. As regras de uso estão em Autenticação.
Resposta (200): a chave em texto, com 64 caracteres hexadecimais, como um texto JSON simples.
"<chave-do-usuario>"
Exemplo:
curl -X PATCH https://api.pedagogo.app/administrative/users/<uuid-do-usuario>/generate-key \
-H "Accept: application/json" \
-H "Authorization: Bearer <token-de-sessao>"
GET /administrative/users/export-users
Baixa uma planilha Excel (.xlsx) com a lista de usuários do cliente. A
planilha traz as colunas #, Nome, Grupo de Acesso, Email, Empresa e
Departamento. Esta chamada não recebe filtros: exporta todos os usuários do
cliente.
Resposta (200): arquivo .xlsx para download. O nome do arquivo começa com
um trecho aleatório.
Listas de apoio
Os endpoints abaixo alimentam as caixas de seleção do cadastro de usuários.
GET /administrative/users/access-groups
Lista os grupos de acesso do cliente. Devolve a mesma resposta de
GET /administrative/access-groups, descrita na página
Grupos de acesso.
GET /administrative/users/companies
Lista as empresas do cliente, para vincular o usuário a uma empresa. Campos
principais: id, name, company_name, document e client_name.
GET /administrative/users/departments
Lista os departamentos do cliente. Devolve a mesma resposta de
GET /administrative/departments, descrita na página
Departamentos.