Atendimento: Contatos
Endpoints da WebApiAlcance para gerenciar contatos - as pessoas cadastradas no Hub (o antigo app de Atendimento foi descomissionado em 14/10/2026 e o atendimento migrou para o Hub). 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, importação de planilha CSV, listagem com filtros por cliente e sócio 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.
Base path
/api/v1/contatosA URL completa em produção é https://api.contabilidadealcance.com.br/api/v1/contatos.
Escopos necessários
contatos:read- listagem e detalhamentocontatos:write- criação, importação de planilha, 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
{
"status": "success",
"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
POST /contatos/importacoes
Importa contatos de uma planilha CSV (multipart/form-data). Síncrona e idempotente: reimportar o mesmo arquivo não duplica. Linha inválida não impede as válidas; o relatório lista os erros por linha. Além do escopo, exige permissão adicional; sem ela, a resposta é 403.
Parâmetros
| Parâmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
arquivo | file | form | sim | CSV (.csv) com separador ; ou ,, até 4 MB e 50.000 linhas. |
criar_departamentos | bool | form | não | Default false. true cria os departamentos ausentes. |
Colunas do CSV
| Cabeçalho | Obrigatório | Observações |
|---|---|---|
CNPJ | sim | Identifica a empresa cadastrada. |
Nome do Contato | sim | Nome do contato. |
Telefone do Contato | não | Telefone. |
Email do Contato | não | E-mail. |
Departamentos do Contato | não | Departamentos separados por vírgula; geram os vínculos contato-departamento. |
O contato é localizado pelo e-mail e, na falta, pelo nome. Em contato existente, só e-mail e telefone vazios são preenchidos.
Request
multipart/form-data com o arquivo no campo arquivo.
Response 200 OK
{
"status": "success",
"message": "8 contato(s) criado(s), 2 atualizado(s), 1 erro(s).",
"data": {
"total_linhas": 11,
"contatos_criados": 8,
"contatos_atualizados": 2,
"contatos_ambiguos": 0,
"telefones_fora_do_padrao": 1,
"vinculos_criados": 12,
"departamentos_criados": [],
"departamentos_criados_total": 0,
"erros": [{ "linha": 5, "campo": "CNPJ", "motivo": "CNPJ inválido" }],
"erros_total": 1,
"avisos": [],
"avisos_total": 0
}
}erros, avisos e departamentos_criados listam no máximo 200 itens; o total real vem em *_total.
Erros: 413 arquivo acima do limite; 422 cabeçalho obrigatório ausente, encoding inválido, mais de 50.000 linhas ou arquivo binário (nada é gravado); 429 excesso de requisições.
Escopo: contatos:write + permissão adicional (sem ela, 403)
GET /contatos/
Lista contatos. Aceita filtros por cliente e por sócio, 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. |
socio | bool | query | não | true: só sócios; false: só não sócios; ausente: todos. |
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
{
"status": "success",
"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
{
"status": "success",
"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
{
"status": "success",
"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
{
"status": "success",
"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. 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 de sucesso segue o envelope
{ status, message, data }. Erros usam{ message }(ou{ detail }no422de validação) com o status HTTP correspondente. - Na listagem,
id_clienteé um filtro opcional via query string; para criar um contato já vinculado a um cliente, envieid_clienteno corpo doPOST. - A paginação de
GET /contatos/usalimit(1-500, default 100) eoffset(default 0). legacy_uuidsó aparece na leitura (ContatoRead); não pode ser definido nem alterado pelos endpoints de escrita.