Departamentos

Os departamentos representam a estrutura organizacional de cada empresa da instância — como "Human Resources" ou "Engineering" — e são usados para classificar vagas e membros do time de recrutamento. Cada departamento pertence a uma empresa (atsCompanyId) e pode ter um departamento pai (parentId), permitindo montar hierarquias com subdepartamentos dentro da mesma empresa.

O acesso é controlado por empresa: usuários owner/admin enxergam e gerenciam os departamentos de todas as empresas da instância, enquanto os demais usuários só acessam as empresas às quais estão vinculados. Quem não tem permissão de leitura ou gerenciamento sobre a empresa recebe 403 Forbidden.

Headers obrigatórios

Todas as requisições devem incluir o header X-Ats-Id (UUID) com o identificador da instância e Authorization: Bearer {token} com o token do usuário ATS.

---

Estrutura de Dados Principal

Um departamento contém as seguintes informações principais:

Campo	Tipo	Descrição
name	String	Nome do departamento (máx. 150 caracteres).
slug	String	Slug gerado automaticamente a partir do nome.
atsCompanyId	Number	ID da empresa à qual o departamento pertence.
parentId	Number	ID do departamento pai (nulo para departamentos raiz).
parent	Object	Dados do departamento pai (no detalhe).
children	Array	Subdepartamentos (na árvore e no detalhe).

---

Endpoints

Endpoints protegidos para gerenciamento dos departamentos. Requerem autenticação de usuário ATS (atsUser) e respeitam o escopo de empresas do usuário autenticado.

Listar Departamentos

Lista os departamentos da instância com paginação, busca e ordenação. Usuários não administradores recebem apenas os departamentos das empresas às quais estão vinculados.

GET /v1/ats/user/departments

Parâmetros de Query

Nome	Tipo	Obrigatório	Descrição
page	number	Não	O número da página (mínimo: 1).
perPage	number	Não	Itens por página (entre 1 e 100).
search	string	Não	Busca por termo no nome (máx. 150 caracteres).
atsCompanyId	number	Não	Filtra por empresa (deve existir na instância).
orderBy	enum	Não	Ordena por id, name ou createdAt.
orderDirection	enum	Não	Direção da ordenação: asc ou desc.

Exemplo de Requisição

curl -X GET "https://api.us.basis.tavares.in/v1/ats/user/departments?atsCompanyId=1" \
  -H "X-Ats-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

Respostas

200 OK

Retorna um objeto de paginação contendo a lista de departamentos.

{
  "meta": {
    "currentPage": 1,
    "perPage": 25
  },
  "data": [
    {
      "id": 2,
      "atsId": 1,
      "atsCompanyId": 1,
      "parentId": null,
      "name": "Human Resources",
      "slug": "human-resources",
      "createdAt": "2026-09-10T12:38:39.189+00:00",
      "updatedAt": "2026-09-10T12:38:39.189+00:00"
    },
    {
      "id": 1,
      "atsId": 1,
      "atsCompanyId": 1,
      "parentId": null,
      "name": "I.T",
      "slug": "i.t",
      "createdAt": "2026-09-10T12:38:22.468+00:00",
      "updatedAt": "2026-09-10T12:38:22.468+00:00"
    }
  ]
}

Listar Departamentos (Lista Simples)

Retorna os departamentos em formato simplificado (label/value), ideal para selects e filtros no frontend.

GET /v1/ats/user/departments/list

Parâmetros de Query

Nome	Tipo	Obrigatório	Descrição
search	string	Não	Busca por termo no nome (máx. 150 caracteres).
atsCompanyId	number	Não	Filtra por empresa (deve existir na instância).

Exemplo de Requisição

curl -X GET "https://api.us.basis.tavares.in/v1/ats/user/departments/list?atsCompanyId=1" \
  -H "X-Ats-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

Respostas

200 OK

Retorna um array com os departamentos em formato label/value.

[
  {
    "value": 4,
    "label": "Engineering"
  },
  {
    "value": 3,
    "label": "Help Desk"
  },
  {
    "value": 2,
    "label": "Human Resources"
  },
  {
    "value": 1,
    "label": "I.T"
  }
]

Obter Árvore de Departamentos

Retorna a hierarquia completa de departamentos de uma empresa, com os subdepartamentos aninhados em children. Este endpoint exige o parâmetro atsCompanyId e permissão de leitura sobre a empresa.

GET /v1/ats/user/departments/tree

Parâmetros de Query

Nome	Tipo	Obrigatório	Descrição
atsCompanyId	number	Sim	ID da empresa (deve existir na instância).
search	string	Não	Busca por termo no nome (máx. 150 caracteres).

Exemplo de Requisição

fetch('https://api.us.basis.tavares.in/v1/ats/user/departments/tree?atsCompanyId=1', {
  headers: {
    'X-Ats-Id': '3fa85f64-5717-4562-b3fc-2c963f66afa6',
    'Authorization': 'Bearer {token}'
  }
})
  .then(response => response.json())
  .then(data => console.log(data));

Respostas

200 OK

Retorna um array com os departamentos raiz e seus subdepartamentos em children.

[
  {
    "id": 1,
    "parentId": null,
    "name": "I.T",
    "children": [
      {
        "id": 3,
        "parentId": 1,
        "name": "Help Desk",
        "children": [
          {
            "id": 4,
            "parentId": 3,
            "name": "Engineering",
            "children": []
          }
        ]
      }
    ]
  },
  {
    "id": 2,
    "parentId": null,
    "name": "Human Resources",
    "children": []
  }
]

403 Forbidden

O usuário não tem permissão para visualizar os departamentos desta empresa.

{
  "code": "FORBIDDEN",
  "message": "Você não tem permissão para visualizar este recurso"
}

Criar Novo Departamento

Cria um novo departamento em uma empresa, opcionalmente vinculado a um departamento pai da mesma empresa. O slug é gerado automaticamente a partir do nome. Requer permissão de gerenciamento sobre a empresa (owner/admin, ou recruiter/hiring_manager vinculado).

POST /v1/ats/user/departments

Payload (Body)

Atributo	Tipo	Obrigatório	Descrição
name	string	Sim	Nome do departamento (máx. 150 caracteres).
atsCompanyId	number	Sim	ID da empresa (deve existir na instância).
parentId	number	Não	ID do departamento pai (deve existir na mesma empresa).

Exemplo de Requisição

curl -X POST "https://api.us.basis.tavares.in/v1/ats/user/departments" \
  -H "X-Ats-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Engineering",
    "atsCompanyId": 1,
    "parentId": 1
  }'

Respostas

201 Created

Retorna o ID do departamento criado.

{
  "id": 1
}

422 Unprocessable Entity

Erro de validação nos campos enviados.

{
  "errors": [
    {
      "message": "The name field must be defined",
      "rule": "required",
      "field": "name"
    }
  ]
}

403 Forbidden

O usuário não tem permissão para gerenciar departamentos desta empresa.

{
  "code": "FORBIDDEN",
  "message": "Você não tem permissão para gerenciar este recurso"
}

Obter Departamento por ID

Recupera os detalhes de um departamento, incluindo o departamento pai e os subdepartamentos.

GET /v1/ats/user/departments/:id

Parâmetros de Rota

Nome	Tipo	Obrigatório	Descrição
id	number	Sim	O ID do departamento.

Exemplo de Requisição

curl -X GET "https://api.us.basis.tavares.in/v1/ats/user/departments/2" \
  -H "X-Ats-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

Respostas

200 OK

Retorna o departamento com parent e children.

{
  "id": 2,
  "atsId": 1,
  "atsCompanyId": 1,
  "parentId": null,
  "name": "Human Resources",
  "slug": "human-resources",
  "createdAt": "2026-09-10T12:38:39.189+00:00",
  "updatedAt": "2026-09-10T12:38:39.189+00:00",
  "parent": null,
  "children": []
}

404 Not Found

Ocorre quando o departamento não existe na instância.

Atualizar Departamento

Atualiza os dados de um departamento existente. Ao alterar o nome, o slug é regenerado automaticamente. Ao mover o departamento para outra empresa (atsCompanyId), é exigida permissão de gerenciamento sobre as duas empresas.

PUT /v1/ats/user/departments/:id

Parâmetros de Rota

Nome	Tipo	Obrigatório	Descrição
id	number	Sim	O ID do departamento.

Payload (Body)

Todos os campos são opcionais; envie apenas os que deseja alterar.

Atributo	Tipo	Obrigatório	Descrição
name	string	Não	Nome do departamento (máx. 150 caracteres).
atsCompanyId	number	Não	ID da nova empresa (deve existir na instância).
parentId	number	Não	ID do departamento pai (deve existir na empresa informada, ou na instância quando atsCompanyId for omitido).

Exemplo de Requisição

curl -X PUT "https://api.us.basis.tavares.in/v1/ats/user/departments/4" \
  -H "X-Ats-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Engineering",
    "parentId": 3
  }'

Respostas

204 No Content

Atualização concluída com sucesso.

404 Not Found

Ocorre quando o departamento não existe na instância.

403 Forbidden

O usuário não tem permissão para gerenciar departamentos da empresa.

Remover Departamento

Remove um departamento da instância. Requer permissão de gerenciamento sobre a empresa do departamento.

DELETE /v1/ats/user/departments/:id

Parâmetros de Rota

Nome	Tipo	Obrigatório	Descrição
id	number	Sim	O ID do departamento.

Exemplo de Requisição

curl -X DELETE "https://api.us.basis.tavares.in/v1/ats/user/departments/5" \
  -H "X-Ats-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer {token}"

Respostas

204 No Content

Remoção concluída com sucesso.

404 Not Found

Ocorre quando o departamento não existe na instância.