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}/financeiroA 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:
| Rotas | Acesso |
|---|---|
GET .../protocolos/{protocolo_id}, GET .../transacoes/{transacao_id} | Só escopo |
GET .../saldos, GET .../saldos.csv, GET .../versoes | Só escopo (leitura com campos reduzidos para credenciais de integração) |
POST .../protocolos/{protocolo_id}/consultar | Login de usuário + permissão adicional |
PUT .../ancoras/{ano}, POST .../recalcular, .../fechar, .../reabrir | Login 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) responde404com 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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
cliente_id | int | path | sim | ID do cliente. |
protocolo_id | int | path | sim | ID 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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
cliente_id | int | path | sim | ID do cliente. |
protocolo_id | int | path | sim | ID 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:
| Campo | Tipo | Descrição |
|---|---|---|
importacao_enfileirada | bool | true quando o extrato está pronto e a importação foi iniciada em segundo plano (202). |
total_previsto | int | Total de transações declarado pela TecnoSpeed. Pode ser null. |
mensagem | str | Aviso 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:
404protocolo não encontrado para este cliente.409commessage.mensagem: consulta já em andamento para o protocolo, ou protocolo já processado.422protocolo sem identificador na TecnoSpeed (não há o que consultar).429commessage{ "mensagem", "proxima_em" }: o protocolo foi consultado há pouco.503integração TecnoSpeed não configurada.- Pode responder
202fora 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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
cliente_id | int | path | sim | ID do cliente. |
transacao_id | int | path | sim | ID 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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
cliente_id | int | path | sim | ID do cliente. |
conta_id | int | query | sim | ID da conta (>= 1). |
ano | int | query | não | Ano (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_ancoraoufuturo. Nos mesessem_ancoraefuturo, os valores eqtd_transacoesvêmnull.ancora_sugerida(mes,saldo,base_saldo_real,base_em,aviso) sugere um saldo de abertura quando ainda não há âncora; énullquando não há sugestão.divergenciaindica que as transações de hoje diferem do mês já fechado (creditos,debitos,qtd,saldo_final_recalculado,detectada_em).pode_fecharemotivo_bloqueiodizem se o mês pode ser fechado agora e, se não, por quê.fechamento_automatico: trueindica mês fechado automaticamente;reaberto_manual: trueindica 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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
cliente_id | int | path | sim | ID do cliente. |
conta_id | int | path | sim | ID da conta. |
ano | int | path | sim | Ano (2000..2100). |
mes | int | path | sim | Mê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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
cliente_id | int | path | sim | ID do cliente. |
conta_id | int | path | sim | ID da conta. |
ano | int | path | sim | Ano (2000..2100). |
Corpo (campos desconhecidos dão 422):
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
mes | int | não | Mês do saldo de abertura (1..12). Padrão 1. |
saldo_abertura | string | sim | Decimal em texto, com ponto e até 2 casas ("-1234.56"), até 13 dígitos inteiros. Número JSON não é aceito. |
observacao | string | sim | De 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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
cliente_id | int | path | sim | ID do cliente. |
conta_id | int | path | sim | ID da conta. |
Corpo (campos desconhecidos dão 422):
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
ano | int | sim | Ano (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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
cliente_id | int | path | sim | ID do cliente. |
conta_id | int | path | sim | ID da conta. |
ano | int | path | sim | Ano (2000..2100). |
mes | int | path | sim | Mê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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
cliente_id | int | path | sim | ID do cliente. |
conta_id | int | path | sim | ID da conta. |
ano | int | path | sim | Ano (2000..2100). |
mes | int | path | sim | Mês (1..12). |
Corpo (campos desconhecidos dão 422):
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
justificativa | string | sim | De 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
- Open Finance (TecnoSpeed) - pagador, contas, consentimento, agendamentos, resumo, transações e protocolos.
- Open Finance: Central de buscas - rodadas, fila e gestão de protocolos de todos os clientes.