SN Analytics: Cálculos

Endpoints da WebApiAlcance para os cálculos do Simples Nacional (módulo SN Analytics). Armazenam e consultam, por empresa e competência (mês/ano), os dados apurados do regime: RBT12, fator R, anexo aplicado, faixa, alíquota nominal, parcela a deduzir, alíquota efetiva, receita do mês e o valor do DAS - além dos tributos que compõem o DAS (IRPJ, CSLL, PIS, COFINS, CPP, ISS, ICMS). Cobrem a listagem dos cálculos (com os tributos aninhados) e o upsert em lote de cálculos e de tributos.

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

Escopos necessários

sn_calculos:read - listagem de cálculos
sn_calculos:write - upsert de cálculos e de tributos em lote

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

Endpoints

`GET /sn-calculos/`

Lista os cálculos do Simples Nacional, com os tributos aninhados em cada cálculo (data[].tributos). Aceita filtro opcional por empresa. Lista vazia é um estado válido (ex.: empresa recém-cadastrada) - 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 empresa separados por vírgula (CSV). Ex.: `1,2,3`. Valores não inteiros retornam `422`.

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Cálculos recuperados com sucesso",
  "data": [
    {
      "id": 501,
      "empresa_id": 1,
      "mes": 6,
      "ano": 2026,
      "rbt12": 1800000.0,
      "fator_r": 0.285000,
      "anexo_aplicado": "III",
      "faixa": 4,
      "aliquota_nominal": 0.210000,
      "parcela_deduzir": 125640.0,
      "aliquota_efetiva": 0.140200,
      "receita_mes": 150000.0,
      "valor_das": 21030.0,
      "valor_cpp_separado": null,
      "ultrapassou_sublimite": false,
      "ultrapassou_limite": false,
      "tributos": {
        "id": 501,
        "calculo_id": 501,
        "irpj": 1051.5,
        "csll": 946.35,
        "pis": 546.78,
        "cofins": 2523.6,
        "cpp": 9042.9,
        "iss": 6918.87,
        "icms": 0.0,
        "created_at": "2026-07-01T09:00:00",
        "updated_at": "2026-07-01T09:00:00"
      },
      "created_at": "2026-07-01T09:00:00",
      "updated_at": "2026-07-01T09:00:00"
    }
  ]
}

Valores de empresa_ids não inteiros resultam em 422 Unprocessable Entity com detail: "empresa_ids deve ser uma lista de inteiros separados por vírgula.".

Escopo: sn_calculos:read

`PUT /sn-calculos/batch`

Faz o upsert em lote de cálculos do Simples Nacional. Cada item é identificado pela chave natural (empresa_id, mes, ano): se já existir cálculo para a competência, é atualizado; caso contrário, é criado. Aceita até 5000 itens por chamada.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query - o corpo é um array de SnCalculoUpsert (no máximo 5000 itens).

Request

[
  {
    "empresa_id": 1,
    "mes": 6,
    "ano": 2026,
    "rbt12": 1800000.0,
    "fator_r": 0.285000,
    "anexo_aplicado": "III",
    "faixa": 4,
    "aliquota_nominal": 0.210000,
    "parcela_deduzir": 125640.0,
    "aliquota_efetiva": 0.140200,
    "receita_mes": 150000.0,
    "valor_das": 21030.0,
    "valor_cpp_separado": null,
    "ultrapassou_sublimite": false,
    "ultrapassou_limite": false
  }
]

Response 200 OK

Envelope com data = array de SnCalculoRead (os cálculos persistidos). Erros de validação de regra de negócio retornam 422 Unprocessable Entity.

{
  "success": true,
  "message": "Cálculos atualizados com sucesso",
  "data": [
    {
      "id": 501,
      "empresa_id": 1,
      "mes": 6,
      "ano": 2026,
      "anexo_aplicado": "III",
      "faixa": 4,
      "aliquota_efetiva": 0.140200,
      "valor_das": 21030.0,
      "created_at": "2026-07-01T09:00:00",
      "updated_at": "2026-07-03T10:15:00"
    }
  ]
}

Escopo: sn_calculos:write

`PUT /sn-calculos/tributos/batch`

Faz o upsert em lote dos tributos que compõem o DAS. Cada item é identificado por calculo_id (o cálculo ao qual os tributos pertencem). Aceita até 5000 itens por chamada.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query - o corpo é um array de SnTributosUpsert (no máximo 5000 itens).

Request

[
  {
    "calculo_id": 501,
    "irpj": 1051.5,
    "csll": 946.35,
    "pis": 546.78,
    "cofins": 2523.6,
    "cpp": 9042.9,
    "iss": 6918.87,
    "icms": 0.0
  }
]

Response 200 OK

Envelope com data = array de SnTributosRead. Um calculo_id inexistente retorna 422 Unprocessable Entity.

{
  "success": true,
  "message": "Tributos atualizados com sucesso",
  "data": [
    {
      "id": 501,
      "calculo_id": 501,
      "irpj": 1051.5,
      "csll": 946.35,
      "pis": 546.78,
      "cofins": 2523.6,
      "cpp": 9042.9,
      "iss": 6918.87,
      "icms": 0.0,
      "created_at": "2026-07-01T09:00:00",
      "updated_at": "2026-07-03T10:15:00"
    }
  ]
}

Escopo: sn_calculos:write

Schemas

`SnCalculoUpsert`

Item do PUT /sn-calculos/batch. Estende SnCalculoBase com empresa_id. Os decimais são serializados como número JSON (não string).

Campo	Tipo	Obrigatório	Observações
`empresa_id`	`int`	sim	ID da empresa (mapeado de `id_cliente` no banco).
`mes`	`int`	sim	Mês da competência (`1`-`12`).
`ano`	`int`	sim	Ano da competência (`2000`-`2100`).
`anexo_aplicado`	`str`	sim	Anexo do Simples: `I`, `II`, `III`, `IV` ou `V`.
`rbt12`	`number`	não	Receita bruta dos últimos 12 meses. Default `null`.
`fator_r`	`number`	não	Fator R (folha ÷ receita). Default `null`.
`faixa`	`int`	não	Faixa da tabela do anexo (`>= 1`). Default `1`.
`aliquota_nominal`	`number`	não	Alíquota nominal da faixa. Default `null`.
`parcela_deduzir`	`number`	não	Parcela a deduzir da faixa. Default `null`.
`aliquota_efetiva`	`number`	não	Alíquota efetiva apurada. Default `null`.
`receita_mes`	`number`	não	Receita do mês. Default `null`.
`valor_das`	`number`	não	Valor do DAS apurado. Default `null`.
`valor_cpp_separado`	`number`	não	CPP recolhida em separado (Anexo IV). Default `null`.
`ultrapassou_sublimite`	`bool`	não	Ultrapassou o sublimite estadual. Default `false`.
`ultrapassou_limite`	`bool`	não	Ultrapassou o limite do Simples. Default `false`.

`SnCalculoRead`

Retorno das rotas de cálculo. Estende SnCalculoBase com os campos abaixo.

Campo	Tipo	Notas
`id`	`int`	Identificador do cálculo.
`empresa_id`	`int`	ID da empresa (exposto de `id_cliente`).
`tributos`	`SnTributosRead`	Tributos aninhados do cálculo (ou `null` quando ainda não há tributos).
`created_at`	`datetime`	Data de criação (exposta de `data_hora_criacao`).
`updated_at`	`datetime`	Data de atualização (exposta de `data_hora_atualizacao`).

Os demais campos (mes, ano, rbt12, fator_r, anexo_aplicado, faixa, aliquota_nominal, parcela_deduzir, aliquota_efetiva, receita_mes, valor_das, valor_cpp_separado, ultrapassou_sublimite, ultrapassou_limite) vêm de SnCalculoBase - mesma semântica do SnCalculoUpsert.

`SnTributosUpsert`

Item do PUT /sn-calculos/tributos/batch. Estende SnTributosBase com calculo_id. Todos os valores de tributo são decimais (número JSON) com default 0.

Campo	Tipo	Obrigatório	Observações
`calculo_id`	`int`	sim	ID do cálculo ao qual os tributos pertencem.
`irpj`	`number`	não	Parcela de IRPJ do DAS. Default `0`.
`csll`	`number`	não	Parcela de CSLL. Default `0`.
`pis`	`number`	não	Parcela de PIS. Default `0`.
`cofins`	`number`	não	Parcela de COFINS. Default `0`.
`cpp`	`number`	não	Parcela de CPP. Default `0`.
`iss`	`number`	não	Parcela de ISS. Default `0`.
`icms`	`number`	não	Parcela de ICMS. Default `0`.

`SnTributosRead`

Retorno das rotas de tributos e do bloco tributos aninhado em SnCalculoRead. Estende SnTributosBase.

Campo	Tipo	Notas
`id`	`int`	Identificador do registro de tributos.
`calculo_id`	`int`	Cálculo ao qual os tributos pertencem.
`irpj`	`number`	Parcela de IRPJ.
`csll`	`number`	Parcela de CSLL.
`pis`	`number`	Parcela de PIS.
`cofins`	`number`	Parcela de COFINS.
`cpp`	`number`	Parcela de CPP.
`iss`	`number`	Parcela de ISS.
`icms`	`number`	Parcela de ICMS.
`created_at`	`datetime`	Data de criação (exposta de `data_hora_criacao`).
`updated_at`	`datetime`	Data de atualização (exposta de `data_hora_atualizacao`).

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.
Decimais são número JSON, não string. Internamente são Decimal (precisão preservada) e só convertem para float na serialização JSON.
Mapeamento de nomes: o banco usa id_cliente, data_hora_criacao e data_hora_atualizacao; o JSON expõe empresa_id, created_at e updated_at. O campo interno legacy_uuid não é exposto no JSON.
Upserts idempotentes por chave natural: PUT /sn-calculos/batch deduplica por (empresa_id, mes, ano) e PUT /sn-calculos/tributos/batch por calculo_id. Ambos aceitam no máximo 5000 itens por chamada.
Ordem das rotas: as literais (/batch, /tributos/batch) são declaradas antes de qualquer rota dinâmica, por convenção do contrato SN Analytics.