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

Escopos necessários

  • sn_empresas:read - listagem e detalhe de empresas SN
  • sn_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âmetroTipoLocalObrigatórioDescrição
customer_idintpathsimID 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âmetroTipoLocalObrigatórioDescrição
customer_idintpathsimID 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âmetroTipoLocalObrigatórioDescrição
empresa_idintpathsimID 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.

CampoTipoObrigatórioObservações
nomestrsim1 a 200 caracteres.
cnpjstrsimNormalizado para somente dígitos; deve ter 11 (CPF) ou 14 (CNPJ).
cnaestrnãoMáx. 20 caracteres. Default null.
tipo_atividadestr (enum)nãocomercio, industria, servicos_III, servicos_IV, servicos_V. Default servicos_V.
anexos_permitidosList[str]nãoValores I, II, III, IV, V. Default ["III"].
utiliza_fator_rboolnãoDefault false.
regime_apuracaostr (enum)nãocompetencia ou caixa. Default competencia.
possui_sublimiteboolnãoDefault false.
atividade_servicoboolnãoDefault true.
atividade_comercioboolnãoDefault false. Ao menos uma entre atividade_servico e atividade_comercio deve ser true (senão 422).
iss_aliquota_fixaboolnãoDefault false.
iss_aliquota_fixa_valorDecimalnão>= 0. Default 0.
observacaostrnãoMáx. 10000 caracteres. Default null.
matriz_idintnãoID 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).

CampoTipoNotas
idintIdentificador (equivale ao ID do cliente).
nomestrRazão social do cliente.
cnpjstrCNPJ/CPF normalizado (somente dígitos).
cnaestrCNAE principal.
tipo_atividadestr (enum)comercio, industria, servicos_III, servicos_IV, servicos_V.
anexos_permitidosList[str]Anexos do Simples (I..V).
utiliza_fator_rboolSe aplica o Fator R.
regime_apuracaostr (enum)competencia ou caixa.
possui_sublimiteboolSe está sujeita a sublimite.
atividade_servicoboolSe é atividade de serviço.
atividade_comercioboolSe é atividade de comércio.
iss_aliquota_fixaboolSe o ISS é por alíquota fixa.
iss_aliquota_fixa_valorDecimalValor fixo do ISS (quando aplicável).
observacaostrObservação livre.
matriz_idintID do cliente matriz (quando filial).
created_atdatetimeData/hora de criação.
updated_atdatetimeData/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.

CampoTipoObservações
cnaestrMáx. 20 caracteres. null limpa o valor.
tipo_atividadestr (enum)comercio, industria, servicos_III, servicos_IV, servicos_V.
anexos_permitidosList[str]Valores I, II, III, IV, V.
utiliza_fator_rboolAplica o Fator R.
regime_apuracaostr (enum)competencia ou caixa.
possui_sublimiteboolSujeita a sublimite.
atividade_servicoboolAtividade de serviço.
atividade_comercioboolAtividade de comércio.
iss_aliquota_fixaboolISS por alíquota fixa.
iss_aliquota_fixa_valorDecimal>= 0.
observacaostrMáx. 10000 caracteres. null limpa o valor.
matriz_idintID 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 retorna 200 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}; use PATCH /sn-empresas/{customer_id} para editar uma única empresa sem resetar os campos omitidos.
  • 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.