Customer Services

Endpoints da WebApiAlcance para gerenciar serviços de cliente - os serviços contratados por cada cliente da Alcance Contabilidade (ex.: "Contabilidade Mensal"). Cobrem criação, listagem geral, listagem restrita a um cliente específico, detalhamento por ID, atualização parcial e exclusão.

Base path

/api/v1/customer-services

Escopos necessários

• customer_services:read - listagem geral, listagem por cliente e detalhamento
• customer_services:write - criação, atualização e exclusão

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

Endpoints

POST /customer-services/

Cria um novo serviço de cliente vinculado a um cliente existente. O usuário responsável pela criação é registrado a partir do usuário autenticado.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query - os dados vão no corpo da requisição (CustomerServiceCreate): nome (obrigatório), id_cliente (obrigatório), id_usuario (obrigatório) e ativo (opcional, default true).

Request

{
  "nome": "Contabilidade Mensal",
  "id_cliente": 1,
  "id_usuario": 1,
  "ativo": true
}

Response 201 Created

{
  "success": true,
  "message": "Serviço de cliente criado com sucesso",
  "data": {
    "id": 42,
    "nome": "Contabilidade Mensal",
    "id_cliente": 1,
    "id_usuario": 1,
    "ativo": true
  }
}

Quando o cliente informado em id_cliente não existe, retorna 404 Not Found com detail descrevendo o erro.

Escopo: customer_services:write

GET /customer-services/

Lista todos os serviços de clientes cadastrados. Lista vazia é um estado válido - sempre retorna 200 OK, inclusive com data: [] e a mensagem "Nenhum serviço de cliente 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": "Lista de serviços de clientes recuperada com sucesso",
  "data": [
    { "id": 42, "nome": "Contabilidade Mensal", "id_cliente": 1, "id_usuario": 1, "ativo": true },
    { "id": 43, "nome": "Folha de Pagamento", "id_cliente": 1, "id_usuario": 2, "ativo": true }
  ]
}

Escopo: customer_services:read

GET /customer-services/by-customer/{id_cliente}

Lista os serviços de um cliente específico. Quando o cliente não possui serviços, retorna 200 OK com data: [] e a mensagem "Nenhum serviço encontrado para este cliente.".

Parâmetros

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Serviços do cliente recuperados com sucesso",
  "data": [
    { "id": 42, "nome": "Contabilidade Mensal", "id_cliente": 1, "id_usuario": 1, "ativo": true },
    { "id": 43, "nome": "Folha de Pagamento", "id_cliente": 1, "id_usuario": 2, "ativo": true }
  ]
}

Escopo: customer_services:read

GET /customer-services/{service_id}

Detalha um serviço de cliente pelo ID inteiro. Quando não encontrado, retorna o envelope de erro com message: "Serviço de cliente não encontrado.".

Parâmetros

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Serviço de cliente encontrado com sucesso",
  "data": {
    "id": 42,
    "nome": "Contabilidade Mensal",
    "id_cliente": 1,
    "id_usuario": 1,
    "ativo": true,
    "data_hora_criacao": "2026-01-15T10:30:00",
    "data_hora_atualizacao": "2026-02-01T09:00:00"
  }
}

Escopo: customer_services:read

PUT /customer-services/{service_id}

Atualiza um serviço existente. O body é um CustomerServiceUpdate com campos parciais - somente o que vier preenchido é alterado. Os campos id_cliente e id_usuario não são editáveis (proteção contra mass-assignment e troca de dono/cliente do recurso); para mudar o cliente do serviço, exclua e crie novamente.

Parâmetros

Request (CustomerServiceUpdate - todos os campos opcionais)

{
  "nome": "Contabilidade Mensal Premium",
  "ativo": false
}

Response 200 OK

{
  "success": true,
  "message": "Serviço de cliente atualizado com sucesso",
  "data": {
    "id": 42,
    "nome": "Contabilidade Mensal Premium",
    "id_cliente": 1,
    "id_usuario": 1,
    "ativo": false,
    "data_hora_criacao": "2026-01-15T10:30:00",
    "data_hora_atualizacao": "2026-07-08T11:42:00"
  }
}

Quando não encontrado, retorna o envelope de erro com message: "Serviço de cliente não encontrado.".

Escopo: customer_services:write

DELETE /customer-services/{service_id}

Remove um serviço de cliente pelo ID. Quando não encontrado, retorna o envelope de erro com message: "Serviço de cliente não encontrado.".

Parâmetros

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Serviço de cliente deletado com sucesso",
  "data": null
}

Escopo: customer_services:write

Schemas

CustomerServiceCreate

CustomerServiceUpdate

Todos os campos são opcionais; apenas os enviados são atualizados. id_cliente e id_usuario não podem ser alterados.

CustomerServiceRead

Notas

• Toda resposta segue o envelope { success, message, data } (ou { success: false, message, details } em erro).
• GET /customer-services/by-customer/{id_cliente} é declarado antes da rota dinâmica GET /customer-services/{service_id}, então by-customer é resolvido como rota estática (e não interpretado como um service_id).
• Relaciona-se com Customers: cada serviço aponta para um cliente via id_cliente.