Atendimento: Departamentos

Endpoints da WebApiAlcance para gerenciar departamentos de clientes no app de Atendimento - as áreas/setores vinculadas a um cliente (customer), cada uma com responsável (nome e e-mail) e integração opcional com o Acessorias. Cobrem criação, listagem paginada com filtro por cliente, detalhamento por ID, atualização parcial e exclusão.

Todos os endpoints exigem autenticação. Veja Autenticação para o fluxo de API Key. O Swagger oficial está em api.contabilidadealcance.com.br/docs.

Base path

/api/v1/departamentos

A URL completa em produção é https://api.contabilidadealcance.com.br/api/v1/departamentos.

Escopos necessários

departamentos:read - listagem e detalhamento
departamentos:write - criação, atualização e exclusão

O escopo é derivado da rota: o prefixo /departamentos vira o recurso departamentos, e o método HTTP define a ação (read para GET, write para POST/PUT/DELETE).

Endpoints

`POST /departamentos/`

Cria um novo departamento vinculado a um cliente. Os dados vão no corpo da requisição (DepartamentoCreate).

Parâmetros

Este endpoint não recebe parâmetros de rota ou query - os dados vão no corpo da requisição (DepartamentoCreate): nome e id_cliente (obrigatórios); acessorias_departamento_id, responsavel_email e responsavel_nome (opcionais).

Request

{
  "nome": "Fiscal",
  "id_cliente": 1234,
  "acessorias_departamento_id": "8f2c-dep-001",
  "responsavel_email": "fiscal@empresa.com.br",
  "responsavel_nome": "Maria Souza"
}

Response 201 Created

{
  "success": true,
  "message": "Departamento criado com sucesso",
  "data": {
    "id": 45,
    "nome": "Fiscal",
    "acessorias_departamento_id": "8f2c-dep-001",
    "responsavel_email": "fiscal@empresa.com.br",
    "responsavel_nome": "Maria Souza",
    "id_cliente": 1234,
    "legacy_uuid": null,
    "data_hora_criacao": "2026-07-03T10:15:00-03:00"
  }
}

Validações de domínio que falham retornam 422 Unprocessable Entity com detail descritivo.

Escopo: departamentos:write

`GET /departamentos/`

Lista departamentos com paginação e filtro opcional por cliente. Lista vazia é um estado válido - sempre retorna 200 OK, inclusive com data: [] e a mensagem "Nenhum departamento encontrado.".

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`id_cliente`	`int`	query	não	Filtra por cliente (`customer.id`).
`limit`	`int`	query	não	Itens por página. Default `100`; entre `1` e `500`.
`offset`	`int`	query	não	Offset de paginação. Default `0`; mínimo `0`.

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Departamentos recuperados com sucesso",
  "data": [
    {
      "id": 45,
      "nome": "Fiscal",
      "acessorias_departamento_id": "8f2c-dep-001",
      "responsavel_email": "fiscal@empresa.com.br",
      "responsavel_nome": "Maria Souza",
      "id_cliente": 1234,
      "legacy_uuid": null,
      "data_hora_criacao": "2026-07-03T10:15:00-03:00"
    }
  ]
}

Escopo: departamentos:read

`GET /departamentos/{departamento_id}`

Detalha um departamento pelo ID inteiro. Quando não encontrado, retorna 404 Not Found com detail descritivo.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`departamento_id`	`int`	path	sim	ID interno do departamento

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Departamento recuperado com sucesso",
  "data": {
    "id": 45,
    "nome": "Fiscal",
    "acessorias_departamento_id": "8f2c-dep-001",
    "responsavel_email": "fiscal@empresa.com.br",
    "responsavel_nome": "Maria Souza",
    "id_cliente": 1234,
    "legacy_uuid": null,
    "data_hora_criacao": "2026-07-03T10:15:00-03:00"
  }
}

Escopo: departamentos:read

`PUT /departamentos/{departamento_id}`

Atualiza um departamento existente. O body é um DepartamentoUpdate com campos parciais - somente o que vier preenchido é alterado.

Sem troca de dono

O DepartamentoUpdate omite id_cliente e legacy_uuid de propósito, para evitar mass-assignment (reatribuição do departamento a outro cliente via PUT).

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`departamento_id`	`int`	path	sim	ID do departamento

Body (DepartamentoUpdate - todos os campos opcionais): nome, acessorias_departamento_id, responsavel_email e/ou responsavel_nome.

Request

{
  "nome": "Fiscal e Tributário",
  "responsavel_nome": "Maria Souza Lima"
}

Response 200 OK

{
  "success": true,
  "message": "Departamento atualizado com sucesso",
  "data": {
    "id": 45,
    "nome": "Fiscal e Tributário",
    "acessorias_departamento_id": "8f2c-dep-001",
    "responsavel_email": "fiscal@empresa.com.br",
    "responsavel_nome": "Maria Souza Lima",
    "id_cliente": 1234,
    "legacy_uuid": null,
    "data_hora_criacao": "2026-07-03T10:15:00-03:00"
  }
}

Departamento inexistente retorna 404 Not Found; demais erros de validação retornam 422 Unprocessable Entity.

Escopo: departamentos:write

`DELETE /departamentos/{departamento_id}`

Remove um departamento pelo ID. Quando não encontrado, retorna 404 Not Found.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`departamento_id`	`int`	path	sim	ID do departamento

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Departamento removido com sucesso",
  "data": null
}

Escopo: departamentos:write

Schemas

`DepartamentoCreate`

Campo	Tipo	Obrigatório	Observações
`nome`	`str`	sim	Nome do departamento. Máx. 200 caracteres.
`id_cliente`	`int`	sim	ID do cliente (`customer.id`) ao qual o departamento pertence.
`acessorias_departamento_id`	`str \| null`	não	ID do departamento correspondente no Acessorias. Máx. 100 caracteres.
`responsavel_email`	`str \| null`	não	E-mail do responsável pelo departamento. Máx. 255 caracteres.
`responsavel_nome`	`str \| null`	não	Nome do responsável pelo departamento. Máx. 200 caracteres.

`DepartamentoUpdate`

Todos os campos são opcionais; apenas os enviados são atualizados. id_cliente e legacy_uuid não são aceitos.

Campo	Tipo	Observações
`nome`	`str \| null`	Novo nome. Máx. 200 caracteres.
`acessorias_departamento_id`	`str \| null`	Novo vínculo com o Acessorias. Máx. 100 caracteres.
`responsavel_email`	`str \| null`	Novo e-mail do responsável. Máx. 255 caracteres.
`responsavel_nome`	`str \| null`	Novo nome do responsável. Máx. 200 caracteres.

`DepartamentoRead`

Campo	Tipo	Notas
`id`	`int`	Identificador do departamento.
`nome`	`str`	Nome do departamento.
`id_cliente`	`int`	Cliente (`customer.id`) dono do departamento.
`acessorias_departamento_id`	`str \| null`	ID correspondente no Acessorias, se houver.
`responsavel_email`	`str \| null`	E-mail do responsável, se informado.
`responsavel_nome`	`str \| null`	Nome do responsável, se informado.
`legacy_uuid`	`str \| null`	Identificador legado, quando aplicável.
`data_hora_criacao`	`datetime`	Timestamp de criação do registro.

Notas

Toda resposta segue o envelope { success, message, data } (ou { success: false, message, details } em erro).
GET /departamentos/{departamento_id} é declarado depois da rota estática GET /departamentos/, então a listagem não conflita com o detalhamento por ID.
Na listagem, limit é restrito ao intervalo 1-500 e offset ao mínimo 0 - valores fora da faixa são rejeitados com 422 antes de chegar ao serviço.
Os campos id_cliente e legacy_uuid são imutáveis via API: definidos na criação e não expostos no PUT.