SN Analytics: Receitas

Endpoints da WebApiAlcance para as receitas do Simples Nacional (SN Analytics), registradas por competência - a combinação empresa / mês / ano. Cada registro guarda a receita mensal segregada (total, ISS retido, ISS próprio, ICMS, monofásica, ICMS-ST, exportação e Anexo IV). Cobrem a listagem (com filtro opcional por empresas) e o upsert em lote das competências.

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-receitas

Escopos necessários

sn_receitas:read - listagem das receitas
sn_receitas:write - upsert em lote das receitas

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

Endpoints

`GET /sn-receitas/`

Lista as receitas do Simples Nacional do usuário autenticado. Aceita um filtro opcional por empresas via query param empresa_ids. Lista vazia é um estado válido - sempre retorna 200 OK, inclusive com data: [].

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`empresa_ids`	`str`	query	não	IDs de empresas separados por vírgula, ex.: `1,2,3`. Vazio/ausente = sem filtro.

Quando empresa_ids não é uma lista de inteiros separados por vírgula, a API responde 422 Unprocessable Entity com detail: "empresa_ids deve ser uma lista de inteiros separados por vírgula (ex.: 1,2,3).".

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Receitas recuperadas com sucesso",
  "data": [
    {
      "receita_total": "150000.00",
      "receita_iss_retido": "0.00",
      "receita_iss_proprio": "5000.00",
      "receita_icms": "12000.00",
      "receita_monofasica": "0.00",
      "receita_icms_st": "0.00",
      "receita_exportacao": "0.00",
      "receita_anexo_iv": "0.00",
      "id": 42,
      "empresa_id": 1,
      "mes": 6,
      "ano": 2026,
      "created_at": "2026-07-01T09:30:00",
      "updated_at": "2026-07-01T09:30:00"
    }
  ]
}

Escopo: sn_receitas:read

`PUT /sn-receitas/batch`

Faz o upsert em lote das receitas: para cada item, insere ou atualiza a competência identificada por (empresa_id, mes, ano). Retorna as competências gravadas.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query - o corpo é uma lista de SnReceitaUpsert (List[SnReceitaUpsert]), com no máximo 5000 itens.

Request

[
  {
    "empresa_id": 1,
    "mes": 6,
    "ano": 2026,
    "receita_total": "150000.00",
    "receita_iss_retido": "0.00",
    "receita_iss_proprio": "5000.00",
    "receita_icms": "12000.00",
    "receita_monofasica": "0.00",
    "receita_icms_st": "0.00",
    "receita_exportacao": "0.00",
    "receita_anexo_iv": "0.00"
  }
]

Response 200 OK

{
  "success": true,
  "message": "Receitas atualizadas com sucesso",
  "data": [
    {
      "receita_total": "150000.00",
      "receita_iss_retido": "0.00",
      "receita_iss_proprio": "5000.00",
      "receita_icms": "12000.00",
      "receita_monofasica": "0.00",
      "receita_icms_st": "0.00",
      "receita_exportacao": "0.00",
      "receita_anexo_iv": "0.00",
      "id": 42,
      "empresa_id": 1,
      "mes": 6,
      "ano": 2026,
      "created_at": "2026-07-01T09:30:00",
      "updated_at": "2026-07-03T14:10:00"
    }
  ]
}

Erros de validação de regra de negócio retornam código HTTP conforme a mensagem canônica do service: 404 Not Found (não encontrado), 409 Conflict (já existe/duplicado) ou 422 Unprocessable Entity (demais casos).

Escopo: sn_receitas:write

Schemas

`SnReceitaValores`

Base compartilhada com os valores DECIMAL(15,2) da receita mensal segregada. Todos os campos são opcionais no envio e usam default 0.

Campo	Tipo	Obrigatório	Observações
`receita_total`	`Decimal`	não	`DECIMAL(15,2)`. Default `0`.
`receita_iss_retido`	`Decimal`	não	`DECIMAL(15,2)`. Default `0`.
`receita_iss_proprio`	`Decimal`	não	`DECIMAL(15,2)`. Default `0`.
`receita_icms`	`Decimal`	não	`DECIMAL(15,2)`. Default `0`.
`receita_monofasica`	`Decimal`	não	`DECIMAL(15,2)`. Default `0`.
`receita_icms_st`	`Decimal`	não	`DECIMAL(15,2)`. Default `0`.
`receita_exportacao`	`Decimal`	não	`DECIMAL(15,2)`. Default `0`.
`receita_anexo_iv`	`Decimal`	não	`DECIMAL(15,2)`. Default `0`.

`SnReceitaUpsert`

Item do PUT /sn-receitas/batch. Estende SnReceitaValores com a chave da competência (empresa_id, mes, ano).

Campo	Tipo	Obrigatório	Observações
`empresa_id`	`int`	sim	`>= 1`. ID da empresa/cliente.
`mes`	`int`	sim	`1..12`.
`ano`	`int`	sim	`2000..2100`.
(valores)	-	-	Todos os campos de `SnReceitaValores`.

`SnReceitaRead`

Retorno de leitura. Estende SnReceitaValores com identificação e timestamps. Os campos empresa_id, created_at e updated_at do JSON mapeiam as colunas do ORM id_cliente, data_hora_criacao e data_hora_atualizacao, respectivamente.

Campo	Tipo	Observações
`id`	`int`	Identificador do registro de receita.
`empresa_id`	`int`	ID da empresa/cliente (coluna `id_cliente` no banco).
`mes`	`int`	Mês da competência (`1..12`).
`ano`	`int`	Ano da competência.
`created_at`	`datetime`	Criação (coluna `data_hora_criacao`).
`updated_at`	`datetime`	Última atualização (coluna `data_hora_atualizacao`).
(valores)	-	Todos os campos de `SnReceitaValores`.

Notas

Toda resposta segue o envelope { success, message, data } (ou { success: false, message, details } em erro).
O GET /sn-receitas/ sempre devolve uma lista dentro do envelope (data), possivelmente vazia ([]) - conforme o contrato do SN Analytics.
A rota literal PUT /sn-receitas/batch é declarada antes de eventuais rotas dinâmicas (convenção de ordenação do FastAPI), garantindo que batch seja resolvido como rota estática.
Os valores monetários são DECIMAL(15,2) e trafegam no JSON como string para preservar a precisão.
O PUT /sn-receitas/batch aceita até 5000 itens por requisição (max_length=5000).