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.

Todos os endpoints exigem autenticação. Veja Autenticação para o fluxo de API Key.

Base path

/api/v1/customer-services

Escopos necessários

  • customer_services:read - listagem geral, listagem por cliente e detalhamento
  • customer_services:write - criação, importação por planilha, 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

{
  "status": "success",
  "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

{
  "status": "success",
  "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

ParâmetroTipoLocalObrigatórioDescrição
id_clienteintpathsimID interno do cliente

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "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

POST /customer-services/importar

Importa em lote os serviços (setores e responsáveis) por cliente a partir de uma planilha .xlsx ou .xltx. Restrita a usuários com permissão adicional; sem ela, a resposta é 403. Erros de linha ou de setor não abortam a importação: cada problema vira uma entrada em erros e o restante da planilha é processado.

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
planilhaUploadFileform (multipart)simPlanilha .xlsx ou .xltx de serviços por cliente.

A planilha traz o CPF/CNPJ do cliente e, para cada setor (Fiscal, Pessoal, Contábil, Financeiro), uma flag S para marcar o setor e o nome do responsável. Qualquer outro valor na flag é reportado como erro; célula em branco é ignorada.

Request

Envio multipart/form-data com o campo planilha. Não usa corpo JSON.

Response 200 OK

{
  "status": "success",
  "message": "210 criado(s), 227 atualizado(s), 0 ignorado(s), 1 erro(s).",
  "data": {
    "criados": 210,
    "atualizados": 227,
    "ignorados": 0,
    "erros": [
      {
        "linha": 2,
        "cpfecnpj": "12.345.678/0001-90",
        "setor": null,
        "motivo": "Cliente não encontrado para o CPF/CNPJ informado."
      }
    ]
  }
}

Erros: 400 para extensão não suportada, arquivo inválido ou planilha acima do limite de linhas; 413 para arquivo acima do limite de tamanho. Falha ao gravar o lote retorna status: "error" com a mensagem "Erro ao importar a planilha de serviços.".

Relatório de erros

setor vem null quando o erro é do cliente da linha inteira. O responsável é resolvido pelo nome entre os usuários ativos; nome não encontrado ou ambíguo gera erro naquele setor.

Escopo: customer_services:write (restrita a usuários com permissão adicional; sem ela, 403)

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

ParâmetroTipoLocalObrigatórioDescrição
service_idintpathsimID interno do serviço

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "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

ParâmetroTipoLocalObrigatórioDescrição
service_idintpathsimID interno do serviço

Request (CustomerServiceUpdate - todos os campos opcionais)

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

Response 200 OK

{
  "status": "success",
  "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

ParâmetroTipoLocalObrigatórioDescrição
service_idintpathsimID interno do serviço

Request

Sem corpo de requisição.

Response 200 OK

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

Escopo: customer_services:write

Schemas

CustomerServiceCreate

CampoTipoObrigatórioObservações
nomestrsimNome do serviço (1 a 200 caracteres). Ex.: Contabilidade Mensal.
id_clienteintsimID do cliente que contrata o serviço.
id_usuariointsimID do usuário responsável pelo serviço.
ativoboolnãoSituação do serviço. Default true.

CustomerServiceUpdate

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

CampoTipoObservações
nomestrNovo nome do serviço (1 a 200 caracteres).
ativoboolNova situação (true = ativo).

CustomerServiceRead

CampoTipoNotas
idintIdentificador do serviço.
nomestrNome do serviço.
id_clienteintCliente que contrata o serviço.
id_usuariointUsuário responsável pelo serviço.
ativoboolSituação (true = ativo).
data_hora_criacaodatetimeData/hora de criação do registro.
data_hora_atualizacaodatetimeData/hora da última atualização.

Notas

  • Toda resposta segue o envelope { status, message, data } (ou { status: "error", 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.