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/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, 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âmetroTipoLocalObrigatórioDescrição
arquivofileformsimCSV (.csv) com separador ; ou ,, até 4 MB e 50.000 linhas.
criar_departamentosboolformnãoDefault false. true cria os departamentos ausentes.

Colunas do CSV

CabeçalhoObrigatórioObservações
CNPJsimIdentifica a empresa cadastrada.
Nome do ContatosimNome do contato.
Telefone do ContatonãoTelefone.
Email do ContatonãoE-mail.
Departamentos do ContatonãoDepartamentos 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âmetroTipoLocalObrigatórioDescrição
id_clienteintquerynãoFiltra pelos contatos de um cliente.
socioboolquerynãotrue: só sócios; false: só não sócios; ausente: todos.
limitintquerynãoLimite de itens por página. Default 100, entre 1 e 500.
offsetintquerynãoOffset 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âmetroTipoLocalObrigatórioDescrição
contato_idintpathsimID 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âmetroTipoLocalObrigatórioDescrição
contato_idintpathsimID 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âmetroTipoLocalObrigatórioDescrição
contato_idintpathsimID 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

CampoTipoObrigatórioObservações
nomestrsimNome do contato. Máx. 200 caracteres.
emailstrnãoE-mail do contato. Máx. 255 caracteres. Default null.
telefonestrnãoTelefone do contato. Máx. 50 caracteres. Default null.
data_nascimentodatenãoData de nascimento (YYYY-MM-DD). Default null.
socioboolnãoIndica se o contato é sócio. Default false.
id_clienteintnãoVincula 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.

CampoTipoObservações
nomestrNovo nome. Máx. 200 caracteres.
emailstrNovo e-mail. Máx. 255 caracteres.
telefonestrNovo telefone. Máx. 50 caracteres.
data_nascimentodateNova data de nascimento (YYYY-MM-DD).
socioboolRedefine a indicação de sócio.

ContatoRead

CampoTipoNotas
idintIdentificador do contato.
nomestrNome do contato.
emailstrE-mail, quando informado.
telefonestrTelefone, quando informado.
data_nascimentodateData de nascimento, quando informada.
socioboolIndica se o contato é sócio.
id_clienteintCliente vinculado, quando houver.
legacy_uuidstrIdentificador legado, quando houver.
data_hora_criacaodatetimeTimestamp de criação do registro.

Notas

  • Toda resposta de sucesso segue o envelope { status, message, data }. Erros usam { message } (ou { detail } no 422 de 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, 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.