Customer Dependente

Endpoints da WebApiAlcance para gerenciar dependentes de clientes - pessoas vinculadas a um cliente (customer) e, opcionalmente, a um sócio do quadro societário (customer_qsa). Cobrem criação, listagem dos dependentes do usuário autenticado, listagem por cliente, 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/customer-dependente

Escopos necessários

customer_dependente:read - listagem por usuário, listagem por cliente e detalhamento
customer_dependente:write - criação, atualização e exclusão

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

Endpoints

`POST /customer-dependente/`

Cria um novo dependente vinculado a um cliente e, opcionalmente, a um sócio do quadro societário. O id_usuario_created é derivado do usuário autenticado - não é aceito no corpo.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query - os dados vão no corpo da requisição (CustomerDependenteCreate). Campos obrigatórios: id_cliente e nome_completo.

Request

{
  "id_cliente": 1,
  "id_customer_qsa": 10,
  "status": "ativo",
  "nome_completo": "Maria da Silva",
  "data_nascimento": "1990-05-20",
  "cpf": "123.456.789-00",
  "grau_parentesco": "Filho(a)"
}

Response 201 Created

{
  "success": true,
  "message": "Dependente criado com sucesso!",
  "data": {
    "id": 1,
    "id_cliente": 1,
    "id_customer_qsa": 10,
    "status": "ativo",
    "nome_completo": "Maria da Silva",
    "data_nascimento": "1990-05-20",
    "cpf": "123.456.789-00",
    "grau_parentesco": "Filho(a)",
    "id_usuario_created": 42,
    "data_hora_criacao": "2026-07-03T14:30:00"
  }
}

Quando o cliente (ou sócio vinculado) não existe, retorna 404 Not Found; falhas de validação de campos retornam 422 Unprocessable Entity. Escopo: customer_dependente:write

`GET /customer-dependente/by-user`

Lista todos os dependentes do usuário autenticado, com filtro opcional por status e paginação. Lista vazia é um estado válido - sempre retorna 200 OK, inclusive com data: [] e a mensagem "Nenhum dependente encontrado.".

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`status`	`str`	query	não	Filtro por status (`ativo`, `inativo`, `suspenso`, `cancelado`).
`page`	`int`	query	não	Página (1-based, `>= 1`).
`per_page`	`int`	query	não	Itens por página (`1` a `500`).

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Dependentes recuperados com sucesso!",
  "data": [
    {
      "id": 1,
      "id_cliente": 1,
      "id_customer_qsa": 10,
      "status": "ativo",
      "nome_completo": "Maria da Silva",
      "data_nascimento": "1990-05-20",
      "cpf": "123.456.789-00",
      "grau_parentesco": "Filho(a)",
      "id_usuario_created": 42,
      "data_hora_criacao": "2026-07-03T14:30:00"
    }
  ]
}

Escopo: customer_dependente:read

`GET /customer-dependente/by-customer/{customer_id}`

Lista os dependentes de um cliente específico, com filtro opcional por status e paginação. Caso de uso primário do front. Quando o cliente não existe, retorna 404 Not Found.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`customer_id`	`int`	path	sim	ID do cliente (`customer.id`).
`status`	`str`	query	não	Filtro por status (`ativo`, `inativo`, `suspenso`, `cancelado`).
`page`	`int`	query	não	Página (1-based, `>= 1`).
`per_page`	`int`	query	não	Itens por página (`1` a `500`).

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Dependentes recuperados com sucesso!",
  "data": [
    {
      "id": 1,
      "id_cliente": 1,
      "id_customer_qsa": 10,
      "status": "ativo",
      "nome_completo": "Maria da Silva",
      "data_nascimento": "1990-05-20",
      "cpf": "123.456.789-00",
      "grau_parentesco": "Filho(a)",
      "id_usuario_created": 42,
      "data_hora_criacao": "2026-07-03T14:30:00"
    }
  ]
}

Escopo: customer_dependente:read

`GET /customer-dependente/{dependente_id}`

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

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`dependente_id`	`int`	path	sim	ID interno do dependente.

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Dependente encontrado!",
  "data": {
    "id": 1,
    "id_cliente": 1,
    "id_customer_qsa": 10,
    "status": "ativo",
    "nome_completo": "Maria da Silva",
    "data_nascimento": "1990-05-20",
    "cpf": "123.456.789-00",
    "grau_parentesco": "Filho(a)",
    "id_usuario_created": 42,
    "data_hora_criacao": "2026-07-03T14:30:00"
  }
}

Escopo: customer_dependente:read

`PUT /customer-dependente/{dependente_id}`

Atualiza um dependente existente. O corpo é um CustomerDependenteUpdate com campos parciais - somente o que vier preenchido é alterado. Os campos id, id_usuario_created, id_cliente e data_hora_criacao são imutáveis e não podem ser reatribuídos via update. Quando não encontrado, retorna 404 Not Found.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`dependente_id`	`int`	path	sim	ID do dependente.

Request (CustomerDependenteUpdate - todos os campos opcionais)

{
  "status": "inativo",
  "grau_parentesco": "Cônjuge"
}

Response 200 OK

{
  "success": true,
  "message": "Dependente atualizado!",
  "data": {
    "id": 1,
    "id_cliente": 1,
    "id_customer_qsa": 10,
    "status": "inativo",
    "nome_completo": "Maria da Silva",
    "data_nascimento": "1990-05-20",
    "cpf": "123.456.789-00",
    "grau_parentesco": "Cônjuge",
    "id_usuario_created": 42,
    "data_hora_criacao": "2026-07-03T14:30:00"
  }
}

Escopo: customer_dependente:write

`DELETE /customer-dependente/{dependente_id}`

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

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`dependente_id`	`int`	path	sim	ID do dependente.

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Dependente removido!",
  "data": null
}

Escopo: customer_dependente:write

Schemas

`CustomerDependenteCreate`

Campo	Tipo	Obrigatório	Observações
`id_cliente`	`int`	sim	ID do cliente (`customer.id`) ao qual o dependente pertence.
`nome_completo`	`str`	sim	Nome completo do dependente. De 1 a 100 caracteres.
`id_customer_qsa`	`int`	não	ID do sócio do quadro societário (`customer_qsa.id`).
`status`	`str`	não	`ativo`, `inativo`, `suspenso` ou `cancelado`. Default `ativo`.
`data_nascimento`	`date`	não	Data de nascimento (sem hora), formato `YYYY-MM-DD`.
`cpf`	`str`	não	CPF do dependente (apenas comprimento validado, máx. 14 caracteres).
`grau_parentesco`	`str`	não	Grau de parentesco (máx. 50 caracteres). Ex.: `Filho(a)`.

`CustomerDependenteUpdate`

Todos os campos são opcionais; apenas os enviados são atualizados. id_cliente não é reatribuível.

Campo	Tipo	Observações
`id_customer_qsa`	`int`	Vínculo opcional ao sócio (mutável).
`status`	`str`	`ativo`, `inativo`, `suspenso` ou `cancelado`.
`nome_completo`	`str`	De 1 a 100 caracteres.
`data_nascimento`	`date`	Formato `YYYY-MM-DD`.
`cpf`	`str`	Máx. 14 caracteres.
`grau_parentesco`	`str`	Máx. 50 caracteres.

`CustomerDependenteRead`

Estende os campos de CustomerDependenteCreate com os campos gerenciados abaixo.

Campo	Tipo	Notas
`id`	`int`	Identificador do dependente.
`id_cliente`	`int`	Cliente ao qual o dependente pertence.
`id_customer_qsa`	`int`	Sócio vinculado (opcional).
`status`	`str`	Status atual (`ativo` por padrão).
`nome_completo`	`str`	Nome completo do dependente.
`data_nascimento`	`date`	Data de nascimento (opcional).
`cpf`	`str`	CPF do dependente (opcional).
`grau_parentesco`	`str`	Grau de parentesco (opcional).
`id_usuario_created`	`int`	ID do usuário que criou (multi-tenant).
`data_hora_criacao`	`datetime`	Timestamp de criação (server-side).

Notas

Toda resposta segue o envelope { success, message, data } (ou { success: false, message, details } em erro).
As rotas estáticas GET /by-user e GET /by-customer/{customer_id} são declaradas antes da rota dinâmica GET /{dependente_id}, então são resolvidas como rotas estáticas (e não interpretadas como um dependente_id).
O campo cpf valida apenas o comprimento (máx. 14 caracteres) - não valida os dígitos verificadores.
O status aceita apenas os valores do ciclo de vida do dependente: ativo, inativo, suspenso e cancelado.
Relaciona-se com Customers, o cadastro de clientes ao qual cada dependente pertence.