Presunção: Palavra-chave

Endpoints da WebApiAlcance para gerenciar regras de presunção tributária por palavra-chave. Cada regra associa uma ou mais palavras-chave que podem aparecer na descrição do serviço prestado por um cliente a percentuais de presunção de IRPJ e CSLL - ou seja, a base de cálculo presumida aplicada no regime de Lucro Presumido. Quando a descrição de um serviço contém a palavra-chave configurada, as alíquotas de presunção correspondentes são aplicadas àquele item, permitindo tratar atividades distintas (ex.: serviços hospitalares a 8%/12% versus serviços em geral a 32%) dentro de um mesmo cliente.

Os endpoints cobrem criação, listagem de todas as regras, listagem das regras de 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. O Swagger oficial está em api.contabilidadealcance.com.br/docs.

Base path

/api/v1/presuncao-palavra-chave

Escopos necessários

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

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

Endpoints

`POST /presuncao-palavra-chave/`

Cria uma nova regra de presunção por palavra-chave. O usuário logado é registrado automaticamente como criador da regra (id_usuario_created) - 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 (PresuncaoPalavraChaveCreate): id_customer, palavras_chave, 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%, 0.08 para 8%).

Request

{
  "id_customer": 487,
  "palavras_chave": "hospital",
  "presuncao_irpj": "0.08",
  "presuncao_csll": "0.12"
}

Response 201 Created

{
  "success": true,
  "message": "Regra de presunção criada com sucesso",
  "data": {
    "id": 15,
    "id_customer": 487,
    "id_usuario_created": 12,
    "palavras_chave": "hospital",
    "presuncao_irpj": "0.08",
    "presuncao_csll": "0.12",
    "data_hora_criacao": "2026-07-03T10:15:00",
    "data_hora_edicao": null
  }
}

Em caso de dados inválidos (ex.: cliente inexistente ou alíquota fora do intervalo), retorna o envelope de erro { success: false, message }. Escopo: presuncao_palavra_chave:write

`GET /presuncao-palavra-chave/`

Lista todas as regras de presunção por palavra-chave. Lista vazia é um estado válido - sempre retorna 200 OK, inclusive com data: [] e a mensagem "Nenhuma regra de presunção por palavra-chave 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,
      "palavras_chave": "hospital",
      "presuncao_irpj": "0.08",
      "presuncao_csll": "0.12",
      "data_hora_criacao": "2026-07-03T10:15:00",
      "data_hora_edicao": null
    }
  ]
}

Escopo: presuncao_palavra_chave:read

`GET /presuncao-palavra-chave/by-customer/{id_customer}`

Lista todas as regras de presunção vinculadas a um cliente específico. Quando o cliente não possui regras, retorna 200 OK com data: [] e a mensagem "Nenhuma regra encontrada para este cliente.".

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`id_customer`	`int`	path	sim	ID interno do cliente (`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,
      "palavras_chave": "hospital",
      "presuncao_irpj": "0.08",
      "presuncao_csll": "0.12",
      "data_hora_criacao": "2026-07-03T10:15:00",
      "data_hora_edicao": null
    }
  ]
}

Escopo: presuncao_palavra_chave:read

`GET /presuncao-palavra-chave/{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,
    "palavras_chave": "hospital",
    "presuncao_irpj": "0.08",
    "presuncao_csll": "0.12",
    "data_hora_criacao": "2026-07-03T10:15:00",
    "data_hora_edicao": null
  }
}

Escopo: presuncao_palavra_chave:read

`PUT /presuncao-palavra-chave/{regra_id}`

Atualiza uma regra existente. O body é um PresuncaoPalavraChaveUpdate com campos parciais - somente o que vier preenchido é alterado. 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 da regra

Request (PresuncaoPalavraChaveUpdate - todos os campos opcionais)

{
  "palavras_chave": "hospital, clinica",
  "presuncao_irpj": "0.08",
  "presuncao_csll": "0.12"
}

Response 200 OK

{
  "success": true,
  "message": "Regra de presunção atualizada com sucesso",
  "data": {
    "id": 15,
    "id_customer": 487,
    "id_usuario_created": 12,
    "palavras_chave": "hospital, clinica",
    "presuncao_irpj": "0.08",
    "presuncao_csll": "0.12",
    "data_hora_criacao": "2026-07-03T10:15:00",
    "data_hora_edicao": "2026-07-03T11:42:00"
  }
}

Escopo: presuncao_palavra_chave:write

`DELETE /presuncao-palavra-chave/{regra_id}`

Remove uma regra de presunção pelo ID. 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 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_palavra_chave:write

Schemas

`PresuncaoPalavraChaveCreate`

Campo	Tipo	Obrigatório	Observações
`id_customer`	`int`	sim	Cliente ao qual a regra se aplica (FK `customers.id`).
`palavras_chave`	`str`	sim	Palavra(s)-chave buscada(s) na descrição do serviço. 1-500 caracteres.
`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`).

`PresuncaoPalavraChaveUpdate`

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

Campo	Tipo	Observações
`palavras_chave`	`str`	Nova(s) palavra(s)-chave. 1-500 caracteres.
`presuncao_irpj`	`Decimal`	Nova alíquota de presunção do IRPJ (fração decimal entre `0` e `1`).
`presuncao_csll`	`Decimal`	Nova alíquota de presunção da CSLL (fração decimal entre `0` e `1`).

`PresuncaoPalavraChaveRead`

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.
`palavras_chave`	`str`	Palavra(s)-chave configurada(s).
`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?`	Data/hora de criação da regra.
`data_hora_edicao`	`datetime?`	Data/hora da última edição (`null` se nunca editada).

Notas

Toda resposta segue o envelope { success, message, data } (ou { success: false, message } em erro).
As alíquotas de presunção são armazenadas e retornadas como fração decimal entre 0 e 1 - 0.32 equivale a 32%, 0.08 a 8%. Valores fora desse intervalo são rejeitados na validação.
GET /presuncao-palavra-chave/by-customer/{id_customer} é declarado antes da rota dinâmica GET /presuncao-palavra-chave/{regra_id}, então by-customer é resolvido como rota estática (e não interpretado como um regra_id).
Relaciona-se com Customers, que fornece o id_customer referenciado por cada regra.