Atendimento: Contato-Departamento

Endpoints da WebApiAlcance para gerenciar a associação N:N entre contatos e departamentos - a tabela de junção (contato_departamento) que vincula um contato a um departamento, opcionalmente amarrado a um cliente. Cobrem criação do vínculo, listagem com filtros e paginação, detalhamento por ID, atualização (apenas o vínculo de cliente) 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/contato-departamento

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

Escopos necessários

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

O escopo é derivado da rota: o prefixo /contato-departamento vira o recurso contato_departamento (hífen → underscore), e o método HTTP define a ação (read para GET, write para POST/PUT/DELETE).

Endpoints

`POST /contato-departamento/`

Cria um novo vínculo entre um contato e um departamento, opcionalmente amarrado a um cliente.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query - os dados vão no corpo da requisição (ContatoDepartamentoCreate): contato_id (obrigatório), departamento_id (obrigatório) e id_cliente (opcional).

Request

{
  "contato_id": 12,
  "departamento_id": 3,
  "id_cliente": 1234
}

Response 201 Created

{
  "success": true,
  "message": "Vínculo criado com sucesso",
  "data": {
    "id": 45,
    "contato_id": 12,
    "departamento_id": 3,
    "id_cliente": 1234,
    "data_hora_criacao": "2026-07-03T09:15:00-03:00"
  }
}

Dados inválidos retornam 422 Unprocessable Entity com detail descrevendo o erro.

Escopo: contato_departamento:write

`GET /contato-departamento/`

Lista os vínculos cadastrados, com filtros opcionais e paginação. Lista vazia é um estado válido - sempre retorna 200 OK, inclusive com data: [] e a mensagem "Nenhum vínculo encontrado.".

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`id_cliente`	`int`	query	não	Filtra por cliente (`customer.id`).
`contato_id`	`int`	query	não	Filtra por contato.
`departamento_id`	`int`	query	não	Filtra por departamento.
`limit`	`int`	query	não	Limite de itens por página. Entre `1` e `500`. Default `100`.
`offset`	`int`	query	não	Offset de paginação. Mínimo `0`. Default `0`.

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Vínculos recuperados com sucesso",
  "data": [
    {
      "id": 45,
      "contato_id": 12,
      "departamento_id": 3,
      "id_cliente": 1234,
      "data_hora_criacao": "2026-07-03T09:15:00-03:00"
    }
  ]
}

Escopo: contato_departamento:read

`GET /contato-departamento/{vinculo_id}`

Detalha um vínculo pelo ID inteiro. Quando não encontrado, retorna 404 Not Found com detail descrevendo o erro.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`vinculo_id`	`int`	path	sim	ID interno do vínculo

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Vínculo recuperado com sucesso",
  "data": {
    "id": 45,
    "contato_id": 12,
    "departamento_id": 3,
    "id_cliente": 1234,
    "data_hora_criacao": "2026-07-03T09:15:00-03:00"
  }
}

Escopo: contato_departamento:read

`PUT /contato-departamento/{vinculo_id}`

Atualiza um vínculo existente. Por ser uma junção pura, somente o vínculo de cliente (id_cliente) é atualizável; contato_id e departamento_id são definidos apenas na criação.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`vinculo_id`	`int`	path	sim	ID do vínculo

Request (ContatoDepartamentoUpdate - apenas id_cliente, opcional)

{
  "id_cliente": 5678
}

Response 200 OK

{
  "success": true,
  "message": "Vínculo atualizado com sucesso",
  "data": {
    "id": 45,
    "contato_id": 12,
    "departamento_id": 3,
    "id_cliente": 5678,
    "data_hora_criacao": "2026-07-03T09:15:00-03:00"
  }
}

Vínculo não encontrado retorna 404 Not Found; demais erros de validação retornam 422 Unprocessable Entity.

Escopo: contato_departamento:write

`DELETE /contato-departamento/{vinculo_id}`

Remove um vínculo pelo ID. Quando não encontrado, retorna 404 Not Found.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`vinculo_id`	`int`	path	sim	ID do vínculo

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Vínculo removido com sucesso",
  "data": null
}

Escopo: contato_departamento:write

Schemas

`ContatoDepartamentoCreate`

Campo	Tipo	Obrigatório	Observações
`contato_id`	`int`	sim	ID do contato a ser vinculado.
`departamento_id`	`int`	sim	ID do departamento a ser vinculado.
`id_cliente`	`int \| null`	não	Cliente (`customer.id`) associado ao vínculo. Default `null`.

`ContatoDepartamentoUpdate`

Junção pura - apenas o vínculo de cliente é atualizável.

Campo	Tipo	Observações
`id_cliente`	`int \| null`	Reassocia (ou desassocia) o vínculo a um cliente.

`ContatoDepartamentoRead`

Campo	Tipo	Notas
`id`	`int`	Identificador do vínculo.
`contato_id`	`int`	Contato vinculado.
`departamento_id`	`int`	Departamento vinculado.
`id_cliente`	`int \| null`	Cliente associado, quando houver.
`data_hora_criacao`	`datetime`	Timestamp de criação do vínculo.

Notas

Toda resposta segue o envelope { success, message, data } (ou { success: false, message, details } em erro).
GET /contato-departamento/ retorna 200 OK com data: [] e a mensagem "Nenhum vínculo encontrado." quando nenhum registro corresponde aos filtros - não é tratado como erro.
Os filtros id_cliente, contato_id e departamento_id são independentes e podem ser combinados na mesma consulta.
Como se trata de uma tabela de junção pura, PUT altera somente o id_cliente; contato_id e departamento_id são definidos apenas na criação.