Atendimento: Contatos

Endpoints da WebApiAlcance para gerenciar contatos - as pessoas do app de Atendimento. Um contato é uma pessoa (geralmente vinculada a um cliente) com dados como nome, e-mail, telefone, data de nascimento e a indicação de ser sócio. Cobrem criação, listagem com filtro por cliente e paginação, detalhamento por ID, atualização 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/contatos

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

Escopos necessários

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

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

Endpoints

`POST /contatos/`

Cria um novo contato. Quando id_cliente é informado no corpo, o contato já é vinculado 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 (ContatoCreate): nome (obrigatório), email, telefone, data_nascimento, socio (default false) e id_cliente (opcional).

Request

{
  "nome": "Maria Souza",
  "email": "maria.souza@empresa.com.br",
  "telefone": "5571988887777",
  "data_nascimento": "1985-04-12",
  "socio": true,
  "id_cliente": 1234
}

Response 201 Created

{
  "success": true,
  "message": "Contato criado com sucesso",
  "data": {
    "id": 42,
    "nome": "Maria Souza",
    "email": "maria.souza@empresa.com.br",
    "telefone": "5571988887777",
    "data_nascimento": "1985-04-12",
    "socio": true,
    "id_cliente": 1234,
    "legacy_uuid": null,
    "data_hora_criacao": "2026-07-03T09:15:00-03:00"
  }
}

Quando a validação falha, retorna 422 Unprocessable Entity com o detail descrevendo o erro. Escopo: contatos:write

`GET /contatos/`

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

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`id_cliente`	`int`	query	não	Filtra pelos contatos de um cliente (`customer.id`).
`limit`	`int`	query	não	Limite de 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": "Contatos recuperados com sucesso",
  "data": [
    {
      "id": 42,
      "nome": "Maria Souza",
      "email": "maria.souza@empresa.com.br",
      "telefone": "5571988887777",
      "data_nascimento": "1985-04-12",
      "socio": true,
      "id_cliente": 1234,
      "legacy_uuid": null,
      "data_hora_criacao": "2026-07-03T09:15:00-03:00"
    }
  ]
}

Escopo: contatos:read

`GET /contatos/{contato_id}`

Detalha um contato pelo ID inteiro. Quando não encontrado, retorna 404 Not Found.

Parâmetros

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

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Contato recuperado com sucesso",
  "data": {
    "id": 42,
    "nome": "Maria Souza",
    "email": "maria.souza@empresa.com.br",
    "telefone": "5571988887777",
    "data_nascimento": "1985-04-12",
    "socio": true,
    "id_cliente": 1234,
    "legacy_uuid": null,
    "data_hora_criacao": "2026-07-03T09:15:00-03:00"
  }
}

Escopo: contatos:read

`PUT /contatos/{contato_id}`

Atualiza um contato existente. O body é um ContatoUpdate com campos parciais - somente o que vier preenchido é alterado. Por segurança, id_cliente e legacy_uuid não podem ser alterados por este endpoint (proteção contra mass-assignment).

Parâmetros

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

Request (ContatoUpdate - todos os campos opcionais)

{
  "telefone": "5571977776666",
  "socio": false
}

Response 200 OK

{
  "success": true,
  "message": "Contato atualizado com sucesso",
  "data": {
    "id": 42,
    "nome": "Maria Souza",
    "email": "maria.souza@empresa.com.br",
    "telefone": "5571977776666",
    "data_nascimento": "1985-04-12",
    "socio": false,
    "id_cliente": 1234,
    "legacy_uuid": null,
    "data_hora_criacao": "2026-07-03T09:15:00-03:00"
  }
}

Retorna 404 Not Found quando o contato não existe e 422 Unprocessable Entity em erro de validação. Escopo: contatos:write

`DELETE /contatos/{contato_id}`

Remove um contato pelo ID. Retorna 404 Not Found quando o contato não existe.

Parâmetros

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

Request

Sem corpo de requisição.

Response 200 OK

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

Escopo: contatos:write

Schemas

`ContatoCreate`

Campo	Tipo	Obrigatório	Observações
`nome`	`str`	sim	Nome do contato. Máx. 200 caracteres.
`email`	`str`	não	E-mail do contato. Máx. 255 caracteres. Default `null`.
`telefone`	`str`	não	Telefone do contato. Máx. 50 caracteres. Default `null`.
`data_nascimento`	`date`	não	Data de nascimento (`YYYY-MM-DD`). Default `null`.
`socio`	`bool`	não	Indica se o contato é sócio. Default `false`.
`id_cliente`	`int`	não	Vincula o contato a um cliente (`customer.id`). Default `null`.

`ContatoUpdate`

Todos os campos são opcionais; apenas os enviados são atualizados. id_cliente e legacy_uuid são omitidos deste schema para evitar mass-assignment.

Campo	Tipo	Observações
`nome`	`str`	Novo nome. Máx. 200 caracteres.
`email`	`str`	Novo e-mail. Máx. 255 caracteres.
`telefone`	`str`	Novo telefone. Máx. 50 caracteres.
`data_nascimento`	`date`	Nova data de nascimento (`YYYY-MM-DD`).
`socio`	`bool`	Redefine a indicação de sócio.

`ContatoRead`

Campo	Tipo	Notas
`id`	`int`	Identificador do contato.
`nome`	`str`	Nome do contato.
`email`	`str`	E-mail, quando informado.
`telefone`	`str`	Telefone, quando informado.
`data_nascimento`	`date`	Data de nascimento, quando informada.
`socio`	`bool`	Indica se o contato é sócio.
`id_cliente`	`int`	Cliente vinculado, quando houver.
`legacy_uuid`	`str`	Identificador legado, quando houver.
`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).
Na listagem, id_cliente é um filtro opcional via query string; para criar um contato já vinculado a um cliente, envie id_cliente no corpo do POST.
A paginação de GET /contatos/ usa limit (1-500, default 100) e offset (default 0).
legacy_uuid só aparece na leitura (ContatoRead); não pode ser definido nem alterado pelos endpoints de escrita.