NFS-e/Repasse: Configuração Tributária

Endpoints da WebApiAlcance para a configuração tributária do produto NFS-e/Repasse Médico. Modelam o cabeçalho cadastro_tributario_prestador (uma ou várias regras por prestador, 1:N) e as três configurações 1:1 filhas de cada regra: tributos sobre faturamento (PIS/COFINS/CSLL/IRPJ), ISS e IR adicional. Cobrem criação, listagem, busca por prestador, detalhamento (com configs aninhadas), 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.

Escopo compartilhado do domínio NFS-e/Repasse

Este recurso pertence ao domínio NFS-e/Repasse, cujo 1º segmento de rota (nfse-repasse) é compartilhado por todos os sub-recursos do produto. Por isso os escopos são derivados desse primeiro segmento: nfse_repasse:read e nfse_repasse:write - e não de config-tributaria. Uma API Key com nfse_repasse:read habilita leitura em todo o domínio NFS-e/Repasse; conceda com parcimônia.

Base path

/api/v1/nfse-repasse/config-tributaria

Escopos necessários

nfse_repasse:read - listagens, busca por prestador, buscas por cadastro e detalhamento (GET)
nfse_repasse:write - criação, atualização e exclusão (POST/PUT/DELETE)

O escopo é derivado do 1º segmento da rota, /nfse-repasse (hífen → underscore ⇒ recurso nfse_repasse), compartilhado com os demais sub-recursos do produto. O método HTTP define a ação (read para GET, write para POST/PUT/DELETE).

Controle de acesso adicional (single-company)

Na migração SINGLE-COMPANY (app webapp-nfs-repasse-medico), além do escopo da API Key, a WebApi aplica: leitura (GET) liberada a qualquer staff autenticado; escrita (POST/PUT/DELETE) restrita ao perfil administrador. Chamadas de escrita sem esse perfil retornam 403 Forbidden.

Endpoints

Os endpoints organizam-se em quatro famílias: o cabeçalho (cadastro_tributario_prestador) e as três configs 1:1 (/tributos, /iss, /ir-adicional).

Ordem de rotas (FastAPI)

As rotas estáticas (/tributos, /iss, /ir-adicional, /by-prestador/{id_prestador}) são declaradas antes da rota dinâmica GET /{cadastro_id}. O FastAPI casa na ordem de declaração, então as estáticas são resolvidas primeiro (e tributos, iss etc. nunca são interpretados como um cadastro_id).

Cabeçalho - `cadastro_tributario_prestador`

`POST /nfse-repasse/config-tributaria/`

Cria um cadastro tributário (cabeçalho da regra). O id_usuario_created é preenchido a partir do usuário autenticado - não é aceito no corpo.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query - os dados vão no corpo da requisição (CadastroTributarioPrestadorCreate): id_prestador, nome_regra e vigente_em (obrigatórios), ativo (default true) e uuid_legado (opcional, metadado de migração).

Request

{
  "id_prestador": 1,
  "nome_regra": "Regra 2026",
  "vigente_em": "2026-01-01",
  "ativo": true
}

Response 201 Created

{
  "success": true,
  "message": "Cadastro tributário criado com sucesso!",
  "data": {
    "id": 1,
    "id_prestador": 1,
    "nome_regra": "Regra 2026",
    "vigente_em": "2026-01-01",
    "ativo": true,
    "uuid_legado": null,
    "id_usuario_created": 7,
    "created_at": "2026-01-01T12:00:00Z",
    "updated_at": "2026-01-01T12:00:00Z"
  }
}

Escopo: nfse_repasse:write

`GET /nfse-repasse/config-tributaria/by-prestador/{id_prestador}`

Lista os cadastros tributários de um prestador específico, com filtro opcional por regras ativas e paginação.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`id_prestador`	`int`	path	sim	ID do prestador (`prestador_medico.id`)
`ativo`	`bool`	query	não	Filtra por regras ativas
`page`	`int >= 1`	query	não	Página 1-based
`per_page`	`int 1..500`	query	não	Itens por página

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Cadastros recuperados com sucesso!",
  "data": [
    {
      "id": 1,
      "id_prestador": 1,
      "nome_regra": "Regra 2026",
      "vigente_em": "2026-01-01",
      "ativo": true,
      "uuid_legado": null,
      "id_usuario_created": 7,
      "created_at": "2026-01-01T12:00:00Z",
      "updated_at": "2026-01-01T12:00:00Z"
    }
  ]
}

Escopo: nfse_repasse:read

`GET /nfse-repasse/config-tributaria/`

Lista os cadastros tributários com filtros opcionais. Lista vazia é um estado válido e retorna 200 OK com data: [].

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`ativo`	`bool`	query	não	Filtra por regras ativas
`id_prestador`	`int`	query	não	Filtra por prestador
`page`	`int >= 1`	query	não	Página 1-based
`per_page`	`int 1..500`	query	não	Itens por página

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Cadastros recuperados com sucesso!",
  "data": [
    {
      "id": 1,
      "id_prestador": 1,
      "nome_regra": "Regra 2026",
      "vigente_em": "2026-01-01",
      "ativo": true,
      "uuid_legado": null,
      "id_usuario_created": 7,
      "created_at": "2026-01-01T12:00:00Z",
      "updated_at": "2026-01-01T12:00:00Z"
    }
  ]
}

Escopo: nfse_repasse:read

`GET /nfse-repasse/config-tributaria/{cadastro_id}`

Detalha um cadastro tributário pelo ID, com as três configs 1:1 aninhadas (config_tributos, config_iss, config_ir_adicional). Quando não encontrado, retorna 404 Not Found.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`cadastro_id`	`int`	path	sim	ID do cadastro tributário

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Cadastro tributário encontrado!",
  "data": {
    "id": 1,
    "id_prestador": 1,
    "nome_regra": "Regra 2026",
    "vigente_em": "2026-01-01",
    "ativo": true,
    "config_tributos": {
      "id": 10,
      "id_cadastro_tributario": 1,
      "pis_percentual": 0.65,
      "cofins_percentual": 3,
      "csll_percentual": 2.88,
      "irpj_percentual": 4.8
    },
    "config_iss": {
      "id": 11,
      "id_cadastro_tributario": 1,
      "tipo_iss": "percentual_faturamento",
      "aliquota_percentual": 5,
      "valor_por_medico": null
    },
    "config_ir_adicional": {
      "id": 12,
      "id_cadastro_tributario": 1,
      "aliquota_presuncao": 32,
      "limite_base": 20000,
      "aliquota_adicional": 10
    }
  }
}

Escopo: nfse_repasse:read

`PUT /nfse-repasse/config-tributaria/{cadastro_id}`

Atualiza um cadastro tributário. O corpo é um CadastroTributarioPrestadorUpdate com campos parciais - somente o que vier preenchido é alterado.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`cadastro_id`	`int`	path	sim	ID do cadastro tributário

Request (CadastroTributarioPrestadorUpdate - todos os campos opcionais: id_prestador, nome_regra, vigente_em, ativo)

{
  "nome_regra": "Regra 2026 - revisada",
  "ativo": false
}

Response 200 OK

{
  "success": true,
  "message": "Cadastro tributário atualizado!",
  "data": {
    "id": 1,
    "id_prestador": 1,
    "nome_regra": "Regra 2026 - revisada",
    "vigente_em": "2026-01-01",
    "ativo": false,
    "uuid_legado": null,
    "id_usuario_created": 7,
    "created_at": "2026-01-01T12:00:00Z",
    "updated_at": "2026-01-02T09:30:00Z"
  }
}

Escopo: nfse_repasse:write

`DELETE /nfse-repasse/config-tributaria/{cadastro_id}`

Remove um cadastro tributário pelo ID.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`cadastro_id`	`int`	path	sim	ID do cadastro tributário

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Cadastro tributário removido!",
  "data": null
}

Escopo: nfse_repasse:write

Config 1:1 - Tributos sobre faturamento

`POST /nfse-repasse/config-tributaria/tributos`

Cria a configuração de tributos (PIS/COFINS/CSLL/IRPJ) de um cadastro.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query - os dados vão no corpo da requisição (ConfiguracaoTributosRepasseCreate): id_cadastro_tributario (obrigatório) e os percentuais pis_percentual, cofins_percentual, csll_percentual e irpj_percentual (opcionais, com defaults).

Request

{
  "id_cadastro_tributario": 1,
  "pis_percentual": 0.65,
  "cofins_percentual": 3,
  "csll_percentual": 2.88,
  "irpj_percentual": 4.8
}

Response 201 Created

{
  "success": true,
  "message": "Configuração de tributos criada!",
  "data": {
    "id": 10,
    "id_cadastro_tributario": 1,
    "pis_percentual": 0.65,
    "cofins_percentual": 3,
    "csll_percentual": 2.88,
    "irpj_percentual": 4.8
  }
}

Escopo: nfse_repasse:write

`GET /nfse-repasse/config-tributaria/tributos/by-cadastro/{id_cadastro_tributario}`

Busca a configuração de tributos vinculada a um cadastro. 404 Not Found quando não existe.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`id_cadastro_tributario`	`int`	path	sim	ID do cadastro tributário (cabeçalho)

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Configuração de tributos encontrada!",
  "data": {
    "id": 10,
    "id_cadastro_tributario": 1,
    "pis_percentual": 0.65,
    "cofins_percentual": 3,
    "csll_percentual": 2.88,
    "irpj_percentual": 4.8
  }
}

Escopo: nfse_repasse:read

`PUT /nfse-repasse/config-tributaria/tributos/{config_id}`

Atualiza a configuração de tributos. O corpo é um ConfiguracaoTributosRepasseUpdate com campos parciais.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`config_id`	`int`	path	sim	ID da config de tributos

Request (ConfiguracaoTributosRepasseUpdate - todos os campos opcionais)

{
  "cofins_percentual": 3.5,
  "irpj_percentual": 5
}

Response 200 OK

{
  "success": true,
  "message": "Configuração de tributos atualizada!",
  "data": {
    "id": 10,
    "id_cadastro_tributario": 1,
    "pis_percentual": 0.65,
    "cofins_percentual": 3.5,
    "csll_percentual": 2.88,
    "irpj_percentual": 5
  }
}

Escopo: nfse_repasse:write

`DELETE /nfse-repasse/config-tributaria/tributos/{config_id}`

Remove a configuração de tributos pelo ID.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`config_id`	`int`	path	sim	ID da config de tributos

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Configuração de tributos removida!",
  "data": null
}

Escopo: nfse_repasse:write

Config 1:1 - ISS

`POST /nfse-repasse/config-tributaria/iss`

Cria a configuração de ISS de um cadastro.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query - os dados vão no corpo da requisição (ConfiguracaoIssPrestadorCreate): id_cadastro_tributario (obrigatório), tipo_iss (percentual_faturamento ou valor_por_medico), aliquota_percentual e valor_por_medico (opcionais).

Request

{
  "id_cadastro_tributario": 1,
  "tipo_iss": "percentual_faturamento",
  "aliquota_percentual": 5,
  "valor_por_medico": null
}

Response 201 Created

{
  "success": true,
  "message": "Configuração de ISS criada!",
  "data": {
    "id": 11,
    "id_cadastro_tributario": 1,
    "tipo_iss": "percentual_faturamento",
    "aliquota_percentual": 5,
    "valor_por_medico": null
  }
}

Escopo: nfse_repasse:write

`GET /nfse-repasse/config-tributaria/iss/by-cadastro/{id_cadastro_tributario}`

Busca a configuração de ISS vinculada a um cadastro. 404 Not Found quando não existe.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`id_cadastro_tributario`	`int`	path	sim	ID do cadastro tributário (cabeçalho)

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Configuração de ISS encontrada!",
  "data": {
    "id": 11,
    "id_cadastro_tributario": 1,
    "tipo_iss": "percentual_faturamento",
    "aliquota_percentual": 5,
    "valor_por_medico": null
  }
}

Escopo: nfse_repasse:read

`PUT /nfse-repasse/config-tributaria/iss/{config_id}`

Atualiza a configuração de ISS. O corpo é um ConfiguracaoIssPrestadorUpdate com campos parciais.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`config_id`	`int`	path	sim	ID da config de ISS

Request (ConfiguracaoIssPrestadorUpdate - todos os campos opcionais)

{
  "tipo_iss": "valor_por_medico",
  "valor_por_medico": 150,
  "aliquota_percentual": null
}

Response 200 OK

{
  "success": true,
  "message": "Configuração de ISS atualizada!",
  "data": {
    "id": 11,
    "id_cadastro_tributario": 1,
    "tipo_iss": "valor_por_medico",
    "aliquota_percentual": null,
    "valor_por_medico": 150
  }
}

Escopo: nfse_repasse:write

`DELETE /nfse-repasse/config-tributaria/iss/{config_id}`

Remove a configuração de ISS pelo ID.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`config_id`	`int`	path	sim	ID da config de ISS

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Configuração de ISS removida!",
  "data": null
}

Escopo: nfse_repasse:write

Config 1:1 - IR adicional

`POST /nfse-repasse/config-tributaria/ir-adicional`

Cria a configuração de IR adicional (presunção + adicional sobre o excedente) de um cadastro.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query - os dados vão no corpo da requisição (ConfiguracaoIrAdicionalCreate): id_cadastro_tributario (obrigatório) e aliquota_presuncao, limite_base e aliquota_adicional (opcionais, com defaults).

Request

{
  "id_cadastro_tributario": 1,
  "aliquota_presuncao": 32,
  "limite_base": 20000,
  "aliquota_adicional": 10
}

Response 201 Created

{
  "success": true,
  "message": "Configuração de IR adicional criada!",
  "data": {
    "id": 12,
    "id_cadastro_tributario": 1,
    "aliquota_presuncao": 32,
    "limite_base": 20000,
    "aliquota_adicional": 10
  }
}

Escopo: nfse_repasse:write

`GET /nfse-repasse/config-tributaria/ir-adicional/by-cadastro/{id_cadastro_tributario}`

Busca a configuração de IR adicional vinculada a um cadastro. 404 Not Found quando não existe.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`id_cadastro_tributario`	`int`	path	sim	ID do cadastro tributário (cabeçalho)

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Configuração de IR adicional encontrada!",
  "data": {
    "id": 12,
    "id_cadastro_tributario": 1,
    "aliquota_presuncao": 32,
    "limite_base": 20000,
    "aliquota_adicional": 10
  }
}

Escopo: nfse_repasse:read

`PUT /nfse-repasse/config-tributaria/ir-adicional/{config_id}`

Atualiza a configuração de IR adicional. O corpo é um ConfiguracaoIrAdicionalUpdate com campos parciais.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`config_id`	`int`	path	sim	ID da config de IR adicional

Request (ConfiguracaoIrAdicionalUpdate - todos os campos opcionais)

{
  "limite_base": 25000,
  "aliquota_adicional": 10
}

Response 200 OK

{
  "success": true,
  "message": "Configuração de IR adicional atualizada!",
  "data": {
    "id": 12,
    "id_cadastro_tributario": 1,
    "aliquota_presuncao": 32,
    "limite_base": 25000,
    "aliquota_adicional": 10
  }
}

Escopo: nfse_repasse:write

`DELETE /nfse-repasse/config-tributaria/ir-adicional/{config_id}`

Remove a configuração de IR adicional pelo ID.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`config_id`	`int`	path	sim	ID da config de IR adicional

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Configuração de IR adicional removida!",
  "data": null
}

Escopo: nfse_repasse:write

Schemas

`CadastroTributarioPrestadorCreate`

Cabeçalho da regra tributária.

Campo	Tipo	Obrigatório	Observações
`id_prestador`	`int`	sim	ID do prestador (`prestador_medico.id`) dono da regra.
`nome_regra`	`str` (≤ 200)	sim	Nome da regra tributária.
`vigente_em`	`date`	sim	Data de início de vigência (ex.: `2026-01-01`).
`ativo`	`bool`	não	Se a regra está ativa. Default `true`.
`uuid_legado`	`str` (≤ 36)	não	UUID do registro original no Supabase (rastreabilidade). Imutável.

CadastroTributarioPrestadorUpdate aceita os mesmos campos de negócio (id_prestador, nome_regra, vigente_em, ativo), todos opcionais. A leitura CadastroTributarioPrestadorRead acrescenta id, uuid_legado, id_usuario_created, created_at e updated_at; e CadastroTributarioPrestadorReadCompleto estende com as configs aninhadas config_tributos, config_iss e config_ir_adicional.

`ConfiguracaoTributosRepasseCreate`

Percentuais de PIS, COFINS, CSLL e IRPJ sobre o faturamento (valores Decimal).

Campo	Tipo	Obrigatório	Observações
`id_cadastro_tributario`	`int`	sim	ID do cadastro (cabeçalho) ao qual pertence.
`pis_percentual`	`Decimal ≥ 0`	não	Percentual de PIS. Default `0.65`.
`cofins_percentual`	`Decimal ≥ 0`	não	Percentual de COFINS. Default `3`.
`csll_percentual`	`Decimal ≥ 0`	não	Percentual de CSLL. Default `2.88`.
`irpj_percentual`	`Decimal ≥ 0`	não	Percentual de IRPJ. Default `4.8`.
`uuid_legado`	`str` (≤ 36)	não	Metadado de migração.

ConfiguracaoTributosRepasseUpdate aceita os quatro percentuais, todos opcionais. ConfiguracaoTributosRepasseRead acrescenta id, uuid_legado, id_usuario_created, created_at e updated_at.

`ConfiguracaoIssPrestadorCreate`

Configuração do ISS. O tipo_iss define qual valor é aplicado.

Campo	Tipo	Obrigatório	Observações
`id_cadastro_tributario`	`int`	sim	ID do cadastro (cabeçalho) ao qual pertence.
`tipo_iss`	`str` (≤ 30)	não	`percentual_faturamento` (default) ou `valor_por_medico`. Validado.
`aliquota_percentual`	`Decimal ≥ 0`	não	Alíquota ISS (%) - usada quando `tipo_iss = percentual_faturamento`.
`valor_por_medico`	`Decimal ≥ 0`	não	Valor fixo por médico (R$) - usado quando `tipo_iss = valor_por_medico`.
`uuid_legado`	`str` (≤ 36)	não	Metadado de migração.

ConfiguracaoIssPrestadorUpdate aceita tipo_iss, aliquota_percentual e valor_por_medico, todos opcionais (tipo_iss continua validado quando enviado). ConfiguracaoIssPrestadorRead acrescenta id, uuid_legado, id_usuario_created, created_at e updated_at.

`ConfiguracaoIrAdicionalCreate`

Configuração do IR adicional (presunção + adicional sobre o excedente).

Campo	Tipo	Obrigatório	Observações
`id_cadastro_tributario`	`int`	sim	ID do cadastro (cabeçalho) ao qual pertence.
`aliquota_presuncao`	`Decimal ≥ 0`	não	Alíquota de presunção (%). Default `32`.
`limite_base`	`Decimal ≥ 0`	não	Limite base (R$). Default `20000`.
`aliquota_adicional`	`Decimal ≥ 0`	não	Alíquota adicional (%). Default `10`.
`uuid_legado`	`str` (≤ 36)	não	Metadado de migração.

ConfiguracaoIrAdicionalUpdate aceita aliquota_presuncao, limite_base e aliquota_adicional, todos opcionais. ConfiguracaoIrAdicionalRead acrescenta id, uuid_legado, id_usuario_created, created_at e updated_at.

Notas

Toda resposta segue o envelope { success, message, data } (ou { success: false, message, details } em erro).
Um cadastro (cabeçalho) relaciona-se 1:1 com cada config filha: tributos, ISS e IR adicional. Use GET /{cadastro_id} para obter o cabeçalho já com as três configs aninhadas.
Valores tributários (percentuais e limites) são Decimal - espelham colunas Numeric no banco para preservar precisão.
id_usuario_created não entra nos payloads de criação: é preenchido pelo service com o usuário autenticado. uuid_legado é metadado de migração (aceito no Create, imutável depois).
Erros do service são mapeados por semântica de mensagem: "não encontrado" ⇒ 404, "já existe" ⇒ 409, "acesso negado" ⇒ 403, demais ⇒ 422.
Escrita (POST/PUT/DELETE) exige perfil administrador além do escopo nfse_repasse:write (ver Callout acima).