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_deletedetransactions_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 nostatement_idinformado para persistir e refletir os novos lançamentos gerados no reprocessamento.Arquitetura Complementar: Os eventos
transaction_deletedetransactions_updateddevem 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.
Comentários
0 comentário
Por favor, entre para comentar.