Como configurar notificações de conclusão de pedidos via API

Quais eventos considerar como conclusão do pedido

Primeiro, defina qual status na API significa a conclusão efetiva do pedido. Em diferentes fornecedores, pode ser um pedido concluído, entregue, cancelado, rejeitado, devolvido ou parcialmente concluído. Não vincule a automação apenas à palavra "sucesso": o pedido pode passar por vários estados intermediários e depois parar por causa de um limite, verificação ou cancelamento.

Não é apenas o resultado positivo que precisa ser tratado. Se o serviço enviar uma notificação de erro, cancelamento, devolução ou conclusão parcial, ela também deve ser registrada no sistema interno. Caso contrário, no painel, no CRM ou no bot, o pedido ficará aguardando, embora a execução seguinte já não vá acontecer.

Monte uma tabela de correspondência de status

Não passe o status da API para a interface sem tratamento. Os nomes e a lógica do fornecedor podem mudar, e um mesmo status interno às vezes reúne vários status externos. Armazene o valor original separadamente: ele será útil para analisar erros e conferir com a documentação.

• pending, created, queued — pedido novo ou aguardando processamento.
• processing, in_progress, running — pedido em execução.
• completed, delivered, success — pedido concluído.
• partial, partially_completed — pedido parcialmente concluído.
• cancelled, rejected, failed — pedido cancelado ou encerrado com erro.
• refunded, returned — pedido que exige devolução ou ajuste.
• Status desconhecido — não altera o card automaticamente e é encaminhado para verificação.

Os nomes acima são apenas um exemplo de esquema. A tabela final deve ser construída com base nos status da API específica. A desvantagem do mapeamento manual é que, após uma atualização da API, ele precisa ser mantido: um novo status pode chegar ao handler antes de existir uma regra para ele.

Escolha webhooks, polling da API ou ambos os esquemas

Um webhook é uma requisição do serviço para a sua URL quando o status do pedido muda. O polling da API funciona ao contrário: o seu sistema consulta as informações do pedido em intervalos. Para notificações de conclusão, geralmente os webhooks são mais convenientes, porque a atualização chega sem requisições constantes ao método de verificação de status.

• Webhooks são adequados para reação rápida: atualização do card, início da próxima etapa ou envio de mensagem ao responsável.
• O polling é adequado se o fornecedor não suportar notificações por callback ou se o servidor não aceitar requisições externas.
• O esquema combinado usa webhooks como canal principal e o polling para localizar pedidos perdidos ou travados.

A desvantagem do polling é o atraso e a carga extra na API. A desvantagem dos webhooks é que é preciso proteger o endpoint, considerar duplicatas e não depender da ordem de entrega dos eventos.

Configure o endpoint para receber eventos

Para as notificações, é necessário um endereço HTTPS público, acessível pelo serviço de API. Nas configurações da integração, geralmente se informam a URL do handler, o segredo da assinatura e a lista de eventos: mudança de status, conclusão, cancelamento, erro ou conclusão parcial.

Reserve uma rota separada apenas para eventos da API. Assim é mais fácil configurar o registro em log, restringir o acesso, definir limites de requisições e não misturar o tráfego de serviço com os formulários do site. Não use o endereço do ambiente de teste para pedidos reais: após a atualização do ambiente, o fornecedor continuará enviando eventos para a URL salva.

Antes de iniciar, verifique o método da requisição e o formato do corpo conforme a documentação. Na maioria das vezes, é POST com JSON, mas há casos de form-data, parâmetros de query ou esquema próprio de serialização. O erro de parsing deve ser registrado no log, caso contrário será difícil distinguir um payload inválido de uma falha da aplicação.

Mantenha a ligação entre o pedido e o evento

Ao criar um pedido via API, salve o identificador retornado pelo fornecedor. Ao lado, armazene o número interno do pedido, o tipo de serviço, o status original, o horário da última alteração e a resposta original da API de forma segura. Relacione o webhook recebido pelo ID do fornecedor, e não pelo link do canal, nome do serviço ou nome do cliente.

Se a API permitir enviar um identificador externo na criação, adicione o seu número de pedido em um campo como external_id ou client_reference. Isso facilita a busca nos logs e a análise de situações controversas. Mas não use o número externo como única chave: alguns fornecedores não o retornam em todas as notificações.

Não crie um novo pedido a partir de um ID desconhecido do webhook. O evento desconhecido deve ser salvo no log e verificado separadamente. A criação automática de um registro pode gerar dados incorretos ou o processamento de uma requisição falsa.

Use uma estrutura de payload clara

Os nomes exatos dos campos dependem da API. Abaixo não há um contrato de um serviço específico, mas um exemplo de evento JSON que pode servir de referência ao projetar o handler interno. O importante são o identificador do evento, o ID do pedido no fornecedor, o status, o horário da alteração e os dados para diagnóstico.

{

  "event_id": "evt_7f31",

  "event_type": "order.status_changed",

  "created_at": "2025-01-15T12:40:00Z",

  "data": {

    "order_id": "provider_order_4815",

    "external_id": "internal_order_9021",

    "status": "completed",

    "completed_quantity": 1000,

    "requested_quantity": 1000

  }

}

Não use a quantidade de unidades concluídas como sinal de conclusão sem o status. O pedido pode ser concluído parcialmente, e o número no payload pode estar arredondado, atualizado com atraso ou nem ter sido enviado. A desvantagem de armazenar o corpo completo do evento é que ele pode conter dados pessoais ou campos internos, por isso esses registros precisam ser mascarados e ter prazo de armazenamento limitado.

Verifique a assinatura pelo corpo original da requisição

A URL aberta do handler pode receber uma requisição que não veio do serviço de API. Se o fornecedor enviar uma assinatura, segredo ou token, verifique-os antes de alterar o pedido. Um esquema comum é o HMAC-SHA256: o fornecedor calcula a assinatura a partir dos bytes do corpo da requisição e de um segredo compartilhado, e depois envia o resultado em um cabeçalho HTTP.

O princípio do cálculo é assim: pega-se o corpo original da requisição, por exemplo os bytes do JSON sem alterações, e o segredo da integração. Em seguida, calcula-se o HMAC-SHA256. Se o resultado em formato hexadecimal coincidir com o valor do cabeçalho, o corpo não foi alterado após a assinatura e a requisição provavelmente foi enviada por uma parte que conhece o segredo.

Exemplo condicional: HMAC_SHA256(segredo, raw_body) = assinatura do cabeçalho X-Signature. O nome do cabeçalho, o algoritmo e o formato do resultado devem ser obtidos apenas na documentação da API. Alguns serviços adicionam um timestamp ou ID do evento à string de assinatura. Nesse caso, não se pode verificar apenas o corpo JSON.

Não altere o JSON antes de verificar a assinatura

A assinatura é verificada pelos bytes originais da requisição, e não pelo objeto JSON que a aplicação já analisou e remontou. Ao reserializar, podem mudar a ordem dos campos, os espaços, o escape de caracteres, a quebra de linha ou a codificação. Para uma pessoa, o JSON continuará o mesmo, mas o conjunto de bytes mudará e o HMAC não coincidirá mais.

Para evitar isso, primeiro obtenha o raw body como bytes ou buffer, salve-o na memória, calcule a assinatura e só depois de uma verificação bem-sucedida analise o JSON. Não aplique ao corpo trim, conversão de codificação, ordenação de chaves nem formatação. No middleware do framework, verifique se o JSON não é analisado automaticamente antes do acesso ao corpo original.

A desvantagem desse esquema é que o handler passa a depender da ordem dos middlewares. Com a configuração incorreta, a aplicação verá apenas o objeto transformado, e notificações legítimas começarão a ser rejeitadas.

Exemplo de handler com verificação HMAC

Abaixo há um exemplo condicional em Python. Ele mostra a ordem das ações, e não uma integração pronta: os cabeçalhos, o algoritmo, o formato da assinatura e os campos do payload devem ser substituídos pelos valores da documentação do fornecedor.

import hmac

import hashlib

import json

from hmac import compare_digest

def handle_webhook(request):

  raw_body = request.body

  received_signature = request.headers.get("X-Signature", "")

  secret = get_webhook_secret()

  expected_signature = hmac.new(

    secret.encode("utf-8"), raw_body, hashlib.sha256

  ).hexdigest()

  if not compare_digest(expected_signature, received_signature):

    log_invalid_signature(request)

    return response(status=401)

  payload = json.loads(raw_body.decode("utf-8"))

  return process_event(payload)

Para a comparação, use uma função que não interrompa a execução no primeiro caractere divergente. Isso reduz o risco de vazamento de informações sobre a assinatura pelo tempo de resposta. Não passe o segredo para o código do cliente, não o adicione à URL e não o registre inteiro nos logs.

Torne o processamento de eventos idempotente

O fornecedor pode entregar o mesmo evento várias vezes. As causas são comuns: o seu servidor demorou a responder, a conexão caiu após salvar os dados, o endpoint retornou um erro temporariamente ou o serviço iniciou uma nova entrega conforme as próprias regras. A repetição não significa que a API criou um novo pedido.

Idempotência significa que o mesmo evento altera o resultado apenas uma vez. Se essa regra não for considerada, a duplicata enviará novamente a mensagem ao cliente, criará várias tarefas para o gerente, concederá uma compensação ou iniciará uma operação repetida.

O melhor é usar o event_id do payload. Salve-o em uma tabela separada ou em um log de eventos processados com restrição de unicidade. Se não houver um ID separado, forme a chave a partir de campos estáveis: ID do pedido no fornecedor, tipo de evento, status e horário da alteração. Essa opção é pior: com timestamps imprecisos, eventos diferentes podem parecer iguais.

Salve o evento e o status em uma única operação

A verificação de "o evento já foi processado" e o registro do resultado devem ser executados de forma atômica. Caso contrário, duas requisições iguais que cheguem ao mesmo tempo verão ambas a ausência do registro e iniciarão a ação duas vezes. Uma opção prática é um índice único por event_id e uma transação de banco de dados.

A continuação condicional do handler fica assim:

def process_event(payload):

  event_id = payload["event_id"]

  provider_order_id = payload["data"]["order_id"]

  new_status = map_status(payload["data"]["status"])

  with database_transaction():

    if event_exists(event_id):

      return response(status=200)

    order = find_order_by_provider_id(provider_order_id)

    if order is None:

      save_unmatched_event(event_id, payload)

      return response(status=200)

    apply_status_if_allowed(order, new_status, payload)

    save_processed_event(event_id, provider_order_id)

  enqueue_follow_up_actions(event_id)

  return response(status=200)

A desvantagem de responder com um código de sucesso para um pedido desconhecido é que o fornecedor pode não repetir a entrega. Por isso, eventos desconhecidos precisam ser monitorados separadamente e analisados rapidamente. Se a documentação da API recomendar outro código de resposta para esses casos, siga-a.

Considere a quebra da ordem dos eventos

Os webhooks nem sempre chegam estritamente na ordem do horário de alteração do status. Primeiro pode chegar um evento de conclusão e depois uma notificação atrasada do status "em execução". Se você simplesmente registrar o último valor recebido, o pedido concluído voltará a ficar ativo.

Defina transições permitidas. Por exemplo, um status intermediário não pode sobrescrever o final, e um pedido cancelado não é transferido para concluído sem uma verificação separada. Se a API permitir a correção do status final, salve o motivo, o valor original e a origem da alteração.

Se o payload contiver o horário de alteração do pedido, compare exatamente esse horário, e não o horário de recebimento do webhook. Quando a API não enviar essa marca, use prioridades de estados e conferência pelo método de obtenção do pedido. A desvantagem das prioridades é que elas não substituem a sequência real, especialmente se o fornecedor permitir devolução a partir do status final.

Confirme a entrega rapidamente e mova as ações para a fila

Não execute operações demoradas antes de responder ao fornecedor. A verificação da assinatura, a busca do pedido, o registro do evento e a atualização do status geralmente podem ser concluídos rapidamente. O envio de mensagem, a sincronização com o CRM, a geração de relatório ou as requisições a sistemas de terceiros é melhor passar para uma fila de tarefas.

A ordem de trabalho é esta: verificar a assinatura, salvar atomicamente o evento e a mudança de status, retornar uma resposta de sucesso e depois executar as ações secundárias. Se responder antes de salvar, os dados serão perdidos em caso de falha. Se responder após um envio demorado de notificação, o fornecedor pode considerar a entrega malsucedida e enviar uma duplicata.

A desvantagem da fila é que surge um componente separado que precisa ser controlado: erros de tarefas, atrasos e novas execuções. Por outro lado, uma falha na notificação ao gerente não bloqueia o recebimento dos status dos pedidos.

Configure notificações para a equipe e para o cliente

Após a mudança de status, não é preciso notificar todos da mesma forma. Para o gerente, geralmente são importantes os cancelamentos, erros, conclusões parciais e pedidos que ficam muito tempo sem alteração. Para o cliente, muitas vezes basta um resultado claro: pedido concluído, cancelado ou que precisa de esclarecimento.

• Pedido concluído — atualização na área do cliente ou mensagem breve ao cliente.
• Erro de execução — notificação ao responsável com o motivo enviado pela API.
• Conclusão parcial — tarefa para verificar ajuste, devolução ou próxima ação.
• Status desconhecido — registro no log e mensagem ao especialista técnico.
• ID de pedido desconhecido — verificação separada da ligação entre o seu sistema e o fornecedor.

Não envie uma mensagem a cada transição técnica. O feed rapidamente se tornará ruído, e um problema importante passará despercebido. A notificação interna deve conter o número do pedido, o serviço, o status atual, o ID externo e o link para o card.

Mantenha um log e confira os pedidos não concluídos

Os logs são necessários para entender se o serviço enviou o evento, qual corpo chegou, por que a assinatura não passou e em que etapa o processamento parou. Salve o horário de recebimento, o ID do evento, o ID do pedido, o tipo de evento, o resultado da verificação da assinatura, o status interno e o código de resposta. Mascare segredos, tokens e dados pessoais.

Acompanhe separadamente erros de entrega, assinaturas inválidas, pedidos desconhecidos, status não suportados, duplicatas e eventos que não podem ser aplicados por causa da ordem dos estados. O aumento desses registros pode indicar mudança no esquema da API, segredo expirado, falha na rota ou erro na lógica do handler.

Periodicamente, confira os pedidos em status intermediários pelo método de obtenção de dados da API. Essa verificação não substitui os webhooks, mas ajuda a detectar um evento perdido, uma falha na fila ou um caso em que o status externo mudou sem uma notificação correta.