Importações

Endpoints da WebApiAlcance para o fluxo de importação de arquivos - envio de extratos e planilhas (ofx, pdf, csv, contas, regras_conversor), leitura e conferência do parse, geração dos lançamentos contábeis e gestão do ciclo de vida de cada importação (listagem, detalhe, download do original, substituição, duplicação e exclusão).

O parse e a geração de lançamentos são síncronos - não há execução em segundo plano neste domínio: preview, confirmar, analisar-regras e confirmar-regras rodam o parser na própria requisição e devolvem o resultado no envelope.

Todos os endpoints exigem autenticação. Veja Autenticação para o fluxo de API Key.

Base path

/api/v1/importacoes

Escopos necessários

  • importacoes:read - listagem, detalhe, download do arquivo, lançamentos gerados e pré-condições da substituição
  • importacoes:write - upload, importação de ISS retido, preview, confirmar, análise/confirmação de regras, substituir, duplicar, excluir e operações de lucro da importação
  • regras_lancamento:read - adicional, exigido por GET /importacoes/{importacao_id}/regras
  • klingo:write - adicional, exigido por POST /importacoes/{importacao_id}/substituir em importação do tipo klingo

O escopo é derivado da rota: o prefixo /importacoes vira o recurso importacoes, e o método HTTP define a ação (read para GET, write para POST/DELETE).

Endpoints

POST /importacoes/upload

Faz o upload do arquivo e cria o registro de importação com status pending. Requisição multipart/form-data (não JSON). Calcula o hash SHA-256 do arquivo e, se o mesmo arquivo já foi importado para o cliente, não bloqueia: a importação é criada normalmente e a resposta traz importacao_existente como aviso.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query - os campos vão no formulário multipart/form-data:

ParâmetroTipoLocalObrigatórioDescrição
id_clienteintformsimID do cliente.
tipostr (enum)formsimUm de ofx | pdf | csv | contas | regras_conversor.
arquivofileformsimArquivo binário a importar.
id_estruturaintformnãoLayout usado (omitir para OFX; opcional p/ regras_conversor).
id_plano_contasintformnãoPlano alvo (contas/regras_conversor). NULL para OFX/PDF/CSV.
id_bancointformnãoBanco selecionado (feature Padrão de Regras por Banco). Para OFX, a resposta também traz codigo_ofx_detectado / id_banco_sugerido.

Request

Requisição multipart/form-data - os campos vão no formulário (ver tabela acima), não em JSON. Não envie um corpo JSON.

Response 201 Created

{
  "status": "success",
  "message": "Upload registrado com sucesso",
  "data": {
    "id": 812,
    "id_usuario_created": 7,
    "id_cliente": 154,
    "id_estrutura": null,
    "id_plano_contas": null,
    "id_banco": null,
    "tipo": "ofx",
    "nome_arquivo_original": "extrato-junho.ofx",
    "tamanho_bytes": 48213,
    "hash_arquivo": "9f2c...",
    "status": "pending",
    "qtd_lancamentos_criados": 0,
    "qtd_linhas_erro": 0,
    "codigo_ofx_detectado": "341",
    "id_banco_sugerido": 12,
    "importacao_existente": null
  }
}

Arquivo acima do tamanho máximo permitido retorna 413 Request Entity Too Large. Quando o arquivo já foi importado antes, importacao_existente segue o HashDuplicadoInfo (ausente/null no caso normal).

Escopo: importacoes:write

POST /importacoes/iss-retido

Importa o relatório Retenções a Recolher (ISS retido) da Domínio em PDF, fazendo upload e confirmação em uma única chamada. As contas dos lançamentos vêm das Regras de Lançamento; lançamento sem regra fica em regra_pendente. Requisição multipart/form-data.

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
arquivofileformsimPDF do relatório Retenções a Recolher (.pdf).
id_clienteintformnãoCliente. Omitido: o cliente é o do CNPJ do relatório. Informado: o CNPJ do relatório deve ser o do cliente.

Request

Requisição multipart/form-data - os campos vão no formulário, não em JSON.

Response 201 Created

{
  "status": "success",
  "message": "Importacao concluida: 14 lancamentos criados (status=success)",
  "data": {
    "importacao_id": 820,
    "qtd_criados": 14,
    "qtd_erros": 0,
    "qtd_ignorados": 0,
    "qtd_ignorados_valor_zero": 0,
    "status_final": "success",
    "data_hora_conclusao": "2026-07-03T14:22:10",
    "qtd_substituidos": null,
    "qtd_lucros_gerados": 0,
    "lucros_por_conta": null
  }
}

O data segue o schema ConfirmarResponse. Arquivo acima do tamanho máximo -> 413; cliente não encontrado para o CNPJ -> 404; relatório já importado -> 409 (exclua a importação anterior para importar de novo); arquivo que não é PDF válido ou CNPJ diferente do cliente informado -> 400. A importação criada tem tipo = "iss_retido".

Escopo: importacoes:write

GET /importacoes/

Lista as importações do escritório, com filtros opcionais. Lista vazia é estado válido - retorna 200 OK com data: [].

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
id_clienteintquerynãoFiltra por cliente.
tipostr (enum)querynãoofx | pdf | csv | contas | regras_conversor | klingo | open_finance | iss_retido.
statusstr (enum)querynãopending | processing | success | partial | error.
data_iniciodatequerynãoData inicial de data_hora_criacao (YYYY-MM-DD).
data_fimdatequerynãoData final de data_hora_criacao (YYYY-MM-DD).
limitintquerynãoPadrão 50, entre 1 e 500.
offsetintquerynãoPadrão 0, maior ou igual a 0.
meusboolquerynãotrue lista só as importações criadas pelo usuário logado. Padrão false (todo o escritório).

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Importacoes recuperadas com sucesso",
  "data": [
    {
      "id": 812,
      "id_usuario_created": 7,
      "id_cliente": 154,
      "tipo": "ofx",
      "nome_arquivo_original": "extrato-junho.ofx",
      "tamanho_bytes": 48213,
      "status": "success",
      "qtd_lancamentos_criados": 128,
      "qtd_atualizados": 0,
      "qtd_ignorados": 3,
      "qtd_linhas_erro": 0,
      "data_hora_criacao": "2026-07-03T14:20:00",
      "data_hora_conclusao": "2026-07-03T14:22:10",
      "id_relatorio_klingo": null,
      "titulo_relatorio_klingo": null,
      "id_klingo_layout": null,
      "nome_layout_klingo": null,
      "data_informada": null,
      "conta_open_finance": null,
      "periodo_inicio": null,
      "periodo_fim": null
    }
  ]
}

O data é um array de ImportacaoListItem (ou []).

Escopo: importacoes:read

GET /importacoes/{importacao_id}

Detalha uma importação pelo ID inteiro. 404 Not Found quando não existe ou não pertence ao usuário.

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
importacao_idintpathsimID interno da importação.

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Importacao encontrada",
  "data": {
    "id": 812,
    "id_usuario_created": 7,
    "id_cliente": 154,
    "id_estrutura": null,
    "id_plano_contas": null,
    "id_banco": 12,
    "tipo": "ofx",
    "nome_arquivo_original": "extrato-junho.ofx",
    "tamanho_bytes": 48213,
    "hash_arquivo": "9f2c...",
    "status": "success",
    "qtd_lancamentos_criados": 128,
    "qtd_linhas_erro": 0,
    "data_hora_criacao": "2026-07-03T14:20:00",
    "data_hora_conclusao": "2026-07-03T14:22:10"
  }
}

O data segue o schema ImportacaoRead.

Escopo: importacoes:read

GET /importacoes/{importacao_id}/arquivo

Faz o download do arquivo original do upload. A resposta não é o envelope JSON - é um FileResponse binário (application/octet-stream) com o nome_arquivo_original como nome de download.

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
importacao_idintpathsimID da importação.

Request

Sem corpo de requisição.

Response 200 OK

Stream binário do arquivo (application/octet-stream), sem envelope JSON. Retorna 404 Not Found se a importação não existir/pertencer ao usuário, se o arquivo não estiver mais disponível ou se a importação não tiver arquivo (dados vindos de integração, como klingo e open_finance).

Escopo: importacoes:read

GET /importacoes/{importacao_id}/lancamentos

Lista os lançamentos contábeis gerados a partir desta importação (id_importacao == importacao_id), ordenados por data_registro e id. A lista fica populada após um POST /confirmar bem-sucedido. Visão compartilhada do escritório - lista todos os lançamentos da importação, sem filtro por dono.

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
importacao_idintpathsimID da importação.

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Lancamentos recuperados com sucesso",
  "data": [
    {
      "id": 90211,
      "id_importacao": 812,
      "data_registro": "2026-06-01",
      "descricao": "PAGAMENTO FORNECEDOR XYZ",
      "valor": 1520.5,
      "tipo": "D",
      "regras_aplicadas": []
    }
  ]
}

O data é um array de LancamentoContabilRead (com regras_aplicadas resolvidas) ou []. 404 Not Found quando a importação não existe/pertence ao usuário.

Escopo: importacoes:read

GET /importacoes/{importacao_id}/regras

Resumo "Ver regras" do arquivo importado: regras que classificaram os lançamentos da importação, regras que ficaram em conflito e regras criadas por ela (planilha de regras). Mesmo formato de GET /exportacoes/{exportacao_id}/regras.

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
importacao_idintpathsimID da importação.

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Regras da importacao recuperadas com sucesso",
  "data": {
    "vinculo_exato": true,
    "total_lancamentos": 128,
    "lancamentos_sem_regra": 9,
    "lancamentos_em_conflito": 2,
    "regras_aplicadas": [
      { "id_regra": 15, "qtd_lancamentos": 80, "regra": { "id": 15, "nome": "Tarifa bancaria" } }
    ],
    "regras_em_conflito": [],
    "regras_criadas": []
  }
}

vinculo_exato é sempre true aqui. Cada item traz regra no mesmo formato de GET /regras-lancamento (resumido acima) ou null se a regra foi excluída; regras_criadas vêm com qtd_lancamentos = 0. 404 Not Found quando a importação não existe.

Escopo: importacoes:read + regras_lancamento:read

POST /importacoes/{importacao_id}/preview

Roda o parser e devolve as transações detectadas + erros por linha sem persistir nada. Serve para o frontend mostrar "isto é o que vai ser criado" antes do POST /confirmar.

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
importacao_idintpathsimID da importação.

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "128 lancamentos detectados",
  "data": {
    "importacao_id": 812,
    "tipo": "ofx",
    "total_linhas_lidas": 131,
    "qtd_lancamentos_detectados": 128,
    "qtd_erros": 0,
    "qtd_ignorados": 3,
    "ignorados": [],
    "qtd_ignorados_valor_zero": 0,
    "lancamentos": [
      {
        "linha_arquivo": 1,
        "data": "2026-06-01",
        "descricao": "PAGAMENTO FORNECEDOR XYZ",
        "valor": 1520.5,
        "tipo": "D"
      }
    ],
    "erros": [],
    "id_banco": 12,
    "codigo_ofx_detectado": "341",
    "id_banco_sugerido": 12
  }
}

O data segue o schema ImportacaoPreviewResponse.

Escopo: importacoes:write

POST /importacoes/{importacao_id}/confirmar

Roda o parser e persiste os lançamentos em transação atômica. Em sucesso parcial (algumas linhas falham), o status final é partial.

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
importacao_idintpathsimID da importação.
id_bancointquerynãoBanco a aplicar (feature Padrão de Regras por Banco). Quando informado, substitui/persiste o banco da importação e seus padrões ATIVOS têm precedência sobre as regras de cliente/estrutura. Omitir mantém o banco vinculado no upload.

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Importacao concluida: 128 lancamentos criados (status=success)",
  "data": {
    "importacao_id": 812,
    "qtd_criados": 128,
    "qtd_erros": 0,
    "qtd_ignorados": 3,
    "qtd_ignorados_valor_zero": 0,
    "status_final": "success",
    "data_hora_conclusao": "2026-07-03T14:22:10",
    "qtd_substituidos": null,
    "qtd_lucros_gerados": 0,
    "lucros_por_conta": null
  }
}

O data segue o schema ConfirmarResponse.

Escopo: importacoes:write

POST /importacoes/{importacao_id}/analisar-regras

Para importações do tipo regras_conversor: lê a planilha e devolve colunas detectadas, amostra (até 5 linhas), total de linhas, duplicados, contas faltantes (código de exportação sem Conta no cliente) e os planos do cliente. Não persiste.

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
importacao_idintpathsimID da importação.

O corpo segue o schema AnalisarRegrasRequest: mapeamento (obrigatório) e campo_destino, id_estrutura e id_klingo_layout (opcionais; estrutura e layout são exclusivos entre si, 422 se vierem juntos). O escopo informado recorta o universo de duplicados exibido, então deve ser o mesmo enviado depois em confirmar-regras.

Request

{
  "mapeamento": { "comparacao": 0, "exportacao": 1 },
  "campo_destino": "conta_debito"
}

Response 200 OK

{
  "status": "success",
  "message": "240 linhas analisadas",
  "data": {
    "colunas": [
      { "indice": 0, "header": "Historico" },
      { "indice": 1, "header": "Codigo" }
    ],
    "amostra": [{ "comparacao": "TARIFA", "exportacao": "3010" }],
    "total_linhas": 240,
    "mapeamento_sugerido": { "comparacao": 0, "exportacao": 1 },
    "duplicados": [],
    "contas_faltantes": [],
    "planos_cliente": [{ "id": 5, "codigo_dominio": "01", "nome": "Plano Padrao" }]
  }
}

O data segue o schema AnalisarRegrasResponse.

Escopo: importacoes:write

POST /importacoes/{importacao_id}/confirmar-regras

Processa todas as linhas da planilha, criando/atualizando RegraLancamento. O plano de contas de cada regra é derivado da conta resolvida pelo codigo_dominio (campo da exportação). Resoluções de duplicados e de contas faltantes vêm no corpo.

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
importacao_idintpathsimID da importação.

O corpo segue o schema ConfirmarRegrasRequest: mapeamento e campo_destino obrigatórios; demais campos com defaults. Para regras de relatório Klingo, informe id_klingo_layout (exclusivo com id_estrutura) e, para comparar uma coluna do relatório, campo_comparacao = "coluna_relatorio" com coluna_relatorio.

Request

{
  "mapeamento": { "comparacao": 0, "exportacao": 1 },
  "campo_comparacao": "historico",
  "modo_comparacao": "contem",
  "campo_destino": "conta_debito",
  "resolucao_duplicados": "ignorar",
  "resolucao_contas_faltantes": "ignorar"
}

Response 200 OK

{
  "status": "success",
  "message": "230 criadas, 8 atualizadas, 2 ignoradas (status=success)",
  "data": {
    "importacao_id": 815,
    "qtd_criadas": 230,
    "qtd_atualizadas": 8,
    "qtd_ignoradas": 2,
    "qtd_erros": 0,
    "status_final": "success",
    "erros": [],
    "data_hora_conclusao": "2026-07-03T15:05:40"
  }
}

O data segue o schema ConfirmarRegrasResponse. Se id_cliente_esperado divergir do cliente da importação, retorna 409 Conflict e nada é gravado. Combinações inválidas (estrutura com layout, coluna_relatorio sem id_klingo_layout) retornam 422.

Escopo: importacoes:write

GET /importacoes/{importacao_id}/substituicao

Pré-condições do diálogo "Importar novamente": quantos lançamentos o lote tem, quantos já foram exportados e se é possível reimportar. Não altera nada.

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
importacao_idintpathsimID da importação.

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Pre-condicoes da substituicao recuperadas com sucesso",
  "data": {
    "importacao_id": 812,
    "tipo": "ofx",
    "qtd_lancamentos": 128,
    "qtd_lancamentos_exportados": 0,
    "reimportavel": true,
    "motivo_nao_reimportavel": null,
    "klingo": null
  }
}

O data segue o schema SubstituicaoInfo. Para tipo = "klingo", klingo traz o relatório, o mapeamento, o período original e as datas sugeridas para a nova busca; sem o escopo klingo:write, reimportavel vem false com o motivo. 404 Not Found quando a importação não existe.

Escopo: importacoes:read

POST /importacoes/{importacao_id}/substituir

Substitui uma importação em status terminal: apaga os lançamentos antigos e roda o parser de novo no mesmo arquivo. Aceita success, partial e error. Recusa pending e processing (409 Conflict). Útil para reaplicar uma estrutura corrigida ou reavaliar após nova regra. Para tipo = "klingo", busca o relatório de novo na API da Klingo no período informado (exige também o escopo klingo:write) e troca o lote; falha da Klingo mantém os lançamentos atuais.

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
importacao_idintpathsimID da importação.

Request (opcional - sem corpo valem os defaults)

{
  "confirmar_exportados": false,
  "data_inicio": "2026-08-01",
  "data_fim": "2026-08-31",
  "data_informada": "2026-08-31"
}
CampoTipoObrigatórioObservações
confirmar_exportadosboolnãoDefault false. Com lançamentos já exportados no lote, é preciso enviar true para confirmar a substituição.
data_iniciodatenãoSó klingo: início do período a buscar de novo.
data_fimdatenãoSó klingo: fim do período a buscar de novo.
data_informadadatenãoSó klingo com mapeamento de data informada: data dos lançamentos.

Response 200 OK

{
  "status": "success",
  "message": "Importacao substituida: 128 lancamentos criados (status=success)",
  "data": {
    "importacao_id": 812,
    "qtd_criados": 128,
    "qtd_erros": 0,
    "qtd_ignorados": 3,
    "qtd_ignorados_valor_zero": 0,
    "status_final": "success",
    "data_hora_conclusao": "2026-07-03T16:10:00",
    "qtd_substituidos": 120,
    "qtd_lucros_gerados": 0,
    "lucros_por_conta": null
  }
}

O data segue o schema ConfirmarResponse; qtd_substituidos é a quantidade de lançamentos do lote anterior apagados. Retorna 409 Conflict quando o lote tem lançamento já exportado (sem confirmar_exportados), quando algum lançamento tem lucro vinculado (exclua o lucro antes) ou quando a importação está pending/processing. Na importação Klingo, período ausente retorna 422.

Escopo: importacoes:write

POST /importacoes/{importacao_id}/duplicar

Duplica uma importação: copia o arquivo no disco com novo UUID e cria um novo registro pending apontando para a original via id_importacao_original. Recusa processing (409 Conflict). Bypassa o dedup por hash internamente - duplicar é justamente reusar o mesmo arquivo. O fluxo segue com /preview e /confirmar no novo id retornado.

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
importacao_idintpathsimID da importação original.

Request

Sem corpo de requisição.

Response 201 Created

{
  "status": "success",
  "message": "Importacao duplicada com sucesso (nova id=813)",
  "data": {
    "id": 813,
    "id_usuario_created": 7,
    "id_cliente": 154,
    "id_importacao_original": 812,
    "tipo": "ofx",
    "nome_arquivo_original": "extrato-junho.ofx",
    "tamanho_bytes": 48213,
    "status": "pending",
    "qtd_lancamentos_criados": 0,
    "qtd_linhas_erro": 0,
    "data_hora_criacao": "2026-07-03T17:00:00"
  }
}

O data segue o schema ImportacaoRead da nova importação.

Escopo: importacoes:write

DELETE /importacoes/{importacao_id}

Hard delete cascade: apaga o registro de importação, todos os lançamentos vinculados e o arquivo do disco. Importações filhas (criadas via /duplicar desta) ficam órfãs (id_importacao_original = NULL via ON DELETE SET NULL) - não são deletadas em cascade.

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
importacao_idintpathsimID da importação.
excluir_regrasboolquerynãoApenas para regras_conversor. true: apaga em cascade as RegraLancamento geradas por este import. false (default): as regras são desvinculadas (id_importacao → NULL) e permanecem.
confirmar_exportadosboolquerynãoApenas para open_finance: confirma a exclusão de importação com lançamento já exportado. Sem ela, 409.

Request

Sem corpo de requisição.

Response 204 No Content

Sem body. Retorna 404 Not Found se a importação não existir ou não pertencer ao usuário. Imports contas apagam apenas registro + arquivo (não apagam contas). Se algum lançamento da importação tem lucro vinculado, retorna 409 Conflict e nada é apagado (use DELETE /importacoes/{importacao_id}/lucros antes).

Escopo: importacoes:write

POST /importacoes/{importacao_id}/lucros/gerar

Gera os lançamentos de lucro automáticos (regra Normal com sócio) que ainda faltam nos lançamentos da importação, sem duplicar. Serve para retomar uma geração que parou no meio.

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
importacao_idintpathsimID da importação.

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Lucros automaticos: 3 criado(s), 5 ja existente(s), 0 pulado(s)",
  "data": { "avaliados": 8, "candidatos": 8, "criados": 3, "existentes": 5, "pulados": 0 }
}

existentes são os lançamentos que já tinham lucro. 404 Not Found quando a importação não existe.

Escopo: importacoes:write

DELETE /importacoes/{importacao_id}/lucros

Exclui, em uma transação, todos os lançamentos de lucro nascidos dos lançamentos contábeis desta importação (automáticos ou criados à mão a partir deles). É o passo que libera a substituição e a exclusão da importação quando elas respondem 409 por lucro vinculado.

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
importacao_idintpathsimID da importação.

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "8 lancamento(s) de lucro excluido(s)",
  "data": { "excluidos": 8 }
}

Tudo ou nada: se algum lucro já foi transmitido ou está em retificação na EFD-Reinf, nada é excluído (409 Conflict). 404 Not Found quando a importação não existe.

Escopo: importacoes:write

Schemas

ImportacaoRead

Registro completo de uma importação (retorno de upload, detalhe e duplicar).

CampoTipoNotas
idintIdentificador da importação.
id_usuario_createdintUsuário que criou o upload.
usuario_nomestr?Nome do usuário criador.
id_clienteintCliente-alvo.
id_estruturaint?Layout usado (NULL para OFX).
id_plano_contasint?Plano alvo (contas/regras_conversor).
id_importacao_originalint?Import de origem quando esta foi duplicada.
id_bancoint?Banco selecionado/sugerido.
tipostr (enum)ofx | pdf | csv | contas | regras_conversor | klingo | open_finance | iss_retido.
nome_arquivo_originalstrNome original do arquivo enviado.
tamanho_bytesintTamanho do arquivo.
hash_arquivostr?SHA-256 usado no dedup.
statusstr (enum)pending | processing | success | partial | error.
qtd_lancamentos_criadosintLançamentos gerados.
qtd_atualizadosintDefault 0.
qtd_ignoradosintDefault 0.
qtd_linhas_errointLinhas que falharam no parse.
erroslist?Detalhes dos erros por linha.
data_hora_criacaodatetimeCriação do registro.
data_hora_conclusaodatetime?Preenchida ao concluir o parse.
codigo_ofx_detectadostr?BANKID lido do OFX (não persistido).
id_banco_sugeridoint?Banco do catálogo cujo codigo_ofx casa (não persistido).
importacao_existenteHashDuplicadoInfo?Aviso de que o mesmo arquivo já foi importado para o cliente (resposta do upload).
id_relatorio_klingoint?ID do relatório na Klingo. null fora do tipo klingo.
titulo_relatorio_klingostr?Título do relatório Klingo.
id_klingo_layoutint?Mapeamento Klingo aplicado.
nome_layout_klingostr?Nome do mapeamento aplicado.
data_informadadate?Data informada quando o mapeamento Klingo usa data informada.
conta_open_financeobject?Conta de origem (mascarada) de importação open_finance.
periodo_iniciodate?Início do período de importação open_finance.
periodo_fimdate?Fim do período de importação open_finance.
lancamentos_exportadosint?Só no detalhe de importação open_finance: lançamentos já exportados.

ImportacaoListItem

Versão enxuta para listagens - omite erros. Traz os mesmos campos de identificação, tipo, status, contadores (qtd_lancamentos_criados, qtd_atualizados, qtd_ignorados, qtd_linhas_erro), datas (data_hora_criacao, data_hora_conclusao) e os campos de origem do ImportacaoRead: id_relatorio_klingo, titulo_relatorio_klingo, id_klingo_layout, nome_layout_klingo, data_informada, conta_open_finance, periodo_inicio e periodo_fim.

ImportacaoPreviewResponse

Resultado do POST /preview - o que seria criado, sem persistir.

CampoTipoNotas
importacao_idintImportação analisada.
tipostr (enum)Tipo do arquivo.
total_linhas_lidasintLinhas lidas do arquivo.
qtd_lancamentos_detectadosintTransações válidas detectadas.
qtd_errosintLinhas com erro.
qtd_ignoradosintLinhas descartadas por regra de ignorar. Default 0.
qtd_ignorados_valor_zerointLinhas descartadas por terem valor zerado. Default 0.
ignoradosLancamentoIgnorado[]Linhas que serão descartadas (com regra_id/regra_nome).
lancamentosLancamentoDetectado[]Transações detectadas.
errosErroParse[]{ linha_arquivo, mensagem }.
id_bancoint?Banco já vinculado à importação.
codigo_ofx_detectadostr?BANKID lido agora (OFX).
id_banco_sugeridoint?Banco do catálogo que casa.

Cada LancamentoDetectado traz linha_arquivo, data, descricao, valor (sempre positivo), tipo (D=débito/saída, C=crédito/entrada), documento? e historico_complementar?.

ConfirmarResponse

Resultado do POST /confirmar (e de /substituir).

CampoTipoNotas
importacao_idintImportação processada.
qtd_criadosintLançamentos persistidos.
qtd_errosintLinhas que falharam.
qtd_ignoradosintLinhas ignoradas por regra de ignorar. Default 0.
qtd_ignorados_valor_zerointLinhas ignoradas por valor zerado. Default 0.
status_finalstr (enum)success | partial | error (entre outros).
data_hora_conclusaodatetime?Momento da conclusão.
qtd_substituidosint?Só em /substituir: lançamentos do lote anterior apagados.
qtd_lucros_geradosintLançamentos de lucro criados automaticamente (regra com sócio). Default 0.
lucros_por_contaLucrosPorContaResumo?Estado do lucro por conta do lote; null quando não se aplica. Só informa - nada é gerado até a chamada de lucros-por-conta/*.

HashDuplicadoInfo

Aviso importacao_existente quando o mesmo arquivo já foi importado para o cliente.

CampoTipoNotas
importacao_id_existenteintImportação original com o mesmo arquivo.
status_existentestr (enum)Status da importação original.
data_hora_criacaodatetimeQuando a original foi criada.

SubstituirImportacaoRequest

Body opcional do POST /substituir (campos descritos no endpoint): confirmar_exportados, data_inicio, data_fim e data_informada.

SubstituicaoInfo

Resposta do GET /substituicao.

CampoTipoNotas
importacao_idintImportação consultada.
tipostr (enum)Tipo da importação.
qtd_lancamentosintLançamentos do lote atual.
qtd_lancamentos_exportadosintQuantos do lote já foram exportados para a Domínio.
reimportavelboolSe é possível importar de novo.
motivo_nao_reimportavelstr?Frase pronta quando reimportavel é false.
klingoSubstituicaoKlingoInfo?Só tipo = "klingo": titulo_relatorio, nome_layout, periodo_original, data_inicio_sugerida, data_fim_sugerida, exige_data_informada e data_informada_sugerida.

AnalisarRegrasRequest

Body do POST /analisar-regras.

CampoTipoObrigatórioNotas
mapeamentoMapeamentoColunassim{ comparacao: int, exportacao: int } (índices 0-based).
campo_destinostr (enum)nãoconta_debito | conta_credito | historico. Quando informado, os duplicados consideram conteúdo e lado da conta; quando null (1ª análise), nenhum duplicado é reportado.
id_estruturaint?nãoEstrutura para recortar o universo de duplicados. Exclusivo com id_klingo_layout.
id_klingo_layoutint?nãoLayout Klingo para recortar o universo de duplicados. Exclusivo com id_estrutura.

AnalisarRegrasResponse

CampoTipoNotas
colunasColunaDetectada[]{ indice, header } das colunas da planilha.
amostraAmostraLinha[]Até 5 linhas { comparacao, exportacao }.
total_linhasintTotal de linhas na planilha.
mapeamento_sugeridoMapeamentoColunasMapeamento inferido.
duplicadosDuplicadoInfo[]{ comparacao, id_regra_existente }.
contas_faltantesstr[]Códigos de exportação sem Conta no cliente.
planos_clientePlanoClienteInfo[]{ id, codigo_dominio, nome }.

ConfirmarRegrasRequest

Body do POST /confirmar-regras.

CampoTipoObrigatórioNotas
mapeamentoMapeamentoColunassimÍndices das colunas comparação/exportação.
campo_destinostr (enum)simconta_debito | conta_credito | historico.
id_cliente_esperadoint?nãoGuard de coerência: se informado e diferente do cliente da importação, retorna 409 e nada é gravado.
campo_comparacaostr (enum)nãoCampo comparado pela condição. Default historico. coluna_relatorio compara uma coluna do relatório Klingo e exige coluna_relatorio e id_klingo_layout.
coluna_relatoriostr?nãoColuna do relatório Klingo (ex.: col3, máx. 50). Obrigatória com campo_comparacao = "coluna_relatorio"; proibida nos demais casos. Vale para o lote inteiro.
modo_comparacaostr (enum)nãoOperador da condição. Default contem.
id_estruturaint?nãoEstrutura opcional para vincular as regras geradas. Exclusivo com id_klingo_layout.
id_klingo_layoutint?nãoLayout Klingo opcional para vincular as regras geradas. Exclusivo com id_estrutura; sem nenhum dos dois, as regras nascem gerais do cliente.
resolucao_duplicadosstr (enum)nãosubstituir | criar | ignorar. Default ignorar.
resolucao_contas_faltantesstr (enum)nãocriar | ignorar. Default ignorar.
id_plano_contas_novasint?nãoPlano onde criar contas novas quando resolucao_contas_faltantes=criar e o cliente tem mais de um plano.

ConfirmarRegrasResponse

CampoTipoNotas
importacao_idintImportação processada.
qtd_criadasintRegras criadas.
qtd_atualizadasintRegras atualizadas.
qtd_ignoradasintRegras ignoradas.
qtd_errosintLinhas com erro.
status_finalstr (enum)Status final da importação.
errosErroLinhaRegra[]{ linha, mensagem }.
data_hora_conclusaodatetime?Momento da conclusão.

Notas

  • Toda resposta segue o envelope { status, message, data } (erros de negócio vêm como { "message": ... } e a validação de entrada como 422 com { "detail": [...] }). A exceção é GET /importacoes/{importacao_id}/arquivo, que devolve o binário do arquivo (FileResponse), e DELETE /importacoes/{importacao_id}, que retorna 204 No Content sem body.
  • O POST /importacoes/upload é multipart/form-data - não envie JSON. Os fluxos de criação de importação por arquivo são este upload e POST /importacoes/iss-retido.
  • Não há execução em segundo plano neste domínio: preview, confirmar, analisar-regras, confirmar-regras e substituir rodam o parser de forma síncrona na própria requisição.
  • Mapeamento de erros de negócio para HTTP: "não encontrado" → 404, "acesso negado" → 403, conflitos de duplicidade/estado (por exemplo importação já processada, cliente divergente em confirmar-regras, lote com lançamento já exportado sem confirmação ou com lucro vinculado) → 409, demais ValueError → 400.
  • Os tipos contas e regras_conversor alimentam fluxos específicos: contas importa plano/contas e regras_conversor alimenta analisar-regras/confirmar-regras, que geram Regras de Lançamento.