Reprocessamento e idempotência em integrações Datasul: como evitar duplicidades
Falhas fazem parte da realidade de qualquer integração entre sistemas.
Uma API pode ficar indisponível, uma conexão pode cair, uma mensagem pode ser rejeitada ou um sistema pode processar uma transação sem conseguir devolver a confirmação esperada.
O problema não é apenas saber como tentar novamente. É garantir que uma nova tentativa não produza documentos, movimentos ou efeitos duplicados.
Por isso, reprocessamento e idempotência precisam ser pensados desde o desenho da integração.
Reprocessar não é simplesmente enviar novamente
Quando uma transação falha, reenviar exatamente a mesma informação pode parecer a solução mais simples.
Mas antes de fazer isso, a integração precisa saber se a operação anterior realmente falhou ou se foi concluída e apenas a resposta não chegou ao sistema de origem.
Sem esse controle, uma retentativa pode criar duplicidades.
O que é idempotência?
Em uma integração, idempotência é o princípio de permitir que uma mesma operação seja recebida mais de uma vez sem produzir efeitos adicionais indesejados.
Na prática, isso significa reconhecer que determinado evento ou transação já foi processado e evitar sua execução novamente quando o resultado já existe.
A forma de implementar esse comportamento depende da arquitetura e do processo envolvido.
Nem toda operação é naturalmente idempotente
Consultar uma informação tende a ser diferente de criar um documento ou executar uma movimentação.
Uma operação de criação pode gerar um novo registro a cada chamada, enquanto uma consulta normalmente não produz alteração de estado.
Por isso, o desenho da integração precisa considerar o efeito real de cada operação.
Utilize identificadores de transação
Uma forma comum de reconhecer uma tentativa repetida é associar a operação a um identificador único.
Esse identificador pode representar um documento, evento ou transação de negócio.
Ao receber novamente a mesma referência, o sistema pode verificar se aquela operação já foi processada antes de executar uma nova ação.
O formato e a origem desse identificador devem ser definidos de acordo com a arquitetura utilizada.
Registre o estado do processamento
Uma transação pode possuir diferentes estados durante sua execução.
Por exemplo:
- recebida;
- em processamento;
- concluída;
- rejeitada;
- aguardando nova tentativa;
- erro técnico;
- erro de negócio.
Registrar estados ajuda a decidir se a operação pode ser processada novamente e também melhora a rastreabilidade.
Diferencie erro técnico de erro de negócio
Uma indisponibilidade temporária de rede possui natureza diferente de um documento rejeitado porque está com informação inválida.
No primeiro caso, uma nova tentativa pode ser apropriada.
No segundo, repetir a mesma mensagem sem corrigir a causa provavelmente produzirá a mesma rejeição.
Essa distinção ajuda a evitar retentativas inúteis e excesso de processamento.
Retentativas automáticas precisam de limite
Quando o erro é temporário, a arquitetura pode prever novas tentativas automáticas.
Mas uma integração não deve permanecer tentando indefinidamente sem controle.
É importante definir quantidade de tentativas, intervalo e condição para encaminhar a transação para tratamento manual.
Esses parâmetros dependem da criticidade e das características do processo.
Backoff ajuda a evitar sobrecarga
Quando um serviço externo está indisponível, repetir chamadas em alta frequência pode aumentar ainda mais o problema.
Uma estratégia de espera progressiva entre as tentativas pode reduzir a pressão sobre o serviço e aumentar a chance de recuperação.
A estratégia específica deve considerar o ambiente e o tipo de integração.
Reprocessamento manual também precisa de controle
Algumas situações exigem análise humana antes da nova tentativa.
Uma interface de reprocessamento deve permitir identificar a transação, entender o motivo da falha e executar novamente somente quando a condição estiver corrigida.
Também é importante registrar quem realizou a ação e quando ela ocorreu, principalmente em processos críticos.
Evite transformar o reprocessamento em atalho
Se uma transação falha frequentemente e a solução operacional é simplesmente clicar em reprocessar, existe um problema que precisa ser investigado.
Reprocessamento é um mecanismo de recuperação, não substituto para correção da causa raiz.
O destino também precisa participar do controle
Não basta o sistema de origem registrar que uma mensagem foi enviada.
O destino precisa responder de forma que permita determinar se a operação foi aceita, rejeitada ou já havia sido processada.
Quando não existe essa clareza, a integração pode ficar sem saber se deve tentar novamente ou aguardar tratamento.
Confirmação de processamento é diferente de confirmação de recebimento
Uma mensagem pode chegar ao sistema de destino e ainda assim não concluir o processo de negócio.
Por isso, em algumas arquiteturas é importante distinguir:
- mensagem recebida;
- mensagem validada;
- operação executada;
- resultado confirmado.
Essa separação melhora o controle sobre processos assíncronos.
Logs precisam permitir reconstruir a transação
Quando ocorre uma duplicidade ou falha de processamento, a equipe precisa reconstruir o caminho da transação.
Informações úteis podem incluir:
- identificador da transação;
- data e hora;
- origem;
- destino;
- tipo de operação;
- estado;
- tentativas;
- retorno recebido;
- mensagem de erro.
Logs não precisam expor dados sensíveis desnecessariamente. A rastreabilidade deve respeitar as regras de segurança do ambiente.
Filas mudam a forma de tratar erros
Em arquiteturas assíncronas, mensagens podem permanecer aguardando processamento enquanto os sistemas continuam operando.
Nesse cenário, é importante controlar ordem, repetição, falhas e mensagens que não conseguem ser processadas após várias tentativas.
A tecnologia utilizada pode variar, mas o princípio de rastrear o estado continua sendo importante.
Teste cenários de duplicidade
Durante a homologação, não teste somente o caminho em que a integração funciona na primeira tentativa.
Também vale considerar cenários como:
- mesma mensagem enviada duas vezes;
- timeout depois do processamento;
- retorno perdido;
- falha antes da confirmação;
- nova tentativa automática;
- reprocessamento manual;
- destino indisponível;
- mensagem rejeitada.
O princípio vale para diferentes integrações Datasul
Esses cuidados podem aparecer em integrações com WMS, sistemas de produção, portais, aplicações fiscais, plataformas comerciais e outros sistemas satélites.
Cada processo possui regras próprias e precisa ser analisado individualmente.
Para cenários de logística e recebimento, veja também nosso artigo sobre divergências na integração entre Datasul e WMS.
Progress OpenEdge e serviços específicos
Em alguns ambientes Datasul, integrações ou componentes específicos podem envolver desenvolvimento em Progress OpenEdge/ABL ou serviços construídos para atender necessidades particulares.
A tecnologia escolhida não elimina a necessidade de controle de transações, erros e reprocessamento.
Conheça nosso serviço de Desenvolvimento Progress OpenEdge e ABL para Datasul.
Precisa estruturar integrações com maior rastreabilidade?
A DATA IT atua no desenho, desenvolvimento, integração, tratamento de erros e homologação de soluções conectadas ao Datasul.
Conheça nosso serviço de Integrações Datasul e APIs ou fale com nosso time.