SN Analytics: Importações

Endpoints da WebApiAlcance para o histórico de importações do Simples Analytics (app webapp-analytics). Registram, para fins de auditoria, cada importação de dados/arquivos executada por um usuário autenticado - o tipo da importação (clientes via API, CSV de prefeitura, relatório de ISS, PDF de faturamento, Domínio), o resultado (sucesso, parcial, erro) e as contagens de registros processados. Cobrem o registro de uma importação e a listagem paginada com filtros opcionais.

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.

Somente auditoria

Estes endpoints não executam a importação em si nem recebem upload de arquivos (não há multipart/form-data nem task Celery). Eles apenas registram o histórico do que foi importado pelo webapp-analytics. O campo nome_arquivo guarda apenas o nome do arquivo processado, para referência.

Base path

/api/v1/sn-importacoes

Escopos necessários

sn_importacoes:read - listagem do histórico de importações
sn_importacoes:write - registro de uma nova importação

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

Endpoints

`POST /sn-importacoes/`

Registra uma nova importação no histórico (auditoria vinculada ao usuário autenticado). O usuario_id e o usuario_nome são preenchidos automaticamente a partir do usuário logado - não vêm no body.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query - os dados vão no corpo da requisição (SnImportacaoCreate): tipo é obrigatório e os demais campos têm default. Quando data_hora é omitido, o service usa datetime.now().

Request

{
  "tipo": "prefeitura_csv",
  "status": "parcial",
  "nome_arquivo": "notas_salvador_2026-07.csv",
  "total_registros": 1200,
  "inseridos": 1150,
  "atualizados": 30,
  "erros": 20,
  "detalhes": "20 linhas ignoradas por CNPJ inválido",
  "empresa_id": 1234
}

Response 200 OK

{
  "success": true,
  "message": "Importação registrada com sucesso",
  "data": {
    "id": 87,
    "data_hora": "2026-07-03T14:22:10",
    "tipo": "prefeitura_csv",
    "status": "parcial",
    "nome_arquivo": "notas_salvador_2026-07.csv",
    "total_registros": 1200,
    "inseridos": 1150,
    "atualizados": 30,
    "erros": 20,
    "detalhes": "20 linhas ignoradas por CNPJ inválido",
    "usuario_id": 7,
    "usuario_nome": "Felipe Venâncio",
    "empresa_id": 1234,
    "created_at": "2026-07-03T14:22:10",
    "updated_at": "2026-07-03T14:22:10"
  }
}

Erros de validação de negócio retornam o status HTTP conforme a mensagem canônica do service: 404 Not Found (não encontrado), 409 Conflict (já existe / duplicado) ou 422 Unprocessable Entity (demais casos). Escopo: sn_importacoes:write

`GET /sn-importacoes/`

Lista o histórico de importações com paginação e filtros opcionais. Lista vazia é um estado válido - sempre retorna 200 OK, inclusive com items: [].

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`empresa_id`	`int`	query	não	Filtra por empresa (`customer.id`).
`tipo`	`str`	query	não	Filtra por tipo de importação.
`status`	`str`	query	não	Filtra por status (`sucesso`, `parcial`, `erro`).
`limit`	`int`	query	não	Itens por página. Default `50`, máximo `1000`.
`offset`	`int`	query	não	Deslocamento para paginação. Default `0` (`>= 0`).

Request

Sem corpo de requisição.

Response 200 OK

O data traz o array items (cada item é um SnImportacaoRead) e o total de registros que casam com o filtro.

{
  "success": true,
  "message": "Histórico de importações recuperado com sucesso",
  "data": {
    "items": [
      {
        "id": 87,
        "data_hora": "2026-07-03T14:22:10",
        "tipo": "prefeitura_csv",
        "status": "parcial",
        "nome_arquivo": "notas_salvador_2026-07.csv",
        "total_registros": 1200,
        "inseridos": 1150,
        "atualizados": 30,
        "erros": 20,
        "detalhes": "20 linhas ignoradas por CNPJ inválido",
        "usuario_id": 7,
        "usuario_nome": "Felipe Venâncio",
        "empresa_id": 1234,
        "created_at": "2026-07-03T14:22:10",
        "updated_at": "2026-07-03T14:22:10"
      }
    ],
    "total": 1
  }
}

Escopo: sn_importacoes:read

Schemas

`SnImportacaoCreate`

Body do POST /sn-importacoes/. Apenas tipo é obrigatório; os demais têm default.

Campo	Tipo	Obrigatório	Observações
`tipo`	`TipoImportacao`	sim	Um de: `clientes_api`, `prefeitura_csv`, `iss_relatorio`, `pdf_faturamento`, `dominio`.
`status`	`StatusImportacao`	não	Um de: `sucesso`, `parcial`, `erro`. Default `sucesso`.
`nome_arquivo`	`str`	não	Nome do arquivo processado. Máx. 255 caracteres. Default `null`.
`total_registros`	`int`	não	Total de registros lidos. `>= 0`. Default `0`.
`inseridos`	`int`	não	Registros inseridos. `>= 0`. Default `0`.
`atualizados`	`int`	não	Registros atualizados. `>= 0`. Default `0`.
`erros`	`int`	não	Registros com erro. `>= 0`. Default `0`.
`detalhes`	`str`	não	Texto livre com detalhes/observações da importação. Default `null`.
`empresa_id`	`int`	não	Empresa (`customer.id`) relacionada. Mapeia para a coluna `id_cliente`. Default `null`.
`data_hora`	`datetime`	não	Momento da importação. Quando omitido, o service usa `datetime.now()`.

`SnImportacaoRead`

Objeto retornado no data (e em cada items[]). O JSON expõe empresa_id, created_at e updated_at (contrato §gerais).

Campo	Tipo	Notas
`id`	`int`	Identificador do registro de importação.
`data_hora`	`datetime`	Momento da importação.
`tipo`	`str`	Tipo de importação.
`status`	`str`	Resultado (`sucesso`, `parcial`, `erro`).
`nome_arquivo`	`str`	Nome do arquivo processado (ou `null`).
`total_registros`	`int`	Total de registros lidos.
`inseridos`	`int`	Registros inseridos.
`atualizados`	`int`	Registros atualizados.
`erros`	`int`	Registros com erro.
`detalhes`	`str`	Detalhes/observações (ou `null`).
`usuario_id`	`int`	Usuário que executou a importação (ou `null`).
`usuario_nome`	`str`	Nome do usuário que executou (ou `null`).
`empresa_id`	`int`	Empresa relacionada. Deriva da coluna `id_cliente` (ou `null`).
`created_at`	`datetime`	Criação do registro. Deriva de `data_hora_criacao`.
`updated_at`	`datetime`	Última atualização. Deriva de `data_hora_atualizacao`.

Notas

Toda resposta segue o envelope { success, message, data } (ou { success: false, message, details } em erro).
usuario_id e usuario_nome do registro vêm sempre do usuário autenticado no POST - não são aceitos no body.
empresa_id é o alias público da coluna interna id_cliente; no SnImportacaoRead a leitura aceita tanto id_cliente quanto empresa_id.
A listagem é paginada por limit/offset e retorna o total de registros que casam com o filtro - use-o para calcular as páginas seguintes.
empresa_id referencia um cliente do cadastro. Consulte Customers para os campos de cada empresa.