Open Finance: Financeiro

Complemento do financeiro por cliente de Open Finance (TecnoSpeed): o detalhe de um protocolo e de uma transação, a consulta imediata de um protocolo e os saldos mensais de uma conta (painel do ano, CSV, saldo de abertura, recálculo, fechamento, reabertura e histórico de versões). O resumo, a listagem de transações e protocolos, o CSV de transações, a atualização de saldos e o reprocessamento de período estão na página Open Finance (TecnoSpeed).

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

Base path

/api/v1/tecnospeed/clientes/{cliente_id}/financeiro

A URL completa em produção é https://api.contabilidadealcance.com.br/api/v1/tecnospeed/clientes/{cliente_id}/financeiro. Os caminhos das rotas abaixo começam em /tecnospeed/clientes/{cliente_id}/financeiro.

Escopos e acesso

O escopo é derivado do primeiro segmento depois de /api/v1/ (tecnospeed) e do método HTTP: tecnospeed:read para GET e tecnospeed:write para POST e PUT. Além do escopo, algumas rotas têm exigência adicional:

RotasAcesso
GET .../protocolos/{protocolo_id}, GET .../transacoes/{transacao_id}Só escopo
GET .../saldos, GET .../saldos.csv, GET .../versoesSó escopo (leitura com campos reduzidos para credenciais de integração)
POST .../protocolos/{protocolo_id}/consultarLogin de usuário + permissão adicional
PUT .../ancoras/{ano}, POST .../recalcular, .../fechar, .../reabrirLogin de usuário + permissão adicional

"Login de usuário" significa sessão de usuário; credenciais de integração recebem 403. Sem a permissão adicional, a resposta também é 403.

Regras comuns

  • Cliente inexistente responde 404. Conta ou protocolo fora do escopo do cliente (matriz e filiais) responde 404 com a mesma mensagem de um item inexistente. Contas arquivadas continuam acessíveis (o histórico delas é real).
  • Valores monetários saem como string decimal ("1234.56", "-12.30"), nunca número.
  • Respostas de sucesso usam o envelope { "status": "success", "message": "...", "data": ... }, exceto o CSV, que devolve o arquivo.

Endpoints

GET /tecnospeed/clientes/{cliente_id}/financeiro/protocolos/{protocolo_id}

Detalhe de um protocolo de coleta: os campos da listagem mais a conta, o número de transações vinculadas e o resumo da quarentena por motivo. O nome de quem pediu o protocolo (solicitado_por_nome) só sai para login de usuário.

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
cliente_idintpathsimID do cliente.
protocolo_idintpathsimID do protocolo.

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Operação realizada com sucesso",
  "data": {
    "id": 9101,
    "conta_id": 7,
    "empresa": "Empresa Exemplo Ltda",
    "data_inicio": "2026-10-19",
    "data_fim": "2026-10-19",
    "origem": "fixa",
    "status": "concluido",
    "motivo": null,
    "total_transacoes": 42,
    "transacoes_descartadas": 1,
    "status_tecnospeed": "SUCCESS",
    "agendamento_id": null,
    "criado_em": "2026-10-20T06:00:12",
    "concluido_em": "2026-10-20T06:03:40",
    "unique_id": "b1f0c4a2-7d3e-4c1a-9f10-2a5d6e7f8a90",
    "solicitado_por_nome": null,
    "progresso": null,
    "rodada_id": 301,
    "tentativa_de_id": null,
    "categoria_falha": null,
    "status_http": null,
    "arquivado_em": null,
    "pode_arquivar": true,
    "pode_desarquivar": false,
    "pode_excluir": false,
    "pode_cancelar": false,
    "banco_nome": "Itaú",
    "agencia": "1234",
    "conta_mascarada": "****8765",
    "tentativas_status": 1,
    "transacoes_vinculadas": 42,
    "quarentena": [{ "motivo": "data_invalida", "quantidade": 1 }]
  }
}

progresso traz o andamento da importação quando há uma em curso (fase, paginas_baixadas, total_paginas, transacoes_baixadas, total_previsto, atualizado_em, parado); caso contrário é null. 404 com "Protocolo não encontrado para este cliente.".

Escopo: tecnospeed:read

POST /tecnospeed/clientes/{cliente_id}/financeiro/protocolos/{protocolo_id}/consultar

"Consultar agora": verifica na TecnoSpeed o andamento de um protocolo sem esperar a consulta automática. Se o extrato já está pronto, a importação das transações é feita em segundo plano e a resposta é 202.

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
cliente_idintpathsimID do cliente.
protocolo_idintpathsimID do protocolo.

Request

Sem corpo de requisição.

Response 200 OK ou 202 Accepted

Envelope com o protocolo (mesmos campos de GET .../protocolos/{protocolo_id} sem a conta e a quarentena) acrescido de:

CampoTipoDescrição
importacao_enfileiradabooltrue quando o extrato está pronto e a importação foi iniciada em segundo plano (202).
total_previstointTotal de transações declarado pela TecnoSpeed. Pode ser null.
mensagemstrAviso para a tela (por exemplo, a importação ficou para a próxima rodada automática). Pode ser null.
{
  "status": "success",
  "message": "Operação realizada com sucesso",
  "data": {
    "id": 9104,
    "conta_id": 9,
    "status": "processando",
    "importacao_enfileirada": true,
    "total_previsto": 380,
    "mensagem": null
  }
}

A amostra mostra apenas alguns campos do protocolo. O 200 vale quando o protocolo segue como está (ainda processando, com falha, ou a importação não pôde ser iniciada agora).

Erros:

  • 404 protocolo não encontrado para este cliente.
  • 409 com message.mensagem: consulta já em andamento para o protocolo, ou protocolo já processado.
  • 422 protocolo sem identificador na TecnoSpeed (não há o que consultar).
  • 429 com message { "mensagem", "proxima_em" }: o protocolo foi consultado há pouco.
  • 503 integração TecnoSpeed não configurada.
  • Pode responder 202 fora do envelope, { "enfileirado": true, "acao_id": "...", "mensagem": "..." }, quando a ação é colocada em fila; o resultado chega por notificação.

Escopo: tecnospeed:write. Exige login de usuário (sessão); credenciais de integração recebem 403. Restrita a usuários com permissão adicional; sem ela, a resposta é 403.

GET /tecnospeed/clientes/{cliente_id}/financeiro/transacoes/{transacao_id}

Detalhe de uma transação, incluindo o item original recebido da TecnoSpeed (dados_tecnospeed), com CPF/CNPJ mascarados e sem campos de credencial.

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
cliente_idintpathsimID do cliente.
transacao_idintpathsimID da transação.

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Operação realizada com sucesso",
  "data": {
    "id": 99012,
    "conta_id": 7,
    "empresa": "Empresa Exemplo Ltda",
    "conta": "Banco Itaú ****8765",
    "banco_nome": "Itaú",
    "agencia": "1234",
    "conta_mascarada": "****8765",
    "data": "2026-10-10",
    "valor": "1500.00",
    "natureza": "C",
    "descricao": "PIX RECEBIDO",
    "categoria": null,
    "fitid": "20261010001",
    "transaction_id": "tx-8f3a21",
    "contraparte_nome": "Cliente Exemplo Ltda",
    "contraparte_documento_mascarado": "98.***.***/0001-10",
    "protocolo_id": 9101,
    "protocolo_data_inicio": "2026-10-10",
    "protocolo_data_fim": "2026-10-10",
    "criado_em": "2026-10-11T06:01:05",
    "dados_tecnospeed": {
      "description": "PIX RECEBIDO",
      "amount": 1500.0
    }
  }
}

natureza é C (crédito) ou D (débito). 404 com "Transação não encontrada para este cliente.".

Escopo: tecnospeed:read

GET /tecnospeed/clientes/{cliente_id}/financeiro/saldos

Painel de saldos mensais de uma conta no ano: o saldo de abertura (âncora), os 12 meses com saldo inicial, créditos, débitos e saldo final, e o resumo do ano. A consulta recalcula e grava os meses ainda abertos; com credenciais de integração a leitura é somente leitura (sem gravar o recálculo, sem nomes de pessoas e sem a observação da âncora).

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
cliente_idintpathsimID do cliente.
conta_idintquerysimID da conta (>= 1).
anointquerynãoAno (2000..2100). Padrão: ano corrente (São Paulo).

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Operação realizada com sucesso",
  "data": {
    "conta_id": 7,
    "ano": 2026,
    "ancora": {
      "id": 3,
      "ano": 2026,
      "mes": 1,
      "saldo_abertura": "10000.00",
      "origem": "manual",
      "observacao": "Saldo do extrato de dezembro",
      "informado_por_nome": "Maria Exemplo",
      "criado_em": "2026-01-05T10:00:00"
    },
    "ancora_sugerida": null,
    "saldo_real": { "saldo": "15230.45", "saldo_em": "2026-10-14T08:00:00" },
    "fechamento_auto_dias": 5,
    "meses": [
      {
        "ano": 2026,
        "mes": 9,
        "competencia": "2026-09",
        "saldo_inicial": "12000.00",
        "total_creditos": "8000.00",
        "total_debitos": "4769.55",
        "saldo_final": "15230.45",
        "qtd_transacoes": 120,
        "status": "fechado",
        "versao": 2,
        "cobertura_completa": true,
        "descartes_pendentes": 0,
        "divergente": false,
        "divergencia": null,
        "fechado_em": "2026-10-06T06:30:00",
        "fechado_por_nome": null,
        "fechamento_automatico": true,
        "reaberto_manual": false,
        "pode_fechar": false,
        "motivo_bloqueio": "Mês já fechado."
      }
    ],
    "ano_resumo": {
      "saldo_inicial": "10000.00",
      "total_creditos": "70000.00",
      "total_debitos": "64769.55",
      "saldo_final": "15230.45",
      "parcial": true,
      "ultimo_mes_com_dados": 10
    }
  }
}
  • meses[].status: aberto, fechado, sem_ancora ou futuro. Nos meses sem_ancora e futuro, os valores e qtd_transacoes vêm null.
  • ancora_sugerida (mes, saldo, base_saldo_real, base_em, aviso) sugere um saldo de abertura quando ainda não há âncora; é null quando não há sugestão.
  • divergencia indica que as transações de hoje diferem do mês já fechado (creditos, debitos, qtd, saldo_final_recalculado, detectada_em).
  • pode_fechar e motivo_bloqueio dizem se o mês pode ser fechado agora e, se não, por quê.
  • fechamento_automatico: true indica mês fechado automaticamente; reaberto_manual: true indica mês reaberto manualmente, que só volta a fechar pela rota de fechamento.

Erros: 404 cliente ou conta não encontrada para este cliente; 422 parâmetro fora do formato.

Escopo: tecnospeed:read

GET /tecnospeed/clientes/{cliente_id}/financeiro/saldos.csv

O painel do ano de uma conta em CSV: uma linha por mês (janeiro a dezembro) mais a linha Total.

Parâmetros

Os mesmos de GET .../financeiro/saldos (conta_id obrigatório e ano opcional).

Request

Sem corpo de requisição.

Response 200 OK

Arquivo CSV (não é envelope JSON): Content-Type: text/csv; charset=utf-8, separador ;, BOM UTF-8, vírgula decimal e quebra de linha \r\n. Content-Disposition: attachment; filename="saldos_{cliente_id}_conta_{conta_id}_{ano}.csv". Colunas: conta, cnpj, ano, mes, competencia, status, versao, saldo_inicial, total_creditos, total_debitos, saldo_final, qtd_transacoes. Valor nulo sai vazio, e texto que começa com =, +, -, @, TAB ou CR é prefixado com ' (proteção contra injeção de fórmula).

Escopo: tecnospeed:read

GET /tecnospeed/clientes/{cliente_id}/financeiro/saldos/{conta_id}/{ano}/{mes}/versoes

Histórico de versões de um mês: cada fechamento, reabertura e recálculo gera uma versão arquivada, da mais recente para a mais antiga.

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
cliente_idintpathsimID do cliente.
conta_idintpathsimID da conta.
anointpathsimAno (2000..2100).
mesintpathsimMês (1..12).

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Operação realizada com sucesso",
  "data": [
    {
      "versao": 2,
      "motivo": "fechamento_automatico",
      "justificativa": null,
      "status": "fechado",
      "saldo_inicial": "12000.00",
      "total_creditos": "8000.00",
      "total_debitos": "4769.55",
      "saldo_final": "15230.45",
      "qtd_transacoes": 120,
      "hash_transacoes": "9f2c1d5e...",
      "criado_por_nome": null,
      "criado_em": "2026-10-06T06:30:00"
    }
  ]
}

motivo é fechamento, fechamento_automatico, reabertura ou recalculo. justificativa e criado_por_nome só saem para login de usuário; criado_por_nome também é null no fechamento automático.

Escopo: tecnospeed:read

PUT /tecnospeed/clientes/{cliente_id}/financeiro/saldos/{conta_id}/ancoras/{ano}

Define o saldo de abertura (âncora) da conta no ano, a partir do qual os saldos mensais são calculados. Substitui a âncora do ano e recalcula os meses. Não é possível alterá-la se houver mês fechado a partir do mês da âncora no ano: reabra-o antes.

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
cliente_idintpathsimID do cliente.
conta_idintpathsimID da conta.
anointpathsimAno (2000..2100).

Corpo (campos desconhecidos dão 422):

CampoTipoObrigatórioDescrição
mesintnãoMês do saldo de abertura (1..12). Padrão 1.
saldo_aberturastringsimDecimal em texto, com ponto e até 2 casas ("-1234.56"), até 13 dígitos inteiros. Número JSON não é aceito.
observacaostringsimDe 3 a 500 caracteres (sem os espaços das pontas).

Request

{
  "mes": 1,
  "saldo_abertura": "10000.00",
  "observacao": "Saldo do extrato de dezembro"
}

Response 200 OK

Envelope com o painel do ano (mesmo formato de GET .../financeiro/saldos).

Erros: 404 conta não encontrada para este cliente; 409 mês fechado impede a alteração (message.mensagem: "Há mês fechado em MM/AAAA ou depois neste ano: reabra-o antes de alterar o saldo de abertura."); 422 corpo inválido.

Escopo: tecnospeed:write. Exige login de usuário (sessão); credenciais de integração recebem 403. Restrita a usuários com permissão adicional; sem ela, a resposta é 403.

POST /tecnospeed/clientes/{cliente_id}/financeiro/saldos/{conta_id}/recalcular

Recalcula os saldos mensais ainda abertos da conta no ano.

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
cliente_idintpathsimID do cliente.
conta_idintpathsimID da conta.

Corpo (campos desconhecidos dão 422):

CampoTipoObrigatórioDescrição
anointsimAno (2000..2100).

Request

{
  "ano": 2026
}

Response 200 OK

Envelope com o painel do ano (mesmo formato de GET .../financeiro/saldos). 404 conta não encontrada para este cliente.

Escopo: tecnospeed:write. Exige login de usuário (sessão); credenciais de integração recebem 403. Restrita a usuários com permissão adicional; sem ela, a resposta é 403.

POST /tecnospeed/clientes/{cliente_id}/financeiro/saldos/{conta_id}/{ano}/{mes}/fechar

Fecha o saldo de um mês. O mês precisa ter terminado, ter saldo de abertura, cobertura completa de extratos e o mês anterior fechado.

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
cliente_idintpathsimID do cliente.
conta_idintpathsimID da conta.
anointpathsimAno (2000..2100).
mesintpathsimMês (1..12).

Request

Sem corpo de requisição.

Response 200 OK

Envelope com o painel do ano (mesmo formato de GET .../financeiro/saldos), com o mês em status: "fechado".

Erros: 404 conta não encontrada para este cliente; 409 mês não elegível, com message.mensagem explicando o motivo ("Mês já fechado.", "Mês futuro.", "O mês ainda não terminou.", "Sem saldo de abertura (âncora) para este mês: informe a âncora.", "Extratos incompletos no mês: há dias sem protocolo concluído." ou "Feche o mês anterior primeiro.").

Escopo: tecnospeed:write. Exige login de usuário (sessão); credenciais de integração recebem 403. Restrita a usuários com permissão adicional; sem ela, a resposta é 403.

POST /tecnospeed/clientes/{cliente_id}/financeiro/saldos/{conta_id}/{ano}/{mes}/reabrir

Reabre um mês fechado. Os meses fechados seguintes também são reabertos, e cada um gera uma versão arquivada com a justificativa. Os meses reabertos só voltam a fechar pela rota de fechamento.

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
cliente_idintpathsimID do cliente.
conta_idintpathsimID da conta.
anointpathsimAno (2000..2100).
mesintpathsimMês (1..12).

Corpo (campos desconhecidos dão 422):

CampoTipoObrigatórioDescrição
justificativastringsimDe 10 a 500 caracteres (sem os espaços das pontas).

Request

{
  "justificativa": "Extrato complementar recebido do banco"
}

Response 200 OK

Envelope com o painel do ano (mesmo formato de GET .../financeiro/saldos).

Erros: 404 conta não encontrada para este cliente; 409 com message.mensagem "Este mês não está fechado."; 422 corpo inválido.

Escopo: tecnospeed:write. Exige login de usuário (sessão); credenciais de integração recebem 403. Restrita a usuários com permissão adicional; sem ela, a resposta é 403.

Páginas relacionadas