Departamentos

Gerenciamento de departamentos de atendimento. Departamentos organizam os atendentes e definem filas de chamadas. Requer papel de supervisor ou superior.

Importante

Departamentos que possuem gravações associadas não podem ser excluídos. Utilize a desativação nesse caso.

Endpoints

Método	Endpoint	Descrição	Role Mínimo
GET	/api/v1/departments	Listar departamentos	supervisor
POST	/api/v1/departments	Criar departamento	supervisor
GET	/api/v1/departments/:id	Buscar departamento	supervisor
PUT	/api/v1/departments/:id	Atualizar departamento	supervisor
DELETE	/api/v1/departments/:id	Excluir departamento	supervisor
GET	/api/v1/departments/:id/users	Listar usuários do departamento	supervisor
POST	/api/v1/departments/:id/users	Adicionar usuário ao departamento	supervisor
DELETE	/api/v1/departments/:id/users/:user_id	Remover usuário do departamento	supervisor

---

Listar Departamentos

GET /api/v1/departments

Query Parameters

Parâmetro	Tipo	Padrão	Descrição
page	integer	1	Número da página
page_size	integer	20	Itens por página
sort_by	string	name	Campo para ordenação
sort_order	string	asc	Direção da ordenação

Exemplo de Request

curl -X GET "https://voki.avanter.com.br/api/v1/departments?page=1&page_size=10" \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "X-Tenant: avanter"

Resposta de Sucesso (200)

{
  "data": [
    {
      "id": "e5f6a7b8-c9d0-1234-efgh-567890123456",
      "name": "Suporte Técnico",
      "identifier": "suporte-tecnico",
      "description": "Departamento de suporte técnico ao cliente",
      "active": true,
      "sector_id": "f6a7b8c9-d0e1-2345-fghi-678901234567",
      "max_queue_size": 20,
      "max_wait_time": 300,
      "user_count": 5,
      "inserted_at": "2026-01-10T09:00:00Z",
      "updated_at": "2026-02-01T10:00:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "page_size": 10,
    "total_pages": 1,
    "total_count": 3
  }
}

---

Criar Departamento

POST /api/v1/departments

Request Body

Campo	Tipo	Obrigatório	Descrição
name	string	Sim	Nome do departamento
identifier	string	Não	Identificador único (slug, gerado automaticamente se omitido)
description	string	Não	Descrição
sector_id	uuid	Não	ID do setor associado
max_queue_size	integer	Não	Tamanho máximo da fila (padrão: 20)
max_wait_time	integer	Não	Tempo máximo de espera em segundos (padrão: 300)

Exemplo de Request

curl -X POST https://voki.avanter.com.br/api/v1/departments \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "X-Tenant: avanter" \
  -H "Content-Type: application/json" \
  -d '{
    "department": {
      "name": "Vendas",
      "description": "Departamento de vendas e consultoria",
      "sector_id": "f6a7b8c9-d0e1-2345-fghi-678901234567",
      "max_queue_size": 15,
      "max_wait_time": 180
    }
  }'

Resposta de Sucesso (201)

{
  "data": {
    "id": "a7b8c9d0-e1f2-3456-ghij-789012345678",
    "name": "Vendas",
    "identifier": "vendas",
    "description": "Departamento de vendas e consultoria",
    "active": true,
    "sector_id": "f6a7b8c9-d0e1-2345-fghi-678901234567",
    "max_queue_size": 15,
    "max_wait_time": 180,
    "user_count": 0,
    "inserted_at": "2026-02-18T12:00:00Z",
    "updated_at": "2026-02-18T12:00:00Z"
  }
}

---

Buscar Departamento

GET /api/v1/departments/:id

Exemplo de Request

curl -X GET https://voki.avanter.com.br/api/v1/departments/e5f6a7b8-c9d0-1234-efgh-567890123456 \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "X-Tenant: avanter"

---

Atualizar Departamento

PUT /api/v1/departments/:id

Exemplo de Request

curl -X PUT https://voki.avanter.com.br/api/v1/departments/e5f6a7b8-c9d0-1234-efgh-567890123456 \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "X-Tenant: avanter" \
  -H "Content-Type: application/json" \
  -d '{
    "department": {
      "name": "Suporte Premium",
      "max_queue_size": 30
    }
  }'

---

Excluir Departamento

DELETE /api/v1/departments/:id

Atenção

Departamentos com gravações associadas retornarão erro 422. Desative o departamento em vez de excluí-lo.

Exemplo de Request

curl -X DELETE https://voki.avanter.com.br/api/v1/departments/e5f6a7b8-c9d0-1234-efgh-567890123456 \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "X-Tenant: avanter"

Resposta de Sucesso (204)

Sem corpo na resposta.

Erros

Código	Descrição
422	Departamento possui gravações e não pode ser excluído
404	Departamento não encontrado

---

Listar Usuários do Departamento

GET /api/v1/departments/:department_id/users

Exemplo de Request

curl -X GET https://voki.avanter.com.br/api/v1/departments/e5f6a7b8-c9d0-1234-efgh-567890123456/users \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "X-Tenant: avanter"

Resposta de Sucesso (200)

{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "João Silva",
      "email": "joao@empresa.com",
      "role": "attendant",
      "active": true
    }
  ]
}

---

Adicionar Usuário ao Departamento

POST /api/v1/departments/:department_id/users

Request Body

Campo	Tipo	Obrigatório	Descrição
user_id	uuid	Sim	ID do usuário a adicionar

Exemplo de Request

curl -X POST https://voki.avanter.com.br/api/v1/departments/e5f6a7b8-c9d0-1234-efgh-567890123456/users \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "X-Tenant: avanter" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }'

Resposta de Sucesso (201)

{
  "data": {
    "message": "Usuário adicionado ao departamento"
  }
}

---

Remover Usuário do Departamento

DELETE /api/v1/departments/:department_id/users/:user_id

Exemplo de Request

curl -X DELETE https://voki.avanter.com.br/api/v1/departments/e5f6a7b8-c9d0-1234-efgh-567890123456/users/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "X-Tenant: avanter"

Resposta de Sucesso (204)

Sem corpo na resposta.