SN Analytics: Folha

Endpoints da WebApiAlcance para a folha de pagamento no contexto do Simples Nacional - os dados de valor_folha e valor_inss por empresa/mês/ano que alimentam o cálculo do fator R (relação entre folha e receita bruta, que define o enquadramento entre os Anexos III e V do Simples Nacional). Cobrem listagem (com filtro opcional por empresas), criação, upsert em lote, atualização e exclusão de folhas mensais.

Base path

/api/v1/sn-folha

Escopos necessários

• sn_folha:read - listagem de folhas
• sn_folha:write - criação, upsert em lote, atualização e exclusão

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

Endpoints

GET /sn-folha/

Lista as folhas cadastradas, com filtro opcional por empresas. Lista vazia é um estado válido - sempre retorna 200 OK, inclusive com data: [].

Parâmetros

Quando empresa_ids contém algo que não seja 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": "Folhas recuperadas com sucesso",
  "data": [
    {
      "id": 42,
      "empresa_id": 1,
      "mes": 5,
      "ano": 2026,
      "valor_folha": "12000.00",
      "valor_inss": "3300.00",
      "valor_total": "15300.00",
      "created_at": "2026-06-01T09:00:00",
      "updated_at": "2026-06-01T09:00:00"
    }
  ]
}

Escopo: sn_folha:read

POST /sn-folha/

Cria uma nova folha para uma empresa em um dado mês/ano. Se já existir uma folha para a mesma combinação empresa + mês + ano, a API responde 409 Conflict.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query - os dados vão no corpo da requisição (SnFolhaCreate): empresa_id (obrigatório), mes (obrigatório), ano (obrigatório), valor_folha (opcional, default 0) e valor_inss (opcional, default 0).

Request

{
  "empresa_id": 1,
  "mes": 5,
  "ano": 2026,
  "valor_folha": "12000.00",
  "valor_inss": "3300.00"
}

Response 201 Created

{
  "success": true,
  "message": "Folha criada com sucesso",
  "data": {
    "id": 42,
    "empresa_id": 1,
    "mes": 5,
    "ano": 2026,
    "valor_folha": "12000.00",
    "valor_inss": "3300.00",
    "valor_total": "15300.00",
    "created_at": "2026-06-01T09:00:00",
    "updated_at": "2026-06-01T09:00:00"
  }
}

Escopo: sn_folha:write

PUT /sn-folha/batch

Faz upsert em lote de folhas, cada item identificado pela combinação empresa/mês/ano - cria as que não existem e atualiza as existentes. O corpo é um array de SnFolhaCreate, com no máximo 5000 itens.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query - o corpo da requisição é um array de objetos SnFolhaCreate (List[SnFolhaCreate]).

Request

[
  { "empresa_id": 1, "mes": 5, "ano": 2026, "valor_folha": "12000.00", "valor_inss": "3300.00" },
  { "empresa_id": 2, "mes": 5, "ano": 2026, "valor_folha": "8000.00", "valor_inss": "2200.00" }
]

Response 200 OK

{
  "success": true,
  "message": "Folhas atualizadas com sucesso",
  "data": [
    {
      "id": 42,
      "empresa_id": 1,
      "mes": 5,
      "ano": 2026,
      "valor_folha": "12000.00",
      "valor_inss": "3300.00",
      "valor_total": "15300.00",
      "created_at": "2026-06-01T09:00:00",
      "updated_at": "2026-06-01T09:05:00"
    }
  ]
}

Escopo: sn_folha:write

PUT /sn-folha/{folha_id}

Atualiza uma folha existente. O body é um SnFolhaUpdate com campos parciais - somente o que vier preenchido é alterado. O empresa_id é imutável e não pode ser alterado por este endpoint. Quando não encontrada, retorna 404 Not Found.

Parâmetros

O corpo da requisição é um SnFolhaUpdate com os campos mes, ano, valor_folha e/ou valor_inss - todos opcionais.

Request

{
  "mes": 6,
  "valor_folha": "12500.00"
}

Response 200 OK

{
  "success": true,
  "message": "Folha atualizada com sucesso",
  "data": {
    "id": 42,
    "empresa_id": 1,
    "mes": 6,
    "ano": 2026,
    "valor_folha": "12500.00",
    "valor_inss": "3300.00",
    "valor_total": "15800.00",
    "created_at": "2026-06-01T09:00:00",
    "updated_at": "2026-06-01T11:42:00"
  }
}

Escopo: sn_folha:write

DELETE /sn-folha/{folha_id}

Remove uma folha pelo ID. Quando não encontrada, retorna 404 Not Found.

Parâmetros

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Folha removida com sucesso",
  "data": null
}

Escopo: sn_folha:write

Schemas

SnFolhaCreate

Payload de criação (POST /sn-folha/) e item do PUT /sn-folha/batch.

SnFolhaUpdate

Todos os campos são opcionais; apenas os enviados são atualizados. O empresa_id não aparece aqui - é imutável, para bloquear troca de dono via PUT (mass-assignment).

SnFolhaRead

Leitura - valida a partir do ORM e serializa com os nomes do contrato.

Notas

• Toda resposta segue o envelope { success, message, data } (ou { success: false, message, details } em erro).
• valor_total é derivado (valor_folha + valor_inss) apenas na serialização de leitura - não é aceito no corpo de criação/atualização nem é gravado no banco.
• empresa_id, created_at e updated_at no JSON mapeiam, respectivamente, id_cliente, data_hora_criacao e data_hora_atualizacao do modelo interno.
• Armadilha de roteamento FastAPI: a rota literal PUT /sn-folha/batch é declarada antes da rota dinâmica PUT /sn-folha/{folha_id}, para que batch não seja interpretado como um folha_id.
• A criação impede duplicatas: empresa + mês + ano é uma combinação única (409 Conflict em caso de conflito). Para atualizar várias competências de uma vez sem se preocupar com existência prévia, use PUT /sn-folha/batch.