Presunção: Código de Serviço

Endpoints da WebApiAlcance para gerenciar regras de presunção tributária por código de serviço. No regime de Lucro Presumido, a base de cálculo do IRPJ e da CSLL é obtida aplicando-se um percentual de presunção sobre a receita bruta, e esse percentual varia conforme a atividade - identificada pelos códigos de serviço (itens da lista da LC 116/2003, ex.: 4.01, 4.02). Cada regra associa um conjunto de códigos de serviço de um cliente às suas alíquotas de presunção de IRPJ e CSLL, permitindo calcular corretamente a base tributável de cada nota. Os endpoints cobrem criação, listagem geral, 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/presuncao-codigo-servico

Escopos necessários

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

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

Endpoints

`POST /presuncao-codigo-servico/`

Cria uma nova regra de presunção por código de serviço para um cliente. O id_usuario_created é preenchido a partir do usuário autenticado - não é aceito no body.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query - os dados vão no corpo da requisição (PresuncaoCodigoServicoCreate): id_customer, nome, codigos, presuncao_irpj e presuncao_csll, todos obrigatórios. As alíquotas devem ser informadas como fração decimal entre 0 e 1 (ex.: 0.32 para 32%).

Request

{
  "id_customer": 487,
  "nome": "Consultas médicas",
  "codigos": ["4.01", "4.02"],
  "presuncao_irpj": "0.32",
  "presuncao_csll": "0.32"
}

Response 201 Created

{
  "success": true,
  "message": "Regra de presunção criada com sucesso",
  "data": {
    "id": 15,
    "id_customer": 487,
    "id_usuario_created": 12,
    "nome": "Consultas médicas",
    "codigos": ["4.01", "4.02"],
    "presuncao_irpj": "0.32",
    "presuncao_csll": "0.32",
    "data_hora_criacao": "2026-07-03T09:12:44",
    "data_hora_edicao": null
  }
}

Em caso de dados inválidos (ex.: alíquota fora do intervalo 0-1), retorna o envelope de erro { success: false, message, ... }. Escopo: presuncao_codigo_servico:write

`GET /presuncao-codigo-servico/`

Lista todas as regras de presunção por código de serviço acessíveis ao usuário autenticado. Lista vazia é um estado válido - sempre retorna 200 OK, inclusive com data: [] e a mensagem "Nenhuma regra de presunção por código encontrada.".

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": "Regras recuperadas com sucesso",
  "data": [
    {
      "id": 15,
      "id_customer": 487,
      "id_usuario_created": 12,
      "nome": "Consultas médicas",
      "codigos": ["4.01", "4.02"],
      "presuncao_irpj": "0.32",
      "presuncao_csll": "0.32",
      "data_hora_criacao": "2026-07-03T09:12:44",
      "data_hora_edicao": null
    }
  ]
}

Escopo: presuncao_codigo_servico:read

`GET /presuncao-codigo-servico/by-customer/{id_customer}`

Lista as regras de presunção de um cliente específico. Retorna data: [] (com 200 OK) e a mensagem "Nenhuma regra encontrada para este cliente." quando o cliente não possui regras cadastradas.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`id_customer`	`int`	path	sim	ID do cliente (FK `customers.id`).

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Regras do cliente recuperadas com sucesso",
  "data": [
    {
      "id": 15,
      "id_customer": 487,
      "id_usuario_created": 12,
      "nome": "Consultas médicas",
      "codigos": ["4.01", "4.02"],
      "presuncao_irpj": "0.32",
      "presuncao_csll": "0.32",
      "data_hora_criacao": "2026-07-03T09:12:44",
      "data_hora_edicao": null
    }
  ]
}

Escopo: presuncao_codigo_servico:read

`GET /presuncao-codigo-servico/{regra_id}`

Detalha uma regra pelo ID inteiro. Quando não encontrada, retorna o envelope de erro com "Regra de presunção não encontrada.".

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`regra_id`	`int`	path	sim	ID interno da regra.

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Regra de presunção encontrada com sucesso",
  "data": {
    "id": 15,
    "id_customer": 487,
    "id_usuario_created": 12,
    "nome": "Consultas médicas",
    "codigos": ["4.01", "4.02"],
    "presuncao_irpj": "0.32",
    "presuncao_csll": "0.32",
    "data_hora_criacao": "2026-07-03T09:12:44",
    "data_hora_edicao": null
  }
}

Escopo: presuncao_codigo_servico:read

`PUT /presuncao-codigo-servico/{regra_id}`

Atualiza uma regra existente. O body é um PresuncaoCodigoServicoUpdate com campos parciais - somente o que vier preenchido é alterado. Quando a regra não existe, retorna o envelope de erro com "Regra de presunção não encontrada.".

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`regra_id`	`int`	path	sim	ID da regra.

Request (PresuncaoCodigoServicoUpdate - todos os campos opcionais)

{
  "nome": "Consultas e exames médicos",
  "presuncao_irpj": "0.32",
  "presuncao_csll": "0.32"
}

Response 200 OK

{
  "success": true,
  "message": "Regra de presunção atualizada com sucesso",
  "data": {
    "id": 15,
    "id_customer": 487,
    "id_usuario_created": 12,
    "nome": "Consultas e exames médicos",
    "codigos": ["4.01", "4.02"],
    "presuncao_irpj": "0.32",
    "presuncao_csll": "0.32",
    "data_hora_criacao": "2026-07-03T09:12:44",
    "data_hora_edicao": "2026-07-03T11:42:00"
  }
}

Escopo: presuncao_codigo_servico:write

`DELETE /presuncao-codigo-servico/{regra_id}`

Remove uma regra de presunção pelo ID. Quando a regra não existe, retorna o envelope de erro com "Regra de presunção não encontrada.".

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`regra_id`	`int`	path	sim	ID da regra.

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Regra de presunção deletada com sucesso",
  "data": null
}

Escopo: presuncao_codigo_servico:write

Schemas

`PresuncaoCodigoServicoCreate`

Campo	Tipo	Obrigatório	Observações
`id_customer`	`int`	sim	ID do cliente ao qual a regra pertence.
`nome`	`str`	sim	Nome descritivo da regra (1-200 caracteres). Ex.: `"Consultas médicas"`.
`codigos`	`List[str]`	sim	Códigos de serviço abrangidos pela regra. Ex.: `["4.01", "4.02"]`.
`presuncao_irpj`	`Decimal`	sim	Alíquota de presunção do IRPJ, em fração decimal entre `0` e `1` (ex.: `0.32`).
`presuncao_csll`	`Decimal`	sim	Alíquota de presunção da CSLL, em fração decimal entre `0` e `1` (ex.: `0.32`).

`PresuncaoCodigoServicoUpdate`

Todos os campos são opcionais; apenas os enviados são atualizados.

Campo	Tipo	Observações
`nome`	`str`	Novo nome da regra (1-200 caracteres).
`codigos`	`List[str]`	Nova lista de códigos de serviço.
`presuncao_irpj`	`Decimal`	Nova alíquota de IRPJ (fração decimal entre `0` e `1`).
`presuncao_csll`	`Decimal`	Nova alíquota de CSLL (fração decimal entre `0` e `1`).

`PresuncaoCodigoServicoRead`

Campo	Tipo	Notas
`id`	`int`	Identificador da regra.
`id_customer`	`int`	Cliente vinculado (FK `customers.id`).
`id_usuario_created`	`int`	Usuário Alcance que criou a regra.
`nome`	`str`	Nome descritivo da regra.
`codigos`	`List[str]`	Códigos de serviço abrangidos.
`presuncao_irpj`	`Decimal`	Alíquota de presunção do IRPJ (fração decimal).
`presuncao_csll`	`Decimal`	Alíquota de presunção da CSLL (fração decimal).
`data_hora_criacao`	`datetime?`	Quando a regra foi criada.
`data_hora_edicao`	`datetime?`	Última edição (`null` enquanto nunca editada).

Notas

Toda resposta segue o envelope { success, message, data } (ou { success: false, message, ... } em erro).
As alíquotas presuncao_irpj e presuncao_csll são frações decimais entre 0 e 1 - informe 0.32 para 32% e 0.05 para 5%. Valores fora desse intervalo são rejeitados na validação.
GET /presuncao-codigo-servico/by-customer/{id_customer} é declarado antes da rota dinâmica GET /presuncao-codigo-servico/{regra_id}, garantindo que by-customer seja resolvido como rota estática (e não interpretado como um regra_id).
O campo id_usuario_created é preenchido automaticamente a partir do usuário autenticado no POST; não é enviado no body.