Documentação da Talent Academy

API

Table Of Contents

Documentação da API de Usuários #

Ambientes da API #

  • Produção: https://api.talentacademy.com.br (use para dados reais)
  • Homologação/Testes: https://qa.api.talentacademy.com.br (use para testes e validações)

Recomenda-se utilizar o ambiente de QA para validar integrações antes de operar em produção.

Papéis e Níveis de Acesso #

Importante: O nível de acesso (accessProfile) deve acompanhar o papel (role) do usuário.
Por exemplo, se o papel for user, o nível de acesso também deve ser user.

  • user (nível mais simples):
    Não possui acesso gerencial. Pode apenas utilizar as funcionalidades básicas da plataforma destinadas a colaboradores comuns.
  • manager:
    Tem acesso aos painéis de controle para acompanhar e gerenciar seus liderados, podendo visualizar relatórios e informações da equipe.
  • master:
    Possui acesso completo à organização. Pode cadastrar, editar e excluir colaboradores, acessar todas as configurações da plataforma, ativar/desativar ferramentas e painéis de controle, além de gerenciar permissões e funcionalidades avançadas.

Resumo: Sempre relacione o accessProfile ao role do usuário para garantir a segurança e o funcionamento correto dos acessos.
Exemplo: Usuário com papel manager deve ter nível de acesso manager.

Autenticação #

Todas as rotas exigem o header x-api-key com a chave de API da sua empresa.

1. Listar Usuários #

GET /endpoint/users

Descrição: Retorna os usuários cadastrados na empresa, incluindo perfis, filtros, papéis, dados de testes e trilhas de jornada.

Headers obrigatórios: x-api-key: SUA_API_KEY

Parâmetros de query (opcionais):

  • page (número) – Número da página (padrão: 1, mínimo: 1)
  • pageSize (número) – Tamanho da página (padrão: 50, mínimo: 1, máximo: 200)

Campos obrigatórios:

  • x-api-key (header)

Exemplo de requisição simples:

curl -X GET -H 'x-api-key: SUA_API_KEY' https://qa.api.talentacademy.com.br/endpoint/users

Exemplo de requisição com paginação:

curl -X GET -H 'x-api-key: SUA_API_KEY' 'https://qa.api.talentacademy.com.br/endpoint/users?page=1&pageSize=50'

Resposta de sucesso:

[
  {
    "idUser": 1,
    "name": "Nome do Usuário",
    "email": "email@exemplo.com",
    "username": "usuario1",
    "birthdate": "1990-01-01",
    "accessProfile": "user",
    "roles": ["user"],
    "purpose": "...",
    "map": "...",
    "filters": [
      { "filterKey": "departamento", "filterValue": "RH" }
    ],
    "journeyTrails": [
      {
        "idUser": 1,
        "idUserJourneyTrail": 100,
        "trailName": "Trilha de Onboarding",
        "trailDays": 30,
        "userLastAccessDate": "2025-02-01T10:00:00.000Z",
        "reachedGoalsCount": 5,
        "quizzesAverage": 85.5,
        "contentProgress": 75.0
      }
    ]
  }
]

2. Criar ou Atualizar Usuários #

PUT /endpoint/users

Descrição: Cria ou atualiza usuários em lote.

Headers obrigatórios: x-api-key: SUA_API_KEY

Observação sobre o campo manager: O gestor informado (manager.managerEmail) deve já estar cadastrado no banco de dados ou estar presente no mesmo array users para ser inserido junto na mesma requisição.

Sobre a senha dos usuários: Ao criar usuários, a senha padrão será a data de nascimento informada (birthdate). Caso a data de nascimento não seja informada, será utilizada a senha enviada no campo password (obrigatório no corpo da requisição).

Sobre os filtros (filters): Os filtros são usados para categorizar e organizar usuários na plataforma. Cada filtro possui dois campos principais:

  • filterKey – A chave que identifica o tipo de filtro
  • filterValue – O valor/opção do filtro que será relacionado ao usuário

Exemplo: Se o filterKey for “Unidade”, o filterValue poderia ser “Matriz”, “Filial São Paulo”, “Filial Rio de Janeiro”, etc.

Filtros padrão da plataforma:

  • Unidade: filterKey: "unit"
  • Gênero: filterKey: "gender"
  • Nível do cargo: filterKey: "positionLevel"
  • Formação: filterKey: "schoolLevel"
  • País: filterKey: "country"

Filtros customizados: Para filtros personalizados criados especificamente para sua empresa, o filterKey deve ser exatamente o nome do filtro customizado.

Campos obrigatórios:

  • password (string) – senha padrão para usuários sem data de nascimento
  • users (array de objetos):
    • name (string)
    • username ou email (string)
    • accessProfile (string: user, manager ou master)
    • roles (array de strings: user, manager ou master)

Exemplo de requisição:

curl -X PUT -H 'x-api-key: SUA_API_KEY' -H "Content-Type: application/json" -d '{
    "password": "senha",
    "idCompanyRecruitment": 123, // Usar apenas quando for cadastrar um candidato em um PS. Para criar um colaborador, não é necessário.
    "users": [
      {
        "name": "Nome do Usuário",
        "email": "email@exemplo.com",
        "username": "usuario1",
        "birthdate": "1990-01-01",
        "roles": ["user"],
        "accessProfile": "user",
        "filters": [
          { "filterKey": "departamento", "filterValue": "RH" }
        ],
        "manager": { "managerEmail": "gestor@exemplo.com" },
        "history": { "hiringDate": "2020-01-01" }
      }
    ]
  }' https://qa.api.talentacademy.com.br/endpoint/users

Body (exemplo):

    {
  "idCompanyRecruitment": 123,
  "password": "senha",
  "users": [
    {
      "name": "Nome do Usuário",
      "email": "email@exemplo.com",
      "username": "usuario1",
      "birthdate": "1990-01-01",
      "roles": ["user"],
      "accessProfile": "user",
      "filters": [
        { "filterKey": "departamento", "filterValue": "RH" }
      ],
      "manager": { "managerEmail": "gestor@exemplo.com" },
      "history": { "hiringDate": "2020-01-01" }
    }
  ]
}

    Resposta de sucesso:

    {
  "users": [
    {
      "idUser": 1,
      "idCompany": 10,
      "name": "Nome do Usuário",
      "email": "email@exemplo.com",
      "username": "usuario1"
    }
  ]
}

    3. Atualizar Status de Usuários #

    PUT /endpoint/users/status

    Descrição: Ativa ou desativa usuários em lote.

    Headers obrigatórios: x-api-key: SUA_API_KEY

    Campos obrigatórios:

    • x-api-key (header)
    • idUsers (array de inteiros)
    • deletedAt (boolean)

    Exemplo de requisição:

    curl -X PUT \
  -H 'x-api-key: SUA_API_KEY' \
  -H "Content-Type: application/json" \
  -d '{
    "idUsers": [1, 2, 3],
    "deletedAt": true,
    "isVoluntary": "true"
  }' \
  https://qa.api.talentacademy.com.br/endpoint/users/status

    Body (exemplo):

    {
  "idUsers": [1, 2, 3],
  "deletedAt": true,
  "isVoluntary": "true"
}

    Body (exemplo):

    • deletedAt: true para desativar o(s) usuário(s), false para reativar.
    • isVoluntary: Indica se a desativação foi voluntária ("true") ou involuntária ("false"). Opcional.

    Resposta de sucesso: Status: 204 (sem conteúdo)

    4. Listar Recrutamentos #

    GET /endpoint/recruitments

    Descrição: Lista os recrutamentos disponíveis para a empresa.

    Headers obrigatórios: x-api-key: SUA_API_KEY

    Campos obrigatórios:

    • x-api-key (header)

    Exemplo de requisição:

    curl -X GET -H 'x-api-key: SUA_API_KEY' https://qa.api.talentacademy.com.br/endpoint/recruitments

    Resposta de sucesso:

    [
  {
    "idCompanyRecruitment": 1,
    "name": "Recrutamento 1"
  }
]

    Observações #

    • Todos os endpoints retornam erros padronizados em caso de falha, com mensagens descritivas.
    • Consulte o suporte para obter sua chave de API ou dúvidas sobre os campos.

    Quais são seus sentimentos

    Atualizado em 11 de fevereiro de 2026