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 detalhe e a atualização parcial da configuração de uma empresa, 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.
Base path
/api/v1/sn-empresasEscopos necessários
sn_empresas:read- listagem e detalhe de empresas SNsn_empresas:write- upsert em lote, atualização parcial 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).
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
{
"status": "success",
"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. Restrita a usuários com permissão adicional; sem ela, a resposta é 403.
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
{
"status": "success",
"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
GET /sn-empresas/{customer_id}
Detalhe de uma empresa SN: dados cadastrais do cliente (somente leitura, com endereço) mais a configuração SN. A consulta não cria configuração: cliente sem configuração retorna config_presente: false e os campos de configuração com null ou valores padrão. Cliente inexistente retorna 404 Not Found.
Parâmetros
| Parâmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
customer_id | int | path | sim | ID do cliente (igual ao id da empresa SN) |
Request
Sem corpo de requisição.
Response 200 OK
{
"status": "success",
"message": "Empresa SN recuperada com sucesso",
"data": {
"id": 1234,
"nome": "ACME SERVICOS LTDA",
"cnpj": "12345678000199",
"nome_fantasia": "ACME",
"regime_tributario": "Simples Nacional",
"inscricao_estadual": null,
"inscricao_municipal": "987654321",
"email": "contato@acme.com.br",
"telefone": null,
"celular": null,
"ativo": true,
"endereco": "Rua Exemplo",
"numero": "123",
"complemento": null,
"bairro": "Centro",
"cidade": "Salvador",
"estado": "BA",
"cep": "40000-000",
"config_presente": true,
"cnae": "6201500",
"tipo_atividade": "servicos_V",
"anexos_permitidos": ["III"],
"utiliza_fator_r": true,
"regime_apuracao": "competencia",
"possui_sublimite": false,
"atividade_servico": true,
"atividade_comercio": 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"
}
}Credenciais do cliente não fazem parte da resposta.
Escopo: sn_empresas:read
PATCH /sn-empresas/{customer_id}
Atualização parcial da configuração SN de uma empresa: somente os campos enviados são alterados e os omitidos permanecem intactos (diferente do PUT /sn-empresas/batch, que reescreve a configuração inteira). Se o cliente ainda não tem configuração SN, ela é criada com os valores padrão mais os campos enviados. Restrita a usuários com permissão adicional; sem ela, a resposta é 403. Retorna o mesmo formato do GET /sn-empresas/{customer_id}.
Parâmetros
| Parâmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
customer_id | int | path | sim | ID do cliente |
O corpo é um EmpresaConfigUpdate.
Request
{
"utiliza_fator_r": true,
"observacao": "Fator R aplicado a partir de 2026."
}Response 200 OK
{
"status": "success",
"message": "Config SN atualizada com sucesso",
"data": {
"id": 1234,
"nome": "ACME SERVICOS LTDA",
"cnpj": "12345678000199",
"config_presente": true,
"utiliza_fator_r": true,
"observacao": "Fator R aplicado a partir de 2026."
}
}Regras de validação
Campo desconhecido (inclusive nome, cnpj e id_cliente) retorna 422. null explícito é
rejeitado com 422 nos campos obrigatórios (tipo_atividade, anexos_permitidos,
utiliza_fator_r, regime_apuracao, possui_sublimite, atividade_servico,
atividade_comercio, iss_aliquota_fixa, iss_aliquota_fixa_valor); omita o campo para
preservar o valor. Em cnae, observacao e matriz_id, null limpa o valor. Após a
atualização, ao menos uma entre atividade_servico e atividade_comercio deve ser true, senão
422. Cliente inexistente retorna 404.
Escopo: sn_empresas:write (restrita a usuários com permissão adicional; sem ela, 403)
DELETE /sn-empresas/{empresa_id}
Exclui a configuração SN e todos os dados SN da empresa. Restrita a usuários com permissão adicional; sem ela, a resposta é 403. 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 ID do cliente) |
Request
Sem corpo de requisição.
Response 200 OK
{
"status": "success",
"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 true. |
atividade_comercio | bool | não | Default false. Ao menos uma entre atividade_servico e atividade_comercio deve ser true (senão 422). |
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 | ID do cliente matriz. Default null. |
EmpresaRead
Junção do cliente com a configuração SN, retornada nas listagens e no upsert. id = ID do cliente, nome = razao_social, cnpj = cpfecnpj normalizado (somente dígitos).
| Campo | Tipo | Notas |
|---|---|---|
id | int | Identificador (equivale ao ID do cliente). |
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. |
atividade_comercio | bool | Se é atividade de comércio. |
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 | ID do cliente matriz (quando filial). |
created_at | datetime | Data/hora de criação. |
updated_at | datetime | Data/hora da última atualização. |
EmpresaConfigUpdate
Corpo do PATCH /sn-empresas/{customer_id}. Todos os campos são opcionais; só o que for enviado é alterado.
| Campo | Tipo | Observações |
|---|---|---|
cnae | str | Máx. 20 caracteres. null limpa o valor. |
tipo_atividade | str (enum) | comercio, industria, servicos_III, servicos_IV, servicos_V. |
anexos_permitidos | List[str] | Valores I, II, III, IV, V. |
utiliza_fator_r | bool | Aplica o Fator R. |
regime_apuracao | str (enum) | competencia ou caixa. |
possui_sublimite | bool | Sujeita a sublimite. |
atividade_servico | bool | Atividade de serviço. |
atividade_comercio | bool | Atividade de comércio. |
iss_aliquota_fixa | bool | ISS por alíquota fixa. |
iss_aliquota_fixa_valor | Decimal | >= 0. |
observacao | str | Máx. 10000 caracteres. null limpa o valor. |
matriz_id | int | ID do cliente matriz. null limpa o valor. |
Notas
- Toda resposta segue o envelope
{ status, message, data }(ou{ status: "error", message, details }em erro). GET /sn-empresas/sempre retorna200 OK; lista vazia (data: []) é estado normal do analytics antes da primeira importação, não um erro.PUT /sn-empresas/batch(rota literal) é declarada antes das rotas dinâmicas/{customer_id}; usePATCH /sn-empresas/{customer_id}para editar uma única empresa sem resetar os campos omitidos.- O
PUT /sn-empresas/batchaceita 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.