SN Analytics: Empresas

Endpoints da WebApiAlcance para o cadastro de empresas do Simples Nacional - a configuração SN vinculada a cada cliente (customer), consumida pelo produto Simples Analytics. Cada "empresa SN" é a junção do cliente cadastrado com sua configuração tributária do Simples (CNAE, tipo de atividade, anexos permitidos, Fator R, regime de apuração, sublimite, ISS etc.). Os endpoints cobrem a listagem de todas as empresas SN, o upsert em lote por CNPJ normalizado e a exclusão dos dados SN de uma empresa.

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

Escopos necessários

sn_empresas:read - listagem de empresas SN
sn_empresas:write - upsert em lote e exclusão

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

Pasta interna x prefixo público

Internamente o domínio vive na pasta customer_simples_config, mas o prefixo exposto e o recurso de escopo derivam do caminho público /sn-empresas. Use sempre sn_empresas:read / sn_empresas:write.

Endpoints

`GET /sn-empresas/`

Lista todas as empresas SN (cliente + configuração). Lista vazia é um estado válido - antes da primeira importação do analytics, o retorno normal é data: [] com 200 OK (não é erro).

Parâmetros

Este endpoint não recebe parâmetros de rota ou query. O data da resposta é um array de EmpresaRead.

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Empresas SN recuperadas com sucesso",
  "data": [
    {
      "id": 1234,
      "nome": "ACME SERVICOS LTDA",
      "cnpj": "12345678000199",
      "cnae": "6201500",
      "tipo_atividade": "servicos_V",
      "anexos_permitidos": ["III"],
      "utiliza_fator_r": false,
      "regime_apuracao": "competencia",
      "possui_sublimite": false,
      "atividade_servico": false,
      "iss_aliquota_fixa": false,
      "iss_aliquota_fixa_valor": "0",
      "observacao": null,
      "matriz_id": null,
      "created_at": "2026-01-15T10:00:00",
      "updated_at": "2026-01-15T10:00:00"
    }
  ]
}

Escopo: sn_empresas:read

`PUT /sn-empresas/batch`

Faz upsert em lote de empresas SN, identificando cada item pelo CNPJ normalizado (somente dígitos). Se o CNPJ já existir, a configuração é atualizada, caso contrário é criada.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query. O corpo é um array de EmpresaUpsert, com no máximo 5000 itens.

Request

[
  {
    "nome": "ACME SERVICOS LTDA",
    "cnpj": "12.345.678/0001-99",
    "cnae": "6201500",
    "tipo_atividade": "servicos_V",
    "anexos_permitidos": ["III"],
    "utiliza_fator_r": true,
    "regime_apuracao": "competencia",
    "possui_sublimite": false,
    "atividade_servico": true,
    "iss_aliquota_fixa": false,
    "iss_aliquota_fixa_valor": "0",
    "observacao": null,
    "matriz_id": null
  }
]

Response 200 OK

{
  "success": true,
  "message": "Empresas SN atualizadas com sucesso",
  "data": [
    { "id": 1234, "nome": "ACME SERVICOS LTDA", "cnpj": "12345678000199" }
  ]
}

Erros de validação de negócio retornam com código mapeado: 404 Not Found (não encontrado), 409 Conflict (já existe / duplicado) ou 422 Unprocessable Entity (demais casos), com a mensagem em detail. Escopo: sn_empresas:write

`DELETE /sn-empresas/{empresa_id}`

Exclui a configuração SN e todos os dados SN da empresa. Não apaga o customer - remove apenas o vínculo/dados do Simples Analytics. Quando o ID não existe, retorna 404 Not Found com a mensagem em detail.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`empresa_id`	`int`	path	sim	ID da empresa SN (equivale ao `customer.id`)

Request

Sem corpo de requisição.

Response 200 OK

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

Escopo: sn_empresas:write

Schemas

`EmpresaUpsert`

Item do corpo do PUT /sn-empresas/batch. Estende os campos de configuração (EmpresaConfigBase) com a identificação da empresa.

Campo	Tipo	Obrigatório	Observações
`nome`	`str`	sim	1 a 200 caracteres.
`cnpj`	`str`	sim	Normalizado para somente dígitos; deve ter 11 (CPF) ou 14 (CNPJ).
`cnae`	`str`	não	Máx. 20 caracteres. Default `null`.
`tipo_atividade`	`str` (enum)	não	`comercio`, `industria`, `servicos_III`, `servicos_IV`, `servicos_V`. Default `servicos_V`.
`anexos_permitidos`	`List[str]`	não	Valores `I`, `II`, `III`, `IV`, `V`. Default `["III"]`.
`utiliza_fator_r`	`bool`	não	Default `false`.
`regime_apuracao`	`str` (enum)	não	`competencia` ou `caixa`. Default `competencia`.
`possui_sublimite`	`bool`	não	Default `false`.
`atividade_servico`	`bool`	não	Default `false`.
`iss_aliquota_fixa`	`bool`	não	Default `false`.
`iss_aliquota_fixa_valor`	`Decimal`	não	`>= 0`. Default `0`.
`observacao`	`str`	não	Máx. 10000 caracteres. Default `null`.
`matriz_id`	`int`	não	`customer.id` da matriz. Default `null`.

`EmpresaRead`

Junção do cliente com a configuração SN, retornada nas listagens e no upsert. id = customer.id, nome = razao_social, cnpj = cpfecnpj normalizado (somente dígitos).

Campo	Tipo	Notas
`id`	`int`	Identificador (equivale ao `customer.id`).
`nome`	`str`	Razão social do cliente.
`cnpj`	`str`	CNPJ/CPF normalizado (somente dígitos).
`cnae`	`str`	CNAE principal.
`tipo_atividade`	`str` (enum)	`comercio`, `industria`, `servicos_III`, `servicos_IV`, `servicos_V`.
`anexos_permitidos`	`List[str]`	Anexos do Simples (`I`..`V`).
`utiliza_fator_r`	`bool`	Se aplica o Fator R.
`regime_apuracao`	`str` (enum)	`competencia` ou `caixa`.
`possui_sublimite`	`bool`	Se está sujeita a sublimite.
`atividade_servico`	`bool`	Se é atividade de serviço.
`iss_aliquota_fixa`	`bool`	Se o ISS é por alíquota fixa.
`iss_aliquota_fixa_valor`	`Decimal`	Valor fixo do ISS (quando aplicável).
`observacao`	`str`	Observação livre.
`matriz_id`	`int`	`customer.id` da matriz (quando filial).
`created_at`	`datetime`	Data/hora de criação.
`updated_at`	`datetime`	Data/hora da última atualização.

Notas

Toda resposta segue o envelope { success, message, data } (ou { success: false, message, details } em erro).
GET /sn-empresas/ sempre retorna 200 OK; lista vazia (data: []) é estado normal do analytics antes da primeira importação, não um erro.
Ordem de rotas (FastAPI): a rota literal PUT /sn-empresas/batch é declarada antes da rota dinâmica DELETE /sn-empresas/{empresa_id} para que o match ocorra na ordem correta.
O PUT /sn-empresas/batch aceita no máximo 5000 itens por chamada e usa o CNPJ normalizado como chave do upsert (11 ou 14 dígitos após remover máscara).
DELETE /sn-empresas/{empresa_id} remove apenas os dados SN - o cliente (customer) é preservado.