Importações: Open Finance

Importação, no siscontabil, das transações bancárias capturadas via Open Finance (TecnoSpeed) como lançamentos contábeis. Cada transação passa pelo mesmo motor da importação de OFX: primeiro as regras de ignorar, depois as regras de classificação (padrões do banco primeiro, regras do cliente/estrutura depois). A captura das transações é feita pelo domínio Open Finance (TecnoSpeed); aqui só se lê o que já foi capturado e se grava a importação.

Base path

/api/v1/importacoes/open-finance

A URL completa em produção é https://api.contabilidadealcance.com.br/api/v1/importacoes/open-finance.

Ordem de montagem

Este router é registrado antes do router de /importacoes. Lá existe /{importacao_id} (inteiro), que capturaria /open-finance/painel e responderia 422 se a ordem fosse a inversa.

Escopos

O router usa o mesmo guard das rotas de /importacoes (_SCOPE_DEP): escopo derivado do path mais o gate de senha provisória. O escopo é derivado do primeiro segmento depois de /api/v1/, então o recurso é importacoes (e não open_finance). Todas as rotas aceitam qualquer funcionário autenticado, inclusive por API Key - não há guard de perfil adicional.

Escopo	Operações permitidas
`importacoes:read`	`GET /painel`, `GET /{id_cliente}/contas`
`importacoes:write`	`PUT /{id_cliente}/contas/{conta_id}/mapeamento`, `POST /preview`, `POST /confirmar`

POST /preview exige escopo de escrita

O POST /preview não grava nada, mas como o escopo é derivado do método HTTP, ele exige importacoes:write.

Regras de negócio

Só matriz. O id_cliente precisa ser uma matriz PJ (senão 422 "A importação Open Finance é feita pela matriz."). O escopo da importação é a matriz mais as filiais da mesma raiz de CNPJ, e a importação é sempre gravada na matriz: a transação de uma filial é lançada na matriz.
Conta arquivada fica fora da listagem, do mapeamento e da seleção (422 se pedida). As transações dela já importadas continuam valendo. Conta só inativa (pagador desativado ou desconectada) continua listada e importável.
Pendente = transação sem vínculo com uma importação. Toda transação processada por um lote (lançada, ignorada por regra ou com valor zerado) ganha vínculo e deixa de ser pendente. Excluir a importação pelo DELETE /importacoes/{importacao_id} libera as transações.
Mapeamento obrigatório. A conta precisa de um de-para para um banco do siscontabil (e, opcionalmente, uma estrutura) antes da prévia e da confirmação.
Período de no máximo 366 dias, com início não posterior ao fim (422).

Erros

Status	Quando
`404`	Cliente inexistente, ou conta inexistente ou de outra raiz de CNPJ (`"Conta não encontrada."`).
`409`	Transações já importadas por outra importação (corrida), ou outra violação de integridade ao gravar (banco, estrutura ou conta mudaram durante a operação).
`422`	Cliente não é matriz, conta arquivada, conta sem mapeamento, banco/estrutura inválidos, nenhuma transação pendente no período, período inválido ou corpo inválido (campos desconhecidos também dão `422`).

Endpoints

`GET /importacoes/open-finance/painel`

Uso do Open Finance por cliente: clientes com ao menos uma conta ativa, com a contagem de contas ativas e autorizadas, a última captura e as transações pendentes (das contas não arquivadas).

Parâmetros

Este endpoint não recebe parâmetros de rota ou query.

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Painel Open Finance recuperado com sucesso",
  "data": [
    {
      "cliente_id": 487,
      "empresa": "Empresa Exemplo Ltda",
      "id_cliente_importacao": 487,
      "contas_ativas": 2,
      "contas_autorizadas": 1,
      "ultima_captura": "2026-10-15T06:05:00",
      "transacoes_pendentes": 34
    }
  ]
}

Escopo: importacoes:read

`GET /importacoes/open-finance/{id_cliente}/contas`

Contas Open Finance importáveis do cliente (matriz e filiais), inativas inclusive e sem as arquivadas. Cada conta vem com o mesmo formato do financeiro da TecnoSpeed, mais o mapeamento (ou null) e o resumo das transações pendentes.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`id_cliente`	`int`	path	sim	ID do cliente (precisa ser matriz).

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Contas Open Finance recuperadas com sucesso",
  "data": [
    {
      "id": 7,
      "cliente_id": 487,
      "empresa": "Empresa Exemplo Ltda",
      "bank_code": "341",
      "banco_nome": "Banco Itaú",
      "agencia": "1234",
      "conta_mascarada": "****8765",
      "consentimento_status": "ativo",
      "ativo": true,
      "inativada_por": null,
      "removida_em": null,
      "saldo": "15230.45",
      "saldo_em": "2026-10-15T06:05:00",
      "mapeamento": {
        "id_cliente": 487,
        "conta_tecnospeed_id": 7,
        "id_banco": 12,
        "id_estrutura": null,
        "atualizado_em": "2026-10-15T10:30:00"
      },
      "pendentes": {
        "quantidade": 34,
        "data_inicio": "2026-10-01",
        "data_fim": "2026-10-14"
      }
    }
  ]
}

Escopo: importacoes:read

`PUT /importacoes/open-finance/{id_cliente}/contas/{conta_id}/mapeamento`

Cria ou atualiza o de-para da conta Open Finance para um banco do siscontabil (e, opcionalmente, uma estrutura). O id_cliente gravado é sempre a matriz. O banco precisa existir e estar ativo; a estrutura, se informada, precisa estar ativa e ser global ou da própria matriz (senão 422).

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`id_cliente`	`int`	path	sim	ID do cliente (precisa ser matriz).
`conta_id`	`int`	path	sim	ID da conta Open Finance.

Corpo MapeamentoBody (campos desconhecidos dão 422).

Request

{
  "id_banco": 12,
  "id_estrutura": null
}

Response 200 OK

{
  "status": "success",
  "message": "Conta mapeada",
  "data": {
    "id_cliente": 487,
    "conta_tecnospeed_id": 7,
    "id_banco": 12,
    "id_estrutura": null,
    "atualizado_em": "2026-10-15T10:30:00"
  }
}

Escopo: importacoes:write

`POST /importacoes/open-finance/preview`

Prévia da importação: mostra o que o confirmar gravaria para as transações pendentes da conta no período. Não grava nada. As transações vêm separadas em lançamentos com regra, sem regra (nasceriam regra_pendente), ignoradas por regra e com valor zerado.

Parâmetros

Sem parâmetros de rota ou query. Corpo PeriodoBody.

Request

{
  "id_cliente": 487,
  "conta_id": 7,
  "inicio": "2026-10-01",
  "fim": "2026-10-14"
}

Response 200 OK

{
  "status": "success",
  "message": "3 transações pendentes no período",
  "data": {
    "id_cliente": 487,
    "conta_id": 7,
    "id_banco": 12,
    "id_estrutura": null,
    "inicio": "2026-10-01",
    "fim": "2026-10-14",
    "total_pendentes": 3,
    "lancamentos": [
      {
        "transacao_id": 9001,
        "data": "2026-10-14",
        "historico": "PIX RECEBIDO CLIENTE EXEMPLO",
        "valor": "1500.00",
        "natureza": "C",
        "numero_documento": null,
        "id_conta_debito": 101,
        "id_conta_credito": 202,
        "regras_aplicadas": ["Recebimento PIX"],
        "status_previsto": "sucesso"
      }
    ],
    "sem_regra": [
      {
        "transacao_id": 9002,
        "data": "2026-10-13",
        "historico": "TED ENVIADA",
        "valor": "800.00",
        "natureza": "D",
        "numero_documento": null,
        "id_conta_debito": null,
        "id_conta_credito": 101,
        "regras_aplicadas": [],
        "status_previsto": "regra_pendente"
      }
    ],
    "ignoradas": [
      {
        "transacao_id": 9003,
        "data": "2026-10-12",
        "historico": "APLICACAO AUTOMATICA",
        "valor": "200.00",
        "natureza": "D",
        "regra_id": 5,
        "regra_nome": "Ignorar aplicação automática"
      }
    ],
    "qtd_valor_zero": 0
  }
}

Escopo: importacoes:write

`POST /importacoes/open-finance/confirmar`

Importa as transações pendentes da conta no período como lançamentos contábeis. Grava a importação (tipo open_finance, sempre na matriz), os lançamentos e os vínculos de todas as transações processadas numa única transação de banco. status_final é error quando nenhum lançamento é criado (todas ignoradas ou zeradas) e success nos outros casos. Sem transação pendente no período, 422; corrida com outra importação das mesmas transações, 409.

Parâmetros

Sem parâmetros de rota ou query. Corpo PeriodoBody (o mesmo do preview).

Request

{
  "id_cliente": 487,
  "conta_id": 7,
  "inicio": "2026-10-01",
  "fim": "2026-10-14"
}

Response 201 Created

{
  "status": "success",
  "message": "Importação Open Finance concluída: 2 lançamentos criados (status=success)",
  "data": {
    "importacao_id": 1520,
    "status_final": "success",
    "qtd_criados": 2,
    "qtd_ignorados": 1,
    "qtd_ignorados_valor_zero": 0,
    "qtd_transacoes_vinculadas": 3,
    "data_hora_conclusao": "2026-10-15T10:35:00"
  }
}

Escopo: importacoes:write

Schemas

`MapeamentoBody`

Campo	Tipo	Obrigatório	Observações
`id_banco`	`int`	sim	Banco do siscontabil (`> 0`), ativo.
`id_estrutura`	`int`	não	Estrutura (`> 0`), ativa, global ou da matriz.

`MapeamentoRead`

Campo	Tipo	Observações
`id_cliente`	`int`	Sempre a matriz.
`conta_tecnospeed_id`	`int`	ID da conta Open Finance.
`id_banco`	`int`	Banco mapeado.
`id_estrutura`	`int`	Pode ser `null`.
`atualizado_em`	`datetime`	Pode ser `null`.

`ContaImportavel`

Os campos de ContaFinanceiroResumo (veja Open Finance (TecnoSpeed)) - id, cliente_id, empresa, bank_code, banco_nome, agencia, conta_mascarada, consentimento_status, ativo, inativada_por, removida_em, saldo, saldo_em - mais:

Campo	Tipo	Observações
`mapeamento`	`MapeamentoRead`	`null` quando a conta ainda não foi mapeada.
`pendentes`	`object`	`quantidade`, `data_inicio` e `data_fim` das transações sem vínculo.

`PeriodoBody`

Corpo de /preview e /confirmar. Campos desconhecidos dão 422.

Campo	Tipo	Obrigatório	Observações
`id_cliente`	`int`	sim	`> 0`; precisa ser matriz.
`conta_id`	`int`	sim	`> 0`; conta do escopo da matriz.
`inicio`	`date`	sim	Início do período.
`fim`	`date`	sim	Fim do período (até 366 dias).

`PreviewOpenFinance`

Campo	Tipo	Observações
`id_cliente`	`int`	Cliente informado.
`conta_id`	`int`	Conta informada.
`id_banco`	`int`	Banco do mapeamento.
`id_estrutura`	`int`	Estrutura do mapeamento. Pode ser `null`.
`inicio`, `fim`	`date`	Período.
`total_pendentes`	`int`	Transações pendentes no período.
`lancamentos`	`list[LancamentoProposto]`	Casaram ao menos uma regra.
`sem_regra`	`list[LancamentoProposto]`	Nenhuma regra casou: nascem `regra_pendente`.
`ignoradas`	`list[TransacaoIgnorada]`	Casaram uma regra de ignorar: não viram lançamento.
`qtd_valor_zero`	`int`	Valor zerado (módulo menor que 0,005): não vira lançamento.

`LancamentoProposto`

Campo	Tipo	Observações
`transacao_id`	`int`	Transação de origem.
`data`	`date`	Data.
`historico`	`str`	Histórico do lançamento.
`valor`	`decimal`	String no JSON.
`natureza`	`str`	`C` ou `D`.
`numero_documento`	`str`	Pode ser `null`.
`id_conta_debito`	`int`	Pode ser `null`.
`id_conta_credito`	`int`	Pode ser `null`.
`regras_aplicadas`	`list[str]`	Nomes das regras que casaram, na ordem de avaliação. Vazio = sem regra.
`status_previsto`	`str`	`sucesso` (exige débito e crédito) ou `regra_pendente`.

`TransacaoIgnorada`

Campo	Tipo	Observações
`transacao_id`	`int`	Transação de origem.
`data`	`date`	Data.
`historico`	`str`	Histórico.
`valor`	`decimal`	String no JSON.
`natureza`	`str`	`C` ou `D`.
`regra_id`	`int`	Regra de ignorar que casou.
`regra_nome`	`str`	Nome da regra.

`ConfirmarOpenFinanceResponse`

Campo	Tipo	Observações
`importacao_id`	`int`	ID da importação criada.
`status_final`	`str`	`success`, `partial` ou `error` (hoje a rota só produz `success` e `error`).
`qtd_criados`	`int`	Lançamentos criados.
`qtd_ignorados`	`int`	Transações ignoradas por regra.
`qtd_ignorados_valor_zero`	`int`	Transações com valor zerado.
`qtd_transacoes_vinculadas`	`int`	Todas as transações processadas (lançadas, ignoradas e zeradas).
`data_hora_conclusao`	`datetime`	Pode ser `null`.

`PainelCliente`

Campo	Tipo	Observações
`cliente_id`	`int`	Cliente dono das contas.
`empresa`	`str`	Razão social.
`id_cliente_importacao`	`int`	Matriz pela qual a importação é feita (o próprio cliente, se matriz; a matriz da mesma raiz, se filial e ela estiver cadastrada; senão `null`).
`contas_ativas`	`int`	Contas ativas.
`contas_autorizadas`	`int`	Contas ativas com consentimento `ativo`.
`ultima_captura`	`datetime`	Pode ser `null`.
`transacoes_pendentes`	`int`	Transações sem vínculo nas contas não arquivadas.

Notas

Excluir uma importação open_finance com lançamento já exportado para a Domínio exige confirmar_exportados=true no DELETE /importacoes/{importacao_id} (sem a flag, 409 importacao_com_exportados).
Uma conta com transações já lançadas por esta importação não pode ser expurgada no domínio TecnoSpeed (409).