Customer Fiscal Config

Endpoints da WebApiAlcance para gerenciar a configuração fiscal do cliente - os parâmetros tributários (alíquotas de PIS, COFINS, ISS e percentuais de presunção de IRPJ/CSLL, além do regime de apuração e observações) associados a um cliente. A relação é 1:1 com customer: cada cliente tem no máximo uma configuração fiscal. Cobrem criação, listagem paginada, busca pelo ID da configuração, busca pelo ID do cliente, 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/customer-fiscal-config

Escopos necessários

customer_fiscal_config:read - listagem, busca por ID e busca pelo ID do cliente
customer_fiscal_config:write - criação, atualização e exclusão

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

Multi-tenant

As configurações são isoladas por usuário: cada operação atua apenas sobre as configs do usuário autenticado (id_usuario_created). Acessar a config de outro usuário resulta em 403 Acesso negado ou 404 Não encontrado.

Endpoints

`POST /customer-fiscal-config/`

Cria uma nova configuração fiscal vinculada a um cliente (relação 1:1 com customer). 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 (CustomerFiscalConfigCreate): id_customer (obrigatório) e as alíquotas/percentuais opcionais em fração decimal entre 0 e 1 (ex.: 0.0065 = 0,65%).

Request

{
  "id_customer": 1234,
  "aliquota_pis": "0.0065",
  "aliquota_cofins": "0.0760",
  "aliquota_iss": "0.0500",
  "aliquota_irpj_base": "0.0800",
  "aliquota_csll_base": "0.1200",
  "regime_apuracao": "trimestral",
  "observacoes": "Cliente optante por anexo III com fator R."
}

Response 201 Created

{
  "success": true,
  "message": "Configuração fiscal criada com sucesso!",
  "data": {
    "id": 1,
    "id_customer": 1234,
    "aliquota_pis": "0.0065",
    "aliquota_cofins": "0.0760",
    "aliquota_iss": "0.0500",
    "aliquota_irpj_base": "0.0800",
    "aliquota_csll_base": "0.1200",
    "regime_apuracao": "trimestral",
    "observacoes": "Cliente optante por anexo III com fator R.",
    "id_usuario_created": 42,
    "created_at": "2026-07-03T12:00:00",
    "updated_at": "2026-07-03T12:00:00"
  }
}

Erros possíveis: 404 (cliente não existe), 409 (já existe configuração para este cliente), 422 (validação de alíquota fora do intervalo 0..1).

Escopo: customer_fiscal_config:write

`GET /customer-fiscal-config/`

Lista todas as configurações fiscais do usuário autenticado, com paginação opcional. Lista vazia é um estado válido - sempre retorna 200 OK, inclusive com data: [] e a mensagem "Nenhuma configuração fiscal encontrada.".

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`page`	`int >= 1`	query	não	Página (1-based). Omitir para devolver todas as configs.
`per_page`	`int 1..500`	query	não	Itens por página (máx `500`). Exige `page` para ativar.

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Configurações fiscais recuperadas com sucesso!",
  "data": [
    {
      "id": 1,
      "id_customer": 1234,
      "aliquota_pis": "0.0065",
      "aliquota_cofins": "0.0760",
      "aliquota_iss": "0.0500",
      "aliquota_irpj_base": "0.0800",
      "aliquota_csll_base": "0.1200",
      "regime_apuracao": "trimestral",
      "observacoes": "Cliente optante por anexo III com fator R.",
      "id_usuario_created": 42,
      "created_at": "2026-07-03T12:00:00",
      "updated_at": "2026-07-03T12:00:00"
    }
  ]
}

Escopo: customer_fiscal_config:read

`GET /customer-fiscal-config/by-customer/{customer_id}`

Busca a configuração fiscal pelo ID do cliente (FK 1:1). É o caso de uso primário do front: dado um cliente, devolve sua config. Quando não há config para o cliente, retorna 404 Not Found.

Parâmetros

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

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Configuração fiscal encontrada!",
  "data": {
    "id": 1,
    "id_customer": 1234,
    "aliquota_pis": "0.0065",
    "aliquota_cofins": "0.0760",
    "aliquota_iss": "0.0500",
    "aliquota_irpj_base": "0.0800",
    "aliquota_csll_base": "0.1200",
    "regime_apuracao": "trimestral",
    "observacoes": "Cliente optante por anexo III com fator R.",
    "id_usuario_created": 42,
    "created_at": "2026-07-03T12:00:00",
    "updated_at": "2026-07-03T12:00:00"
  }
}

Escopo: customer_fiscal_config:read

`GET /customer-fiscal-config/{config_id}`

Detalha uma configuração fiscal pelo ID da própria config. Quando não encontrada (ou pertencente a outro usuário), retorna 404 Not Found.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`config_id`	`int`	path	sim	ID interno da configuração fiscal

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Configuração fiscal encontrada!",
  "data": {
    "id": 1,
    "id_customer": 1234,
    "aliquota_pis": "0.0065",
    "aliquota_cofins": "0.0760",
    "aliquota_iss": "0.0500",
    "aliquota_irpj_base": "0.0800",
    "aliquota_csll_base": "0.1200",
    "regime_apuracao": "trimestral",
    "observacoes": "Cliente optante por anexo III com fator R.",
    "id_usuario_created": 42,
    "created_at": "2026-07-03T12:00:00",
    "updated_at": "2026-07-03T12:00:00"
  }
}

Escopo: customer_fiscal_config:read

`PUT /customer-fiscal-config/{config_id}`

Atualiza uma configuração existente. O body é um CustomerFiscalConfigUpdate com campos parciais - somente o que vier preenchido é alterado. id_customer, id, id_usuario_created, created_at e updated_at são imutáveis e não podem ser enviados (proteção contra mass-assignment).

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`config_id`	`int`	path	sim	ID da configuração fiscal

Request (CustomerFiscalConfigUpdate - todos os campos opcionais)

{
  "aliquota_iss": "0.0300",
  "regime_apuracao": "anual",
  "observacoes": "Regime alterado para apuração anual."
}

Response 200 OK

{
  "success": true,
  "message": "Configuração fiscal atualizada!",
  "data": {
    "id": 1,
    "id_customer": 1234,
    "aliquota_pis": "0.0065",
    "aliquota_cofins": "0.0760",
    "aliquota_iss": "0.0300",
    "aliquota_irpj_base": "0.0800",
    "aliquota_csll_base": "0.1200",
    "regime_apuracao": "anual",
    "observacoes": "Regime alterado para apuração anual.",
    "id_usuario_created": 42,
    "created_at": "2026-07-03T12:00:00",
    "updated_at": "2026-07-03T14:20:00"
  }
}

Escopo: customer_fiscal_config:write

`DELETE /customer-fiscal-config/{config_id}`

Remove uma configuração fiscal do usuário autenticado pelo ID.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`config_id`	`int`	path	sim	ID da configuração fiscal

Request

Sem corpo de requisição.

Response 200 OK

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

Escopo: customer_fiscal_config:write

Schemas

`CustomerFiscalConfigCreate`

Alíquotas em fração decimal entre 0 e 1 (ex.: 0.0065 = 0,65%). Valores fora desse intervalo resultam em 422.

Campo	Tipo	Obrigatório	Observações
`id_customer`	`int`	sim	ID do cliente (`customer.id`). Define a relação 1:1 e é imutável depois.
`aliquota_pis`	`Decimal`	não	Alíquota de PIS. Default `0`. Ex.: `0.0065` = 0,65%.
`aliquota_cofins`	`Decimal`	não	Alíquota de COFINS. Default `0`. Ex.: `0.0760` = 7,60%.
`aliquota_iss`	`Decimal`	não	Alíquota de ISS. Default `0`. Ex.: `0.0500` = 5,00%.
`aliquota_irpj_base`	`Decimal`	não	Percentual de presunção do IRPJ. Default `0`. Ex.: `0.0800` = 8%.
`aliquota_csll_base`	`Decimal`	não	Percentual de presunção da CSLL. Default `0`. Ex.: `0.1200` = 12%.
`regime_apuracao`	`str`	não	Regime de apuração do IRPJ/CSLL (ex.: `trimestral`, `anual`). Máx 50.
`observacoes`	`str`	não	Observações livres. Máx 500 caracteres.

`CustomerFiscalConfigUpdate`

Todos os campos são opcionais; apenas os enviados são atualizados. id_customer não aparece aqui (imutável).

Campo	Tipo	Observações
`aliquota_pis`	`Decimal`	Nova alíquota de PIS (fração decimal).
`aliquota_cofins`	`Decimal`	Nova alíquota de COFINS (fração decimal).
`aliquota_iss`	`Decimal`	Nova alíquota de ISS (fração decimal).
`aliquota_irpj_base`	`Decimal`	Novo percentual de presunção do IRPJ (fração decimal).
`aliquota_csll_base`	`Decimal`	Novo percentual de presunção da CSLL (fração decimal).
`regime_apuracao`	`str`	Novo regime de apuração. Máx 50.
`observacoes`	`str`	Novas observações. Máx 500 caracteres.

`CustomerFiscalConfigRead`

Estende os campos base com os campos gerenciados pelo servidor.

Campo	Tipo	Notas
`id`	`int`	Identificador da configuração fiscal.
`id_customer`	`int`	Cliente vinculado (`customer.id`).
`aliquota_pis`	`Decimal`	Alíquota de PIS (fração decimal).
`aliquota_cofins`	`Decimal`	Alíquota de COFINS (fração decimal).
`aliquota_iss`	`Decimal`	Alíquota de ISS (fração decimal).
`aliquota_irpj_base`	`Decimal`	Presunção do IRPJ (fração decimal).
`aliquota_csll_base`	`Decimal`	Presunção da CSLL (fração decimal).
`regime_apuracao`	`str`	Regime de apuração do IRPJ/CSLL.
`observacoes`	`str`	Observações livres.
`id_usuario_created`	`int`	Usuário que criou a config (multi-tenant).
`created_at`	`datetime`	Timestamp de criação (server-side).
`updated_at`	`datetime`	Timestamp da última atualização (server-side).

Notas

Toda resposta segue o envelope { success, message, data } (ou { success: false, message, details } em erro).
As alíquotas são sempre representadas em fração decimal entre 0 e 1: 0.0065 = 0,65%, 0.05 = 5%. O banco usa Numeric(5,4) (4 casas decimais); valores fora do intervalo 0..1 retornam 422 Unprocessable Entity.
GET /by-customer/{customer_id} é declarado antes da rota dinâmica GET /{config_id}, então o FastAPI resolve by-customer como rota estática (e não interpreta by-customer como um config_id).
A relação com customer é 1:1: tentar criar uma segunda config para o mesmo cliente retorna 409 Conflict.
Relaciona-se com Customers - o cliente cuja tributação esta configuração parametriza.