SN Analytics: Faturamento Anual

Endpoints da WebApiAlcance para registrar e consultar o faturamento anual dos clientes no Simples Nacional - a base do cálculo da RBT12 (Receita Bruta dos últimos 12 meses). Cada registro representa o faturamento de uma competência (MM/YYYY) de uma empresa, com os valores total, retido no Simples e retido fora do Simples. Cobrem listagem filtrável por empresa, cálculo do faturamento efetivo da competência (com prioridade para a prefeitura), upsert em lote, criação, 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/sn-faturamento-anual

Escopos necessários

sn_faturamento_anual:read - listagem e faturamento efetivo
sn_faturamento_anual:write - upsert em lote, criação, atualização e exclusão

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

Endpoints

`GET /sn-faturamento-anual/`

Lista os registros de faturamento anual. O filtro por empresa é opcional - sem ele, retorna todos os registros; com ele, apenas os da empresa informada. Lista vazia é um estado válido e retorna 200 OK com data: [].

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`empresa_id`	`int`	query	não	Filtra por empresa (`customer.id`).

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Faturamento anual recuperado com sucesso",
  "data": [
    {
      "id": 42,
      "empresa_id": 1234,
      "ano": 2026,
      "mes": 6,
      "competencia": "06/2026",
      "faturamento_total": 18500.00,
      "faturamento_retido_s": 0.0,
      "faturamento_retido_n": 1200.00,
      "observacao": null,
      "origem": "nacional",
      "created_at": "2026-07-01T10:15:00",
      "updated_at": "2026-07-01T10:15:00"
    }
  ]
}

Escopo: sn_faturamento_anual:read

`GET /sn-faturamento-anual/efetivo`

Retorna o faturamento efetivo de uma competência, aplicando prioridade de fonte: primeiro o valor apurado na prefeitura; na ausência, faz fallback para o faturamento anual cadastrado. Quando não há dado algum para a competência, fonte vem null e os totais zerados.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`empresa_id`	`int`	query	sim	Empresa (`customer.id`).
`competencia`	`str`	query	sim	Competência no formato `MM/YYYY`.

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Faturamento efetivo recuperado com sucesso",
  "data": {
    "fonte": "prefeitura",
    "total": 18500.00,
    "retido_s": 0.0,
    "retido_n": 1200.00
  }
}

Escopo: sn_faturamento_anual:read

`PUT /sn-faturamento-anual/batch`

Faz o upsert em lote de registros de faturamento anual. Cada item é criado ou atualizado conforme já exista o par empresa + competência.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query - o corpo é um array JSON de SnFaturamentoAnualCreate (limite de 5000 itens).

Request

[
  { "empresa_id": 1234, "competencia": "05/2026", "faturamento_total": 17000.00 },
  { "empresa_id": 1234, "competencia": "06/2026", "faturamento_total": 18500.00, "faturamento_retido_n": 1200.00 }
]

Response 200 OK

{
  "success": true,
  "message": "Batch processado com sucesso",
  "data": {
    "criados": 1,
    "atualizados": 1
  }
}

Escopo: sn_faturamento_anual:write

`POST /sn-faturamento-anual/`

Cria um novo registro de faturamento anual para uma empresa e competência.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query - os dados vão no corpo da requisição (SnFaturamentoAnualCreate). Campos obrigatórios: empresa_id e competencia; mes/ano são derivados de competencia quando omitidos.

Request

{
  "empresa_id": 1234,
  "competencia": "06/2026",
  "faturamento_total": 18500.00,
  "faturamento_retido_n": 1200.00,
  "origem": "nacional"
}

Response 201 Created

{
  "success": true,
  "message": "Faturamento criado com sucesso",
  "data": {
    "id": 42,
    "empresa_id": 1234,
    "ano": 2026,
    "mes": 6,
    "competencia": "06/2026",
    "faturamento_total": 18500.00,
    "faturamento_retido_s": 0.0,
    "faturamento_retido_n": 1200.00,
    "observacao": null,
    "origem": "nacional",
    "created_at": "2026-07-01T10:15:00",
    "updated_at": "2026-07-01T10:15:00"
  }
}

Escopo: sn_faturamento_anual:write

`PUT /sn-faturamento-anual/{faturamento_id}`

Atualiza um registro existente. O body é um SnFaturamentoAnualUpdate com campos parciais - somente o que vier preenchido é alterado. O campo empresa_id não é atualizável (mass-assignment bloqueado). Se competencia mudar e mes/ano não forem enviados, eles são re-derivados.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`faturamento_id`	`int`	path	sim	ID interno do registro

Request (SnFaturamentoAnualUpdate - todos os campos opcionais)

{
  "faturamento_total": 19000.00,
  "observacao": "Retificação da competência"
}

Response 200 OK

{
  "success": true,
  "message": "Faturamento atualizado com sucesso",
  "data": {
    "id": 42,
    "empresa_id": 1234,
    "ano": 2026,
    "mes": 6,
    "competencia": "06/2026",
    "faturamento_total": 19000.00,
    "faturamento_retido_s": 0.0,
    "faturamento_retido_n": 1200.00,
    "observacao": "Retificação da competência",
    "origem": "nacional",
    "created_at": "2026-07-01T10:15:00",
    "updated_at": "2026-07-01T11:42:00"
  }
}

Escopo: sn_faturamento_anual:write

`DELETE /sn-faturamento-anual/{faturamento_id}`

Remove um registro de faturamento anual pelo ID.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`faturamento_id`	`int`	path	sim	ID interno do registro

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Faturamento removido com sucesso",
  "data": null
}

Escopo: sn_faturamento_anual:write

Schemas

`SnFaturamentoAnualCreate`

Campo	Tipo	Obrigatório	Observações
`empresa_id`	`int`	sim	Empresa (`customer.id`).
`competencia`	`str`	sim	Formato `MM/YYYY` (mês `01`-`12`).
`mes`	`int`	não	`1`-`12`. Derivado de `competencia` quando omitido.
`ano`	`int`	não	`1900`-`9999`. Derivado de `competencia` quando omitido.
`faturamento_total`	`Decimal`	não	Máx. 15 dígitos, 2 casas. Default `0`.
`faturamento_retido_s`	`Decimal`	não	Faturamento retido no Simples. Default `0`.
`faturamento_retido_n`	`Decimal`	não	Faturamento retido fora do Simples. Default `0`.
`observacao`	`str`	não	Texto livre (máx. 10000 caracteres).
`origem`	`str`	não	`nacional` ou `exterior`. Default `nacional`.

`SnFaturamentoAnualUpdate`

Update parcial - todos os campos são opcionais; apenas os enviados são atualizados. empresa_id não é aceito.

Campo	Tipo	Observações
`competencia`	`str`	Formato `MM/YYYY`. Se mudar, re-deriva `mes`/`ano` quando ausentes.
`mes`	`int`	`1`-`12`.
`ano`	`int`	`1900`-`9999`.
`faturamento_total`	`Decimal`	Máx. 15 dígitos, 2 casas.
`faturamento_retido_s`	`Decimal`	Faturamento retido no Simples.
`faturamento_retido_n`	`Decimal`	Faturamento retido fora do Simples.
`observacao`	`str`	Texto livre (máx. 10000 caracteres).
`origem`	`str`	`nacional` ou `exterior`.

`SnFaturamentoAnualRead`

Campo	Tipo	Notas
`id`	`int`	Identificador do registro.
`empresa_id`	`int`	Empresa (`customer.id`).
`ano`	`int`	Ano da competência.
`mes`	`int`	Mês da competência (`1`-`12`).
`competencia`	`str`	Competência `MM/YYYY`.
`faturamento_total`	`float`	Faturamento total da competência.
`faturamento_retido_s`	`float`	Faturamento retido no Simples.
`faturamento_retido_n`	`float`	Faturamento retido fora do Simples.
`observacao`	`str`	Opcional; `null` quando não informado.
`origem`	`str`	`nacional` ou `exterior`.
`created_at`	`datetime`	Data/hora de criação.
`updated_at`	`datetime`	Data/hora da última atualização.

`SnFaturamentoEfetivoRead`

Resposta do GET /efetivo - prioridade prefeitura, fallback faturamento anual.

Campo	Tipo	Notas
`fonte`	`str`	`prefeitura` ou `faturamento_anual`; `null` quando não há dado na competência.
`total`	`float`	Faturamento total efetivo. Default `0`.
`retido_s`	`float`	Retido no Simples. Default `0`.
`retido_n`	`float`	Retido fora do Simples. Default `0`.

Notas

Toda resposta segue o envelope { success, message, data } (ou { success: false, message, details } em erro).
Ordem de rotas (FastAPI). As rotas estáticas GET /efetivo e PUT /batch são declaradas antes da rota dinâmica PUT /{faturamento_id}, para que efetivo e batch não sejam interpretados como um faturamento_id.
O JSON de saída expõe sempre empresa_id, created_at e updated_at, mesmo que internamente a persistência use os campos id_cliente, data_hora_criacao e data_hora_atualizacao.
Os valores faturamento_* são aceitos como Decimal (15 dígitos, 2 casas) na escrita e devolvidos como float na leitura.
Erros de validação de negócio são mapeados para HTTP: "não encontrado" → 404, "já existe"/"duplicado" → 409, demais → 422.