Lançamento Fiscal

Endpoints da WebApiAlcance para gerenciar lançamentos fiscais - registros manuais de débitos e créditos de tributos por competência (mês de apuração), vinculados a um cliente. Cada lançamento tem um tributo (PIS, COFINS, ISS, IRPJ, CSLL, INSS, OUTROS), um tipo (debito ou credito) e um valor sempre positivo (o sinal contábil vem do tipo). Cobrem criação, listagem dos lançamentos do usuário autenticado, listagem por cliente com filtros, 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/lancamento-fiscal

Escopos necessários

lancamento_fiscal:read - listagem do usuário, listagem por cliente e detalhamento
lancamento_fiscal:write - criação, atualização e exclusão

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

Endpoints

`POST /lancamento-fiscal/`

Cria um novo lançamento fiscal manual vinculado a 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 (LancamentoFiscalCreate). Campos obrigatórios: id_customer, mes_apuracao, tributo, tipo e valor. Campos opcionais: descricao, data_lancamento e categoria.

Request

{
  "id_customer": 1,
  "mes_apuracao": "2026-05",
  "tributo": "PIS",
  "tipo": "debito",
  "valor": "1234.56",
  "descricao": "Ajuste manual de PIS de competências anteriores.",
  "data_lancamento": "2026-05-31",
  "categoria": "receita-financeira"
}

Response 201 Created

{
  "success": true,
  "message": "Lançamento fiscal criado com sucesso!",
  "data": {
    "id": 1,
    "id_customer": 1,
    "mes_apuracao": "2026-05",
    "tributo": "PIS",
    "tipo": "debito",
    "valor": "1234.56",
    "descricao": "Ajuste manual de PIS de competências anteriores.",
    "categoria": "receita-financeira",
    "data_lancamento": "2026-05-31",
    "id_usuario_created": 42,
    "created_at": "2026-05-31T12:00:00",
    "updated_at": "2026-05-31T12:00:00"
  }
}

Cliente inexistente retorna 404 Not Found; falhas de validação (tributo/tipo fora do enum, valor não positivo, mes_apuracao fora do formato YYYY-MM) retornam 422 Unprocessable Entity.

Escopo: lancamento_fiscal:write

`GET /lancamento-fiscal/by-user`

Lista todos os lançamentos fiscais do usuário autenticado, com filtro e paginação opcionais. Lista vazia é um estado válido - sempre retorna 200 OK, inclusive com data: [] e a mensagem "Nenhum lançamento fiscal encontrado.".

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`mes_apuracao`	`str`	query	não	Filtro por mês de apuração (`YYYY-MM`). Ex.: `2026-05`.
`page`	`int`	query	não	Página 1-based (`>= 1`).
`per_page`	`int`	query	não	Itens por página (`1..500`).

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Lançamentos fiscais recuperados com sucesso!",
  "data": [
    {
      "id": 1,
      "id_customer": 1,
      "mes_apuracao": "2026-05",
      "tributo": "PIS",
      "tipo": "debito",
      "valor": "1234.56",
      "descricao": "Ajuste manual de PIS de competências anteriores.",
      "categoria": "receita-financeira",
      "data_lancamento": "2026-05-31",
      "id_usuario_created": 42,
      "created_at": "2026-05-31T12:00:00",
      "updated_at": "2026-05-31T12:00:00"
    }
  ]
}

Escopo: lancamento_fiscal:read

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

Lista os lançamentos fiscais de um cliente, opcionalmente filtrados por competência e/ou tributo. É o caso de uso primário do front. Quando o cliente não é encontrado, retorna 404 Not Found.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`customer_id`	`int`	path	sim	ID do cliente.
`mes_apuracao`	`str`	query	não	Filtro por mês de apuração (`YYYY-MM`). Ex.: `2026-05`.
`tributo`	`str`	query	não	Filtro por tributo: `PIS`, `COFINS`, `ISS`, `IRPJ`, `CSLL`, `INSS`, `OUTROS`.
`page`	`int`	query	não	Página 1-based (`>= 1`).
`per_page`	`int`	query	não	Itens por página (`1..500`).

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Lançamentos fiscais recuperados com sucesso!",
  "data": [
    {
      "id": 1,
      "id_customer": 1,
      "mes_apuracao": "2026-05",
      "tributo": "PIS",
      "tipo": "debito",
      "valor": "1234.56",
      "descricao": "Ajuste manual de PIS de competências anteriores.",
      "categoria": "receita-financeira",
      "data_lancamento": "2026-05-31",
      "id_usuario_created": 42,
      "created_at": "2026-05-31T12:00:00",
      "updated_at": "2026-05-31T12:00:00"
    }
  ]
}

Escopo: lancamento_fiscal:read

`GET /lancamento-fiscal/{lancamento_id}`

Detalha um lançamento fiscal do usuário autenticado pelo ID inteiro. Quando não encontrado, retorna 404 Not Found.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`lancamento_id`	`int`	path	sim	ID interno do lançamento.

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Lançamento fiscal encontrado!",
  "data": {
    "id": 1,
    "id_customer": 1,
    "mes_apuracao": "2026-05",
    "tributo": "PIS",
    "tipo": "debito",
    "valor": "1234.56",
    "descricao": "Ajuste manual de PIS de competências anteriores.",
    "categoria": "receita-financeira",
    "data_lancamento": "2026-05-31",
    "id_usuario_created": 42,
    "created_at": "2026-05-31T12:00:00",
    "updated_at": "2026-05-31T12:00:00"
  }
}

Escopo: lancamento_fiscal:read

`PUT /lancamento-fiscal/{lancamento_id}`

Atualiza um lançamento fiscal existente. O body é um LancamentoFiscalUpdate com campos parciais - somente o que vier preenchido é alterado (exclude_unset). Os campos id, id_customer, id_usuario_created, created_at e updated_at são imutáveis e não aparecem no schema (proteção contra mass-assignment).

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`lancamento_id`	`int`	path	sim	ID do lançamento.

Request (LancamentoFiscalUpdate - todos os campos opcionais)

{
  "valor": "1500.00",
  "descricao": "Valor revisado após conferência."
}

Response 200 OK

{
  "success": true,
  "message": "Lançamento fiscal atualizado!",
  "data": {
    "id": 1,
    "id_customer": 1,
    "mes_apuracao": "2026-05",
    "tributo": "PIS",
    "tipo": "debito",
    "valor": "1500.00",
    "descricao": "Valor revisado após conferência.",
    "categoria": "receita-financeira",
    "data_lancamento": "2026-05-31",
    "id_usuario_created": 42,
    "created_at": "2026-05-31T12:00:00",
    "updated_at": "2026-05-31T14:20:00"
  }
}

Quando não encontrado, retorna 404 Not Found.

Escopo: lancamento_fiscal:write

`DELETE /lancamento-fiscal/{lancamento_id}`

Remove um lançamento fiscal pelo ID. Quando não encontrado, retorna 404 Not Found.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`lancamento_id`	`int`	path	sim	ID do lançamento.

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Lançamento fiscal removido!",
  "data": null
}

Escopo: lancamento_fiscal:write

Schemas

`LancamentoFiscalCreate`

Herda todos os campos de LancamentoFiscalBase. id_customer é obrigatório.

Campo	Tipo	Obrigatório	Observações
`id_customer`	`int`	sim	ID do cliente (`customer.id`) ao qual o lançamento pertence.
`mes_apuracao`	`str`	sim	Mês de apuração no formato `YYYY-MM` (7 caracteres, mês `01`-`12`).
`tributo`	`str` (enum)	sim	Um de: `PIS`, `COFINS`, `ISS`, `IRPJ`, `CSLL`, `INSS`, `OUTROS`.
`tipo`	`str` (enum)	sim	`debito` (aumenta tributo a pagar) ou `credito` (reduz / gera crédito).
`valor`	`Decimal`	sim	Sempre estritamente positivo e `< 10.000.000.000.000`; 2 casas decimais (`Numeric(15,2)`). O sinal vem do `tipo`.
`descricao`	`str`	não	Descrição livre, até 500 caracteres.
`data_lancamento`	`date`	não	Data do lançamento. Default `CURRENT_DATE` no banco.
`categoria`	`str` (enum)	não	Subdivisão semântica: `receita-financeira`, `receita-nao-operacional`, `irrf-aplicacoes`, `outros`. `None` é tratado como `outros` pelo frontend.

`LancamentoFiscalUpdate`

Todos os campos são opcionais; apenas os enviados são atualizados. Campos imutáveis (id, id_customer, id_usuario_created, created_at, updated_at) não aparecem aqui para bloquear mass-assignment.

Campo	Tipo	Observações
`mes_apuracao`	`str`	Novo mês de apuração (`YYYY-MM`).
`tributo`	`str` (enum)	Novo tributo (`PIS`, `COFINS`, `ISS`, `IRPJ`, `CSLL`, `INSS`, `OUTROS`).
`tipo`	`str` (enum)	Novo tipo (`debito` / `credito`).
`valor`	`Decimal`	Novo valor, sempre positivo e dentro do limite.
`descricao`	`str`	Nova descrição (até 500 caracteres).
`data_lancamento`	`date`	Nova data do lançamento.
`categoria`	`str` (enum)	Nova categoria semântica. Update não enviado = "não tocar" (`exclude_unset`).

`LancamentoFiscalRead`

Estende LancamentoFiscalBase com os campos gerenciados (id, owner, timestamps).

Campo	Tipo	Notas
`id`	`int`	ID do lançamento fiscal.
`id_customer`	`int`	Cliente ao qual o lançamento pertence.
`mes_apuracao`	`str`	Competência no formato `YYYY-MM`.
`tributo`	`str`	Tributo lançado.
`tipo`	`str`	`debito` ou `credito`.
`valor`	`Decimal`	Valor positivo (o sinal vem do `tipo`).
`descricao`	`str`	Descrição livre (pode ser `null`).
`categoria`	`str`	Categoria semântica (pode ser `null`).
`data_lancamento`	`date`	Preenchida server-side quando ausente no Create.
`id_usuario_created`	`int`	Usuário que criou o lançamento (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). Códigos HTTP refletem semântica REST padrão.
Armadilha de roteamento FastAPI. As rotas estáticas GET /by-user e GET /by-customer/{customer_id} são declaradas antes da rota dinâmica GET /{lancamento_id}. Isso é intencional: inverter a ordem faria o router casar by-user/by-customer como se fossem um lancamento_id, quebrando os endpoints estáticos.
valor é sempre positivo: o sinal contábil é expresso pelo campo tipo (debito aumenta o tributo a pagar; credito reduz ou gera crédito a recuperar).
mes_apuracao usa o formato YYYY-MM (mesmo padrão do front-end), com validação de mês 01-12 e ano de 4 dígitos.
As listagens (GET /by-user e GET /by-customer/{customer_id}) aceitam paginação opcional via page e per_page (máx. 500); quando não há resultados, retornam data: [] com 200 OK.