Pedidos duplicados ao usar a API: causas e proteção

Por que as duplicatas aparecem após uma única ação

O dono do painel pode clicar no botão uma vez e ver vários pedidos idênticos: seguidores, visualizações, reações ou outro serviço. Normalmente o problema não está no clique em si, mas na cadeia entre o cliente, a API, o banco de dados e o fornecedor.

Do ponto de vista do servidor, "uma requisição" nem sempre é uma só. O cliente pode não ter recebido a resposta, reenviado o envio, e a primeira operação já ter sido salva. Às vezes o pedido é criado uma vez no banco do painel, mas é enviado duas vezes ao fornecedor. São cenários diferentes, e eles são corrigidos de formas diferentes.

Timeout não significa que o pedido não foi criado

A causa mais comum é o cliente aguardar a resposta por um tempo limitado. O servidor recebe a requisição, cria o pedido, mas responde depois do timeout estabelecido. O cliente considera a operação malsucedida e a envia novamente.

Como resultado, o primeiro pedido já está no banco, e a segunda requisição cria mais um. Isso acontece especialmente com resposta lenta de uma API externa, fila sobrecarregada ou conexão instável entre os serviços.

O timeout indica apenas a ausência de resposta, e não a ausência de processamento da requisição.

Repetições automáticas do lado do cliente

Bibliotecas para requisições HTTP, tarefas em segundo plano e serviços de integração frequentemente repetem a requisição automaticamente. O motivo pode ser erro de conexão, código de resposta do servidor, queda de rede ou resposta demorada demais.

A repetição em si é útil: ela reduz o número de pedidos perdidos em falhas temporárias. A desvantagem dessa abordagem é que, sem proteção contra reprocessamento, ela transforma qualquer instabilidade de rede em duplicatas.

• a repetição pode ser acionada no código do site ou do bot;
• a tarefa pode ser reiniciada pela fila;
• a requisição pode ser repetida por um proxy ou módulo de integração;
• o operador pode reenviar o pedido manualmente após um erro.

A requisição repetida chega antes da primeira resposta

Às vezes duas requisições idênticas realmente chegam à API quase ao mesmo tempo. Por exemplo, o usuário enviou o formulário duas vezes, o frontend não bloqueou o botão ou a tarefa em segundo plano iniciou novamente antes da conclusão da primeira.

Se o manipulador primeiro verifica a existência do pedido e depois o cria, duas operações paralelas podem passar pela verificação ao mesmo tempo. Cada uma verá que o pedido ainda não existe, e cada uma adicionará um novo registro.

Essa situação é chamada de condição de corrida. Uma simples verificação prévia no código não protege totalmente contra ela. A desvantagem da verificação sem restrição no nível do banco é que ela falha sob carga paralela.

O pedido foi registrado, mas a resposta da API se perdeu

A requisição passa por várias etapas: o servidor recebe os dados, cria o registro, coloca a tarefa na fila, envia a resposta. Uma falha pode ocorrer entre qualquer uma delas. Por exemplo, o banco já confirmou a criação do pedido, mas a conexão caiu antes da transmissão da resposta ao cliente.

O cliente não sabe se o pedido foi aceito e repete a operação. Uma API sem um mecanismo de verificação separado trata a requisição como nova. No log, isso frequentemente parece que o serviço criou dois pedidos "sozinho", embora tenha recebido duas chamadas de entrada.

Chave de idempotência para criação de pedido

Para operações de criação, é necessária uma chave de idempotência única. O cliente a gera antes do primeiro envio e a transmite junto com os parâmetros do pedido. Em caso de repetição por timeout ou erro, usa-se a mesma chave.

A API salva a chave junto com o resultado do processamento. Se chegar uma requisição com uma chave já conhecida, o servidor não cria um novo pedido, mas retorna o resultado da primeira chamada: o identificador do pedido, seu status ou o erro gerado anteriormente.

Uma chave deve corresponder a uma operação de negócio, e não a uma conexão HTTP.

A desvantagem do método é que as chaves precisam ser armazenadas, limpas conforme as regras e verificadas no lado da API. Se uma nova chave for gerada a cada repetição, a proteção não funcionará. Se uma mesma chave for usada para pedidos diferentes, parte das novas operações será rejeitada por engano.

A unicidade deve ser controlada pelo banco de dados

A idempotência é melhor complementada com uma restrição de unicidade no banco. Para isso, escolhe-se uma combinação que descreva o pedido de forma inequívoca: identificador interno do cliente, chave de idempotência, tipo de serviço e outros campos necessários.

O banco de dados deve rejeitar o segundo registro, mesmo que dois manipuladores tenham chegado à criação ao mesmo tempo. Após o conflito, a API retorna o pedido existente, e não um erro sem explicação.

A desvantagem de uma restrição de unicidade rígida é que ela não pode ser baseada apenas no link ou no username. O cliente pode conscientemente pedir o mesmo serviço para o mesmo canal várias vezes. Uma restrição ampla demais bloqueará compras repetidas normais.

A fila pode entregar a tarefa mais de uma vez

As filas de tarefas frequentemente funcionam pelo princípio de "entrega pelo menos uma vez". Se o worker processou a tarefa, mas não conseguiu confirmar sua execução, a fila pode entregar a mesma tarefa novamente a outro worker.

Para a fila, essa é uma forma normal de não perder a tarefa. Para a criação de pedido sem idempotência, é uma fonte de duplicatas. O identificador da tarefa ou uma chave de operação separada precisa ser transmitido até o manipulador final, incluindo o módulo de envio do pedido ao fornecedor.

A desvantagem de desativar a reentrega é que, se o worker cair, parte dos pedidos pode se perder. É mais seguro aceitar possíveis repetições e tornar o manipulador resistente a elas.

As duplicatas surgem entre o painel e o fornecedor

O pedido interno pode ser criado uma vez, mas a requisição à API externa é enviada duas vezes. A causa é a mesma: o painel não recebeu resposta do fornecedor e decidiu repetir o envio. Se o fornecedor já havia aceitado a primeira requisição, duas solicitações idênticas aparecerão do lado dele.

É necessária uma vinculação separada do pedido interno ao externo: identificador de envio, chave de idempotência ou resposta salva do fornecedor. Não se pode presumir que a proteção na entrada do próprio painel protegerá automaticamente as chamadas de saída.

A desvantagem da conciliação com uma API de terceiros é que nem todo fornecedor oferece suporte à busca por chave externa. Nesse caso, é preciso registrar as tentativas de envio e analisar separadamente os status indefinidos.

O webhook não deve criar um novo pedido

Os webhooks informam sobre mudanças: pedido aceito, iniciado, concluído, cancelado ou que requer verificação. O erro ocorre quando o manipulador do webhook interpreta a notificação como um comando para criar o pedido novamente.

O mesmo webhook pode chegar repetidamente. O remetente repete a entrega se não recebeu confirmação, e as notificações às vezes chegam fora de ordem. O manipulador deve encontrar o pedido existente pelo identificador externo e atualizar o status.

A desvantagem de processar webhooks apenas pelo horário de recebimento é que uma notificação atrasada pode sobrescrever o status atual com um desatualizado. São necessários o identificador do evento, a versão do status ou regras claras de transição.

Quais registros ajudam a encontrar a origem das duplicatas

Para a investigação, não basta ver apenas dois números de pedido. São necessários dados sobre cada etapa do processamento: horário da requisição, chave de idempotência, identificador do cliente, parâmetros do pedido, número da tarefa em segundo plano, resposta da API externa e tentativas de reenvio.

• compare as duplicatas pela chave da operação, e não apenas pelo link;
• verifique se houve requisições idênticas no log da API de entrada;
• veja se a tarefa foi repetida na fila;
• separe a criação do pedido interno do envio ao fornecedor;
• salve o identificador externo da solicitação imediatamente após receber a resposta.

A desvantagem de logs curtos demais é que a origem do problema desaparece antes de ser analisada. A desvantagem do excesso de logs é que tokens, dados pessoais e outros campos sensíveis podem acabar no registro, por isso eles precisam ser mascarados.

Como lidar com um resultado indefinido da requisição

Após um timeout, não se deve criar imediatamente o pedido novamente com novos dados. Primeiro, a API deve verificar a operação pela chave de idempotência ou pelo identificador do cliente. Se o pedido for encontrado, retorna-se seu estado atual. Se o processamento ainda estiver em andamento, o cliente recebe um status de espera.

1. Criar a chave da operação antes da primeira requisição.
2. Enviar a mesma chave a cada repetição.
3. Salvar a chave e o pedido em uma única operação protegida do banco de dados.
4. Transmitir o identificador da operação para a fila e para a API externa.
5. Retornar o pedido criado anteriormente em caso de nova chamada.

Esse cenário exige ajustes na API e na integração do cliente. Sua desvantagem é a depuração mais complexa e mais estados do pedido, mas a reentrega da requisição deixa de significar automaticamente uma nova compra.