Tratamento do status "em execução" ao verificar o pedido via API

O que significa processing na resposta da API

O status processing, in_progress ou outro estado equivalente significa que o fornecedor aceitou o pedido para processamento, mas não registrou o resultado final. Para serviços de promoção, isso pode ser a verificação do link, a espera na fila, o início da tarefa ou a entrega gradual do volume solicitado.

Processing não confirma a execução bem-sucedida e não significa erro. Depois dele, o pedido pode passar para completed, partial, canceled ou failed. Enquanto o fornecedor retornar um status intermediário, não crie uma nova solicitação para o mesmo link e o mesmo volume.

HTTP 200 com status processing significa uma resposta bem-sucedida da API, e não a conclusão bem-sucedida do pedido. Esses eventos precisam ser armazenados e tratados separadamente.

Quais dados são necessários para verificar o pedido

Para o polling é necessário o ID externo do pedido, que o fornecedor retornou na criação. Salve-o junto com o ID interno, o volume original, os parâmetros do serviço, o link, o horário de criação e a resposta original da API. Buscar o pedido pelo nome do canal, link ou volume não é confiável: esses valores podem coincidir em várias solicitações.

Se após a criação vier um timeout, não reenvie a solicitação automaticamente. O fornecedor pode ter aceitado a requisição, e a resposta pode ter se perdido no caminho. Primeiro use o método de busca de pedido, se houver na documentação, ou encaminhe o caso para verificação.

A desvantagem de armazenar apenas o status atual é que, em uma disputa, não é possível reconstruir quando o pedido passou para processing, se houve progresso e quais respostas chegaram antes.

Exemplo de requisição de status via curl

Obtenha o endereço exato, o método de autorização e os nomes dos campos na documentação do fornecedor. Abaixo é mostrado um modelo: os valores entre colchetes angulares devem ser substituídos pelos dados da API específica.

Requisição GET para um pedido

curl -X GET "https:///orders//status" \

-H "Authorization: Bearer " \

-H "Accept: application/json"

Exemplo de resposta:

{

"order_id": "",

"status": "processing",

"completed_quantity": 250,

"remains": 750,

"updated_at": "значение_времени"

}

Os campos completed_quantity e remains são apresentados apenas como exemplo de estrutura. O fornecedor pode usar progress, start_count, balance ou outros nomes. A desvantagem da abordagem GET é que parte das APIs aceita a verificação de status apenas via POST.

Exemplo de requisição POST e verificação em lote

Requisição POST de status de um pedido

curl -X POST "https:///orders/status" \

-H "Authorization: Bearer " \

-H "Content-Type: application/json" \

-d '{"order_id":""}'

Não passe a chave de API na string da URL. Os endereços das requisições acabam em logs de proxy, sistemas de análise, histórico do navegador e logs técnicos. A desvantagem do POST é que é mais difícil verificá-lo manualmente pela barra de endereços, mas isso não é motivo para mover o segredo para a URL.

Requisição em lote de pedidos ativos

Se a API suportar verificação em lote, envie vários IDs em uma única requisição:

curl -X POST "https:///orders/statuses" \

-H "Authorization: Bearer " \

-H "Content-Type: application/json" \

-d '{"order_ids":["",""]}'

Relacione a resposta ao pedido interno pelo ID externo, e não pela posição do elemento no array. Desvantagem da verificação em lote: o fornecedor pode não retornar todos os pedidos, limitar o tamanho da lista ou informar erro apenas para um ID.

Como definir o polling para processing

Após a primeira resposta processing, coloque a próxima verificação na fila. Escolha o intervalo conforme a documentação da API, os limites de frequência e a natureza do serviço. Para tarefas em que o status muda rapidamente, é aceitável uma verificação mais frequente no início. Para promoção gradual, requisições curtas constantes geralmente não trazem novas informações.

Um esquema prático é aumentar a pausa após respostas processing idênticas. A primeira verificação ocorre após um atraso inicial, depois o intervalo cresce até um máximo estabelecido. Se a API retornar progresso ou um novo horário de atualização, a contagem pode começar a partir dessa mudança.

• Após criar o pedido, não verifique o status imediatamente muitas vezes seguidas: o serviço pode precisar de tempo para entrar na fila.
• Com processing recorrente, aumente o intervalo entre as requisições em vez de manter uma frequência constante.
• Adicione uma pequena variação aleatória ao horário de execução das tarefas para que os pedidos não consultem a API ao mesmo tempo.
• Se o fornecedor enviar Retry-After ou uma recomendação equivalente, use-a como prioritária.
• Para pedidos com webhooks, mantenha um polling de controle: a notificação pode não chegar.

A desvantagem do polling raro é que a interface pode mostrar um status antigo após a conclusão real. A desvantagem do polling excessivamente frequente é o risco de esbarrar nos limites da API, receber 429 e gerar carga desnecessária.

Quais horários armazenar para controlar o processing

Para distinguir a execução normal de um travamento, um único status atual não basta. Para cada pedido ativo, armazene o horário de criação, a primeira obtenção de processing, a última resposta bem-sucedida da API, a última alteração do status externo e a última alteração do progresso.

Também é útil salvar o volume original, o volume executado confirmado, o saldo restante e o status original do fornecedor. Se a API não retornar progresso, isso não é motivo para considerar o pedido travado: oriente-se pelo horário da última resposta e pelo período de processamento esperado, se estiver indicado nas condições do serviço.

O tempo máximo de espera não pode ser definido com um único número para todos os serviços. Use o prazo que o fornecedor indica para o serviço específico, com uma margem interna para fila e atualização de dados. Se o prazo não estiver indicado, defina uma regra separada para cada categoria de serviço e revise-a com base no histórico de processamento real.

O que fazer se o processing não mudar

Um processing prolongado não prova erro. Primeiro verifique se chegaram respostas bem-sucedidas da API, se completed_quantity ou remains mudaram, se houve webhooks e se as regras do serviço mudaram. A ausência de crescimento visível pode estar relacionada ao atraso das estatísticas da plataforma ou ao fato de o fornecedor atualizar o progresso apenas no final.

Quando o prazo interno de espera for excedido, não cancele o pedido automaticamente. Faça uma verificação de status fora da programação, solicite os dados por um método separado, se houver, e verifique o histórico de notificações. Se o fornecedor ainda confirmar processing, mova o pedido para um estado interno de "requer verificação", mas mantenha o status externo sem substituí-lo.

• Registre o horário da última resposta confirmada e a resposta completa da API.
• Verifique se o progresso mudou desde a consulta anterior.
• Reduza a frequência das requisições automáticas após atingir o limite interno.
• Encaminhe ao suporte o ID externo, o link, os parâmetros do serviço, o histórico de status e os erros técnicos.
• Não reinicie o saldo restante antes da resposta do fornecedor ou de um status final explícito.

A desvantagem da verificação manual é que o pedido exige atenção do suporte. Mas o cancelamento automático ou a duplicidade é mais perigoso: a execução pode continuar no fornecedor.

Como separar falha de requisição do status do pedido

Erro de rede, timeout, HTTP 429 e resposta 5xx não informam o estado do próprio pedido. Eles significam apenas que não foi possível obter um novo status confiável. Nessa situação, mantenha o último status confirmado, registre o erro técnico e agende uma nova verificação.

Em caso de 429, considere o Retry-After, se o cabeçalho for enviado. Em erros temporários de rede e 5xx, aumente a pausa entre as tentativas. Em erro de autorização, assinatura ou permissões de acesso, não faça retentativas frequentes: é preciso verificar a chave, a validade do token, as restrições de IP e as configurações de acesso.

Se a API retornar HTTP 200, mas o JSON não for interpretável ou a resposta não tiver order_id e status, salve o corpo da resposta por completo e marque a verificação como incorreta. Não substitua a ausência de status por completed, canceled ou processing.

Quando interromper as requisições automáticas repetidas

O polling não deve ser infinito. Limite o número de retentativas técnicas para erros temporários e controle separadamente o prazo total em que o pedido permanece em processing. Após esgotar o limite de retentativas, mova a tarefa de verificação para a fila de análise, em vez de criar novas requisições a cada minuto sem resultado.

Repetir a requisição de status geralmente é seguro se o método apenas lê dados. Métodos de criação, cancelamento, recarga, reinício e reembolso não podem ser repetidos mecanicamente após um timeout. Sem uma chave idempotente ou confirmação explícita do fornecedor, essa repetição pode alterar o pedido duas vezes.

A desvantagem de limitar as retentativas é que parte das atualizações se tornará uma tarefa manual. Retentativas infinitas são piores: mascaram a falha, consomem limites e dificultam a análise dos logs.

Como aceitar o status final após o processing

Evite a transição reversa de completed para processing por causa de uma resposta de polling atrasada ou de um webhook antigo. A cada atualização, compare o horário do evento do fornecedor, o número de versão sequencial, se houver, e o estado interno atual.

• new e pending podem passar para processing, canceled ou failed.
• processing pode passar para completed, partial, canceled ou failed.
• partial não deve ser automaticamente considerado completed.
• completed, canceled e failed geralmente são considerados finais e bloqueiam o retorno automático.
• Status desconhecido ou transição inválida exigem verificação separada.

Uma tabela rígida de transições também tem desvantagem: o fornecedor pode adicionar um novo estado válido. Por isso, mantenha o status original e não o substitua pela classificação interna.

Como tratar partial e o saldo restante do pedido

Partial significa que apenas parte do volume original foi confirmada. A resposta da API pode conter a quantidade efetivamente executada, o saldo restante, o motivo e os dados de compensação. Armazene esses valores separadamente: o volume original do pedido não pode ser substituído pela quantidade executada.

Um exemplo de resposta final pode ser assim:

{

"order_id": "",

"status": "partial",

"completed_quantity": 700,

"remains": 300,

"refund": "значение_или_отсутствие_поля"

}

Primeiro determine o que exatamente a API confirma: o reembolso já foi processado, o reembolso está apenas agendado, o saldo restante foi cancelado ou é necessário contatar o suporte. Se não houver campo sobre reembolso, não considere o saldo restante compensado automaticamente.

Não reinicie a parte não executada sem uma decisão separada. O fornecedor pode ainda estar finalizando o cálculo, as estatísticas da plataforma podem ser atualizadas com atraso, e uma nova solicitação pode criar uma promoção duplicada. A desvantagem de esperar a confirmação é que o saldo restante não será fechado imediatamente, mas não surgirá um pedido extra.

Webhooks não substituem a verificação de controle

O webhook permite atualizar o cartão do pedido logo após o evento, sem esperar o próximo polling. No manipulador, encontre o pedido pelo ID externo, verifique a assinatura ou o segredo, salve o ID do evento e aplique a transição somente após verificar sua validade.

A reentrega de um webhook deve ser segura: o mesmo evento não pode ser considerado uma nova alteração. Os eventos também podem chegar fora de ordem, portanto não mova um pedido final de volta apenas com base em um processing atrasado.

O polling de controle é necessário mesmo com webhooks estáveis. A desvantagem dos webhooks é a configuração mais complexa: é preciso um manipulador acessível, proteção contra requisições falsas, deduplicação e registro de eventos.

O que mostrar ao cliente durante processing e travamento

Na interface, não é necessário exibir todo o JSON técnico. Para processing, basta o estado "pedido em andamento". Se a API retornar um progresso confiável, mostre o volume confirmado separadamente do original e não o apresente como resultado final.

Para um pedido que excedeu o prazo interno de controle, use um estado compreensível como "verificando a execução". Não informe cancelamento, reembolso ou conclusão total enquanto isso não for confirmado pela resposta do fornecedor.

As notificações são úteis na aceitação do pedido, na execução final, em partial, no cancelamento, em erro e quando houver necessidade de verificação. Mensagens após cada polling geram ruído e não ajudam o cliente a entender o estado real da solicitação.

Quais registros são necessários no log de processamento

O histórico de respostas ajuda a analisar um processing travado, um webhook perdido, uma disputa sobre execução parcial e uma divergência entre a interface e a API. Para cada chamada, armazene o ID externo, a origem da atualização, o horário da requisição e da resposta, o código HTTP, o status original, o status normalizado, o progresso, o saldo restante e o texto do erro técnico.

Não registre nos logs comuns chaves de API, tokens, assinaturas e outros segredos. Restrinja o acesso às respostas brutas: elas podem conter dados que não deveriam estar na interface do suporte.

Antes do lançamento, teste os cenários com processing recorrente, ausência de progresso, timeout, 429, erro 5xx, JSON inválido, webhook atrasado, webhook duplicado, partial, canceled e status desconhecido. O modo de teste é útil para a estrutura da integração, mas sua desvantagem é que ele pode não reproduzir as filas e atrasos reais da API de produção.