SN Analytics: Prefeitura

Endpoints da WebApiAlcance para o módulo SN Analytics: Prefeitura - dados de prefeitura (notas fiscais de serviço, ISS e faturamento) no contexto do Simples Nacional. O domínio organiza os lançamentos em registros (cada NFS-e/serviço) que alimentam consolidados por empresa e competência (MM/YYYY), com totais de faturamento calculados no servidor. Cobrem listagem de consolidados, listagem paginada de registros, criação individual e em lote, atualização de valores em lote, atualização e exclusão de registro.

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

Escopos necessários

sn_prefeitura:read - listagem de consolidados e de registros
sn_prefeitura:write - criação (individual e batch), atualização (individual e batch-valores) e exclusão

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

Endpoints

`GET /sn-prefeitura/consolidados`

Lista os consolidados de prefeitura (totais por empresa e competência). Os totais são calculados server-side a partir dos registros. Lista vazia é um estado válido - retorna 200 OK com data: [] (ex.: banco recém-migrado sem dados da empresa).

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": "Consolidados recuperados com sucesso",
  "data": [
    {
      "id": 10,
      "empresa_id": 1234,
      "competencia": "03/2026",
      "total_faturamento": 15000.0,
      "total_faturamento_retido_s": 5000.0,
      "total_faturamento_retido_n": 10000.0,
      "created_at": "2026-03-31T12:00:00",
      "updated_at": "2026-03-31T12:00:00"
    }
  ]
}

Escopo: sn_prefeitura:read

`GET /sn-prefeitura/registros`

Lista os registros de prefeitura de forma paginada, com filtros opcionais por empresa e intervalo de data_hora_nfe. Retorna data como objeto { items, total }, onde total é a contagem sem paginação.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`empresa_id`	`int`	query	não	Filtra por empresa (`customer.id`)
`data_inicio`	`datetime`	query	não	Filtro inicial de `data_hora_nfe` (ISO 8601)
`data_fim`	`datetime`	query	não	Filtro final de `data_hora_nfe` (ISO 8601)
`limit`	`int`	query	não	Itens por página (`1`-`10000`, default `1000`)
`offset`	`int`	query	não	Offset de paginação (`>= 0`, default `0`)

Request

Sem corpo de requisição. Exemplo de chamada com filtros e paginação:

GET /api/v1/sn-prefeitura/registros?empresa_id=1234&data_inicio=2026-03-01T00:00:00&data_fim=2026-03-31T23:59:59&limit=500&offset=0

Response 200 OK

{
  "success": true,
  "message": "Registros recuperados com sucesso",
  "data": {
    "items": [
      {
        "id": 501,
        "empresa_id": 1234,
        "consolidado_id": 10,
        "data_hora_nfe": "2026-03-15T09:30:00",
        "competencia": "03/2026",
        "valor_servicos": 2500.0,
        "iss_retido": "N",
        "numero_nfse": "2026000123",
        "created_at": "2026-03-15T09:31:00",
        "updated_at": "2026-03-15T09:31:00"
      }
    ],
    "total": 1
  }
}

Escopo: sn_prefeitura:read

`POST /sn-prefeitura/registros`

Cria um registro individual de prefeitura. Ao criar, o service recalcula o consolidado da empresa/competência correspondente.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query - os dados vão no corpo da requisição (SnPrefeituraRegistroCreate): empresa_id, data_hora_nfe, competencia (padrão MM/YYYY), valor_servicos, iss_retido e numero_nfse.

Request

{
  "empresa_id": 1234,
  "data_hora_nfe": "2026-03-15T09:30:00",
  "competencia": "03/2026",
  "valor_servicos": 2500.0,
  "iss_retido": "N",
  "numero_nfse": "2026000123"
}

Response 201 Created

{
  "success": true,
  "message": "Registro criado com sucesso",
  "data": {
    "id": 501,
    "empresa_id": 1234,
    "consolidado_id": 10,
    "data_hora_nfe": "2026-03-15T09:30:00",
    "competencia": "03/2026",
    "valor_servicos": 2500.0,
    "iss_retido": "N",
    "numero_nfse": "2026000123",
    "created_at": "2026-03-15T09:31:00",
    "updated_at": "2026-03-15T09:31:00"
  }
}

Escopo: sn_prefeitura:write

`POST /sn-prefeitura/registros/batch`

Cria registros em lote (até 5000 itens por chamada). Recalcula os consolidados afetados, agrupados por empresa/competência.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query - o corpo é um array de SnPrefeituraRegistroCreate (mesmos campos do POST individual).

Request

[
  {
    "empresa_id": 1234,
    "data_hora_nfe": "2026-03-15T09:30:00",
    "competencia": "03/2026",
    "valor_servicos": 2500.0,
    "iss_retido": "N",
    "numero_nfse": "2026000123"
  },
  {
    "empresa_id": 1234,
    "data_hora_nfe": "2026-03-16T10:00:00",
    "competencia": "03/2026",
    "valor_servicos": 800.0,
    "iss_retido": "S",
    "numero_nfse": "2026000124"
  }
]

Response 201 Created

{
  "success": true,
  "message": "Registros criados com sucesso",
  "data": [
    {
      "id": 501,
      "empresa_id": 1234,
      "consolidado_id": 10,
      "data_hora_nfe": "2026-03-15T09:30:00",
      "competencia": "03/2026",
      "valor_servicos": 2500.0,
      "iss_retido": "N",
      "numero_nfse": "2026000123",
      "created_at": "2026-03-15T09:31:00",
      "updated_at": "2026-03-15T09:31:00"
    }
  ]
}

Escopo: sn_prefeitura:write

`PUT /sn-prefeitura/registros/batch-valores`

Atualiza valores em lote (até 5000 itens). Recalcula os consolidados afetados. Cada item identifica o registro por id e atualiza apenas valor_servicos e, opcionalmente, numero_nfse.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query - o corpo é um array de SnPrefeituraRegistroBatchValores.

Request

[
  { "id": 501, "valor_servicos": 2600.0, "numero_nfse": "2026000123" },
  { "id": 502, "valor_servicos": 900.0 }
]

Response 200 OK

{
  "success": true,
  "message": "Valores atualizados com sucesso",
  "data": [
    {
      "id": 501,
      "empresa_id": 1234,
      "consolidado_id": 10,
      "data_hora_nfe": "2026-03-15T09:30:00",
      "competencia": "03/2026",
      "valor_servicos": 2600.0,
      "iss_retido": "N",
      "numero_nfse": "2026000123",
      "created_at": "2026-03-15T09:31:00",
      "updated_at": "2026-03-16T14:20:00"
    }
  ]
}

Escopo: sn_prefeitura:write

`PUT /sn-prefeitura/registros/{registro_id}`

Atualiza um registro existente. Body é um SnPrefeituraRegistroUpdate com campos parciais - somente o que vier preenchido é alterado. Se empresa_id e/ou competencia mudarem, o service re-vincula o registro ao consolidado correto e recalcula ambos os consolidados envolvidos. O campo consolidado_id nunca é aceito do cliente.

Parâmetros

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

Request (SnPrefeituraRegistroUpdate - todos os campos opcionais)

{
  "valor_servicos": 2800.0,
  "iss_retido": "S"
}

Response 200 OK

{
  "success": true,
  "message": "Registro atualizado com sucesso",
  "data": {
    "id": 501,
    "empresa_id": 1234,
    "consolidado_id": 10,
    "data_hora_nfe": "2026-03-15T09:30:00",
    "competencia": "03/2026",
    "valor_servicos": 2800.0,
    "iss_retido": "S",
    "numero_nfse": "2026000123",
    "created_at": "2026-03-15T09:31:00",
    "updated_at": "2026-03-16T15:05:00"
  }
}

Quando não encontrado, retorna 404 Not Found. Escopo: sn_prefeitura:write

`DELETE /sn-prefeitura/registros/{registro_id}`

Remove um registro pelo ID. O service recalcula (ou apaga, se ficar vazio) o consolidado associado.

Parâmetros

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

Request

Sem corpo de requisição.

Response 200 OK

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

Quando não encontrado, retorna 404 Not Found. Escopo: sn_prefeitura:write

Schemas

`SnPrefeituraRegistroCreate`

Campo	Tipo	Obrigatório	Observações
`empresa_id`	`int`	sim	Empresa dona do registro (`customer.id`).
`data_hora_nfe`	`datetime`	sim	Data/hora da NFS-e (ISO 8601).
`competencia`	`str`	sim	Competência no padrão `MM/YYYY` (mês `01`-`12`).
`valor_servicos`	`decimal`	não	Valor dos serviços (até 15 dígitos, 2 casas). Default `0`.
`iss_retido`	`str`	não	`"S"` ou `"N"`. Default `"N"`.
`numero_nfse`	`str`	não	Número da NFS-e (até 50 caracteres). Default `null`.

`SnPrefeituraRegistroUpdate`

Todos os campos são opcionais; apenas os enviados são atualizados. consolidado_id não é aceito.

Campo	Tipo	Observações
`empresa_id`	`int`	Pode mudar - re-vincula ao consolidado correto.
`data_hora_nfe`	`datetime`	Nova data/hora da NFS-e.
`competencia`	`str`	Padrão `MM/YYYY`. Pode mudar - recalcula consolidados envolvidos.
`valor_servicos`	`decimal`	Até 15 dígitos, 2 casas.
`iss_retido`	`str`	`"S"` ou `"N"`.
`numero_nfse`	`str`	Até 50 caracteres.

`SnPrefeituraRegistroBatchValores`

Item do PUT /registros/batch-valores.

Campo	Tipo	Obrigatório	Observações
`id`	`int`	sim	ID do registro a atualizar.
`valor_servicos`	`decimal`	sim	Novo valor dos serviços (até 15 dígitos, 2 casas).
`numero_nfse`	`str`	não	Novo número da NFS-e (até 50 caracteres).

`SnPrefeituraRegistroRead`

Campo	Tipo	Notas
`id`	`int`	Identificador do registro.
`empresa_id`	`int`	Empresa dona (mapeia a coluna `id_cliente`).
`consolidado_id`	`int`	Consolidado ao qual o registro está vinculado.
`data_hora_nfe`	`datetime`	Data/hora da NFS-e.
`competencia`	`str`	Competência `MM/YYYY`.
`valor_servicos`	`float`	Valor dos serviços (decimal exposto como número JSON).
`iss_retido`	`str`	`"S"` ou `"N"`.
`numero_nfse`	`str`	Número da NFS-e (pode ser `null`).
`created_at`	`datetime`	Criação (mapeia `data_hora_criacao`).
`updated_at`	`datetime`	Atualização (mapeia `data_hora_atualizacao`).

`SnPrefeituraConsolidadoRead`

Somente leitura - os totais são calculados server-side a partir dos registros.

Campo	Tipo	Notas
`id`	`int`	Identificador do consolidado.
`empresa_id`	`int`	Empresa (mapeia `id_cliente`).
`competencia`	`str`	Competência `MM/YYYY`.
`total_faturamento`	`float`	Faturamento total da competência.
`total_faturamento_retido_s`	`float`	Total com ISS retido (`iss_retido = "S"`).
`total_faturamento_retido_n`	`float`	Total sem ISS retido (`iss_retido = "N"`).
`created_at`	`datetime`	Criação (mapeia `data_hora_criacao`).
`updated_at`	`datetime`	Atualização (mapeia `data_hora_atualizacao`).

Notas

Armadilha de roteamento FastAPI. As rotas estáticas POST /registros/batch e PUT /registros/batch-valores são declaradas antes da rota dinâmica PUT|DELETE /registros/{registro_id}. O FastAPI faz match na ordem de declaração, então batch/batch-valores são resolvidos como rotas estáticas (e não interpretados como um registro_id).

Toda resposta segue o envelope { success, message, data } (ou { success: false, message, details } em erro).
O JSON expõe empresa_id, created_at e updated_at, que mapeiam as colunas id_cliente, data_hora_criacao e data_hora_atualizacao. O campo interno legacy_uuid não é exposto.
Valores decimais (valor_servicos, totais) saem como número JSON (float) nos schemas de leitura.
Operações de escrita (criar, atualizar, batch, excluir) sempre recalculam os consolidados afetados. Consolidados não têm endpoint de escrita direto - são derivados dos registros.
Erros de validação canônicos são mapeados para HTTP: "não encontrado" → 404, "já existe"/"duplicado" → 409, demais → 422.
Listas vazias retornam 200 OK com data: [] - estado normal para o front de analytics.