SN Analytics: Domínio Registros

Endpoints da WebApiAlcance para os registros do sistema Domínio importados para a análise SN (Simples Nacional). Cada registro representa uma competência (mês/ano) de uma empresa, com CNPJ, razão social e valor. Cobrem listagem (com filtro opcional por empresa), upsert em lote, atualização parcial e exclusão.

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-dominio-registros

Escopos necessários

sn_dominio_registros:read - listagem dos registros
sn_dominio_registros:write - upsert em lote, atualização e exclusão

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

Endpoints

`GET /sn-dominio-registros/`

Lista os registros do Domínio importados para a análise SN. Aceita filtro opcional por empresa. Lista vazia é um estado válido - sempre retorna 200 OK, inclusive com data: [].

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": "Registros do Domínio recuperados com sucesso",
  "data": [
    {
      "id": 101,
      "empresa_id": 1234,
      "cnpj": "12345678000199",
      "razao_social": "ACME SERVICOS LTDA",
      "competencia": "03/2026",
      "mes": 3,
      "ano": 2026,
      "valor": 1520.75,
      "created_at": "2026-04-01T10:00:00",
      "updated_at": "2026-04-01T10:00:00"
    }
  ]
}

Escopo: sn_dominio_registros:read

`PUT /sn-dominio-registros/batch`

Faz o upsert de registros do Domínio em lote - cria ou atualiza cada item conforme já exista. O corpo é um array de SnDominioRegistroCreate, com limite de 5000 itens por requisição.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query - os dados vão no corpo da requisição, um array de SnDominioRegistroCreate. Cada item exige empresa_id, cnpj, razao_social e competencia; mes/ano são derivados da competencia quando omitidos.

Request

[
  {
    "empresa_id": 1234,
    "cnpj": "12.345.678/0001-99",
    "razao_social": "ACME SERVICOS LTDA",
    "competencia": "03/2026",
    "valor": 1520.75
  }
]

Response 200 OK

{
  "success": true,
  "message": "Batch processado com sucesso",
  "data": [
    {
      "id": 101,
      "empresa_id": 1234,
      "cnpj": "12345678000199",
      "razao_social": "ACME SERVICOS LTDA",
      "competencia": "03/2026",
      "mes": 3,
      "ano": 2026,
      "valor": 1520.75,
      "created_at": "2026-04-01T10:00:00",
      "updated_at": "2026-04-01T10:00:00"
    }
  ]
}

Escopo: sn_dominio_registros:write

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

Atualiza um registro existente. O body é um SnDominioRegistroUpdate com campos parciais - somente o que vier preenchido é alterado. O campo empresa_id não pode ser alterado por esta rota (mass-assignment bloqueado). Quando não encontrado, retorna 404 Not Found.

Parâmetros

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

O corpo é um SnDominioRegistroUpdate (todos os campos opcionais): cnpj, razao_social, competencia, mes, ano e/ou valor. Se a competencia mudar e mes/ano não vierem, são re-derivados.

Request

{
  "razao_social": "ACME SERVICOS S.A.",
  "valor": 1875.4
}

Response 200 OK

{
  "success": true,
  "message": "Registro atualizado com sucesso",
  "data": {
    "id": 101,
    "empresa_id": 1234,
    "cnpj": "12345678000199",
    "razao_social": "ACME SERVICOS S.A.",
    "competencia": "03/2026",
    "mes": 3,
    "ano": 2026,
    "valor": 1875.4,
    "created_at": "2026-04-01T10:00:00",
    "updated_at": "2026-04-08T14:30:00"
  }
}

Escopo: sn_dominio_registros:write

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

Remove um registro do Domínio pelo ID. Quando não encontrado, retorna 404 Not Found.

Parâmetros

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

Request

Sem corpo de requisição.

Response 200 OK

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

Escopo: sn_dominio_registros:write

Schemas

`SnDominioRegistroCreate`

Campo	Tipo	Obrigatório	Observações
`empresa_id`	`int`	sim	ID da empresa (`customer.id`).
`cnpj`	`str`	sim	1 a 20 caracteres; normalizado para somente dígitos (até 14).
`razao_social`	`str`	sim	1 a 255 caracteres.
`competencia`	`str`	sim	Formato `MM/YYYY` (mês `01`-`12`).
`mes`	`int`	não	`1`-`12`. Derivado da `competencia` quando omitido.
`ano`	`int`	não	`1900`-`9999`. Derivado da `competencia` quando omitido.
`valor`	`Decimal`	não	Até 15 dígitos, 2 casas decimais. Default `0`.

`SnDominioRegistroUpdate`

Todos os campos são opcionais; apenas os enviados são atualizados. Não inclui empresa_id.

Campo	Tipo	Observações
`cnpj`	`str`	1 a 20 caracteres; normalizado para somente dígitos (até 14).
`razao_social`	`str`	1 a 255 caracteres.
`competencia`	`str`	Formato `MM/YYYY`. Se mudar, re-deriva `mes`/`ano` quando omitidos.
`mes`	`int`	`1`-`12`.
`ano`	`int`	`1900`-`9999`.
`valor`	`Decimal`	Até 15 dígitos, 2 casas decimais.

`SnDominioRegistroRead`

Campo	Tipo	Notas
`id`	`int`	Identificador do registro.
`empresa_id`	`int`	ID da empresa (aceita alias `id_cliente`).
`cnpj`	`str`	CNPJ em dígitos.
`razao_social`	`str`	Razão social.
`competencia`	`str`	Competência `MM/YYYY`.
`mes`	`int`	Mês (`1`-`12`).
`ano`	`int`	Ano.
`valor`	`float`	Valor do registro.
`created_at`	`datetime`	Data/hora de criação (alias `data_hora_criacao`).
`updated_at`	`datetime`	Data/hora de atualização (alias `data_hora_atualizacao`).

Notas

Toda resposta segue o envelope { success, message, data } (ou { success: false, message, details } em erro).
Ordem de rotas (FastAPI). A rota estática PUT /sn-dominio-registros/batch é declarada antes da rota dinâmica PUT /sn-dominio-registros/{registro_id}, para que batch não seja interpretado como um registro_id.
O cnpj é normalizado para somente dígitos (até 14) - máscaras enviadas no request são removidas antes de persistir.
mes e ano são derivados da competencia (MM/YYYY) quando não informados.
O batch aceita no máximo 5000 itens por requisição.
Erros de validação de negócio retornam 404 (não encontrado), 409 (já existe/duplicado) ou 422 (demais casos).