Guia de Atualização de Transações OpenFinance (em breve)

1. Contexto e Comportamento da Origem

Em cenários excepcionais, algumas instituições financeiras integradas via Open Finance podem deixar de retornar determinadas transações por um período de 1 a 3 dias úteis, disponibilizando-as novamente após esse intervalo.

Quando esse comportamento ocorre na instituição de origem, a transação é temporariamente removida do extrato inicial. Ao ser restabelecida pelo banco, ela é reintroduzida no ecossistema, gerando uma nova transação associada a um novo identificador exclusivo (ID).

Este comportamento é comumente observado em:

• Transações realizadas ou processadas durante finais de semana e feriados;

• Instabilidades e intermitências pontuais na API da instituição financeira de origem.

Embora não seja um cenário de erro alarmante, trata-se de uma particularidade técnica que exige tratamento adequado para garantir a integridade e a consistência dos saldos e extratos.

2. Fluxo de Reprocessamento e Etapas de Resolução

Para mitigar esse comportamento e garantir que as informações reflitam fielmente o estado bancário real, a TecnoSpeed adota um fluxo automatizado de reprocessamento estruturado nas seguintes etapas consecutivas:

• Recepção do Alerta: A TecnoSpeed recebe uma sinalização do parceiro ou da rede Open Finance informando que uma transação previamente listada foi removida na origem.

• Remoção Local e Notificação: O sistema localiza a transação afetada e o extrato (statement) ao qual ela pertencia. A transação antiga é removida da base e um webhook de exclusão (transaction_deleted) é disparado imediatamente ao cliente.

• Agendamento do Reprocessamento: O protocolo desse extrato é inserido em uma fila de reprocessamento diário. Uma vez ao dia, o motor de roativos dentro do período de vigência daquele extrbusca realiza uma nova varredura de movimentos retato.

• Resolução de Inserção: 

  • Caso novas transações sejam localizadas: Elas são vinculadas e inseridas no extrato correspondente, e um webhook de atualização (transactions_updated) é disparado contendo os novos IDs gerados.

  • Caso nenhuma transação seja localizada: O extrato permanece elegível na fila de reprocessamento por até 7 dias corridos, repetindo a busca diária.

• Encerramento do Ciclo: Após o 8º dia, o extrato é removido da fila de busca automática. Caso seja necessária uma nova validação após esse prazo, o parceiro deverá gerar manualmente uma nova consulta sob um novo protocolo.

3. Especificação dos Webhooks e Eventos

Evento: transaction_deleted

Este evento notifica o sistema parceiro de que uma transação disponibilizada anteriormente foi removida na instituição de origem e não compõe mais o extrato atual.

Exemplo de Payload

{
  "event": "transaction_deleted",
  "data": {
    "statement_id": "123",
    "transaction_ids": [
      "456"
    ],
    "message": "Transação removida na instituição financeira de origem. Extrato encaminhado para a fila de reprocessamento."
  }
}

Dicionário de Campos

• event (string): O tipo do evento gerado (transaction_deleted).

• statement_id (string): Identificador exclusivo do extrato impactado pela remoção.

• transaction_ids (array de strings): Lista de IDs das transações que foram excluídas.

• message (string): Mensagem descritiva ou informativa sobre o processamento executado.

Evento: transactions_updated

Este evento notifica que o extrato agendado foi reprocessado com sucesso pelo motor de busca e que as novas transações restabelecidas foram adicionadas à base.

Exemplo de Payload

{
  "event": "transactions_updated",
  "data": {
    "statement_id": "unique-id-do-statement",
    "transaction_ids": [
      "789",
      "790"
    ],
    "message": "Extrato reprocessado com sucesso. Novas transações identificadas e vinculadas."
  }
}

Dicionário de Campos

• event (string): O tipo do evento gerado (transactions_updated).

• statement_id (string): Identificador exclusivo do extrato que sofreu o reprocessamento.

• transaction_ids (array de strings): Lista contendo os novos identificadores das transações inseridas.

• message (string): Mensagem descritiva ou informativa sobre o resultado do reprocessamento.

4. Diretrizes e Recomendações para Integração

Para garantir a melhor experiência de conciliação do lado do seu software, siga as boas práticas abaixo ao consumir nossa API:

• Webhooks: Para receber os webhooks é necessário cadastrar o evento de STATEMENT_OPENFINANCE_UPDATED dentro das nossas APIs para que as notificações de transaction_deleted e transactions_updated.

• Tratamento de Exclusão: Ao recepcionar o evento transaction_deleted, seu sistema deve remover ou invalidar imediatamente as transações sinalizadas no escopo local, evitando que registros fantasmas impactem o fluxo financeiro do cliente.

• Sincronização de Atualizações: Ao recepcionar o evento transactions_updated, realize uma nova rotina de sincronização baseada no statement_id informado para persistir e refletir os novos lançamentos gerados no reprocessamento.

• Arquitetura Complementar: Os eventos transaction_deleted e transactions_updated devem ser interpretados como regras de negócio complementares de um mesmo ciclo de vida. O estado final definitivo do extrato só deve ser consolidado após o encerramento das janelas de reprocessamento.