Customer Employees

Endpoints da WebApiAlcance para gerenciar funcionários/colaboradores do cliente - o quadro de pessoal vinculado a cada cliente (pessoa física ou jurídica) da Alcance Contabilidade. Cobrem registro, listagem geral, listagem restrita a um cliente específico, detalhamento por ID, atualização e remoçã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-employees

Escopos necessários

customer_employees:read - listagem geral, listagem por cliente e detalhamento
customer_employees:write - registro, atualização e remoção

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

Endpoints

`POST /customer-employees/`

Registra um novo funcionário vinculado a um cliente. O usuário autenticado é gravado como autor do registro (id_user_created).

Parâmetros

Este endpoint não recebe parâmetros de rota ou query - os dados vão no corpo da requisição (CustomerEmployeeCreate). Campos obrigatórios: id_customer e nome; os demais (numero_dominio, cpf, rg, ativo, data_admissao, data_demissao) são opcionais.

Request

{
  "id_customer": 1234,
  "numero_dominio": "1001",
  "nome": "João da Silva",
  "cpf": "123.456.789-00",
  "rg": "12.345.678-9",
  "ativo": true,
  "data_admissao": "2025-02-01",
  "data_demissao": null
}

Response 200 OK

{
  "success": true,
  "message": "Funcionário registrado com sucesso!",
  "data": {
    "id": 501,
    "id_customer": 1234,
    "numero_dominio": "1001",
    "nome": "João da Silva",
    "cpf": "123.456.789-00",
    "rg": "12.345.678-9",
    "ativo": true,
    "data_admissao": "2025-02-01",
    "data_demissao": null
  }
}

Escopo: customer_employees:write

`GET /customer-employees/`

Lista todos os funcionários cadastrados. Quando não há registros, retorna 200 OK com data: [] e a mensagem "Nenhum funcionário encontrado.".

Parâmetros

Este endpoint não recebe parâmetros de rota ou query.

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Funcionários listados com sucesso!",
  "data": [
    { "id": 501, "id_customer": 1234, "nome": "João da Silva", "ativo": true },
    { "id": 502, "id_customer": 1234, "nome": "Maria Souza", "ativo": true }
  ]
}

Escopo: customer_employees:read

`GET /customer-employees/cliente/{id_customer}`

Lista os funcionários de um cliente específico. Lista vazia é um estado válido - retorna 200 OK com data: [] e a mensagem "Nenhum funcionário encontrado para este cliente.".

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`id_customer`	`int`	path	sim	ID do cliente (ver Customers)

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Funcionários do cliente listados com sucesso!",
  "data": [
    { "id": 501, "id_customer": 1234, "nome": "João da Silva", "ativo": true }
  ]
}

Escopo: customer_employees:read

`GET /customer-employees/{employee_id}`

Detalha um funcionário pelo ID inteiro. Quando não encontrado, retorna o envelope de erro com message: "Funcionário não encontrado.".

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`employee_id`	`int`	path	sim	ID interno do funcionário

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Funcionário encontrado!",
  "data": {
    "id": 501,
    "id_customer": 1234,
    "numero_dominio": "1001",
    "nome": "João da Silva",
    "cpf": "123.456.789-00",
    "rg": "12.345.678-9",
    "ativo": true,
    "data_admissao": "2025-02-01",
    "data_demissao": null,
    "id_user_created": 7,
    "data_hora_criacao": "2025-02-01T10:15:00",
    "data_hora_edicao": null
  }
}

Escopo: customer_employees:read

`PUT /customer-employees/{employee_id}`

Atualiza um funcionário existente. O body é um CustomerEmployeeUpdate com campos parciais - somente o que vier preenchido é alterado. Não inclui id_customer: o vínculo com o cliente não é alterado na atualização. Quando não encontrado, retorna o envelope de erro com message: "Funcionário não encontrado.".

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`employee_id`	`int`	path	sim	ID do funcionário

Request (CustomerEmployeeUpdate - todos os campos opcionais)

{
  "nome": "João da Silva Júnior",
  "ativo": false,
  "data_demissao": "2026-06-30"
}

Response 200 OK

{
  "success": true,
  "message": "Funcionário atualizado com sucesso!",
  "data": {
    "id": 501,
    "id_customer": 1234,
    "numero_dominio": "1001",
    "nome": "João da Silva Júnior",
    "cpf": "123.456.789-00",
    "rg": "12.345.678-9",
    "ativo": false,
    "data_admissao": "2025-02-01",
    "data_demissao": "2026-06-30",
    "id_user_created": 7,
    "data_hora_criacao": "2025-02-01T10:15:00",
    "data_hora_edicao": "2026-06-30T14:20:00"
  }
}

Escopo: customer_employees:write

`DELETE /customer-employees/{employee_id}`

Remove um funcionário pelo ID. Quando não encontrado, retorna o envelope de erro com message: "Funcionário não encontrado.".

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`employee_id`	`int`	path	sim	ID do funcionário

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Funcionário removido com sucesso!",
  "data": null
}

Escopo: customer_employees:write

Schemas

`CustomerEmployeeCreate`

Campo	Tipo	Obrigatório	Observações
`id_customer`	`int`	sim	ID do cliente ao qual o funcionário pertence.
`nome`	`str`	sim	Nome do funcionário.
`numero_dominio`	`str`	não	Código do funcionário no sistema Domínio.
`cpf`	`str`	não	CPF do funcionário.
`rg`	`str`	não	RG do funcionário.
`ativo`	`bool`	não	Situação do funcionário. Default `true`.
`data_admissao`	`date`	não	Data de admissão (`AAAA-MM-DD`).
`data_demissao`	`date`	não	Data de demissão (`AAAA-MM-DD`).

`CustomerEmployeeUpdate`

Todos os campos são opcionais; apenas os enviados são atualizados. Não inclui id_customer - o vínculo com o cliente não é alterado na atualização.

Campo	Tipo	Observações
`numero_dominio`	`str`	Novo código no sistema Domínio.
`nome`	`str`	Novo nome do funcionário.
`cpf`	`str`	Novo CPF.
`rg`	`str`	Novo RG.
`ativo`	`bool`	Nova situação (`false` para inativar).
`data_admissao`	`date`	Nova data de admissão.
`data_demissao`	`date`	Nova data de demissão.

`CustomerEmployeeRead`

Estende o CustomerEmployeeBase (todos os campos de CustomerEmployeeCreate) com os campos de auditoria abaixo.

Campo	Tipo	Notas
`id`	`int`	Identificador do funcionário.
`id_customer`	`int`	Cliente ao qual o funcionário pertence.
`numero_dominio`	`str`	Código no sistema Domínio.
`nome`	`str`	Nome do funcionário.
`cpf`	`str`	CPF.
`rg`	`str`	RG.
`ativo`	`bool`	Situação (`true` = ativo).
`data_admissao`	`date`	Data de admissão.
`data_demissao`	`date`	Data de demissão.
`id_user_created`	`int`	Usuário que registrou o funcionário.
`data_hora_criacao`	`datetime`	Timestamp de criação do registro.
`data_hora_edicao`	`datetime`	Timestamp da última edição do registro.

Notas

Toda resposta segue o envelope { success, message, data } (ou { success: false, message, details } em erro).
O POST /customer-employees/ retorna 200 OK (e não 201 Created) mesmo ao registrar um novo funcionário.
GET /customer-employees/cliente/{id_customer} é declarado antes da rota dinâmica GET /customer-employees/{employee_id}, então cliente é resolvido como rota estática (e não interpretado como um employee_id).
Falhas de "não encontrado" (detalhamento, atualização e remoção) retornam o envelope de erro com success: false, não um 404 com detail.
Relaciona-se com Customers: cada funcionário é vinculado a um cliente pelo campo id_customer.