Pular para o conteúdo principal

Acompanhamento de Pedido

O sistema possui um sistema robusto de acompanhamento de pedidos que cobre todo o ciclo de vida, desde a criação até possíveis devoluções.

Visão Geral​

O sistema de acompanhamento de pedidos utiliza webhooks para enviar notificações em tempo real sobre eventos relacionados aos pedidos. Isso permite que você mantenha seu sistema atualizado com o status mais recente dos pedidos sem a necessidade de consultas constantes à API.

Estados do Pedido​

1. Criação e Pagamento​

  1. CartCreated (1)

    • Pedido adicionado ao carrinho
    • Ainda não finalizado

  2. OrderCreated (100)

    • Pedido criado
    • Aguardando processamento

  3. PaymentPending (200)

    • Aguardando confirmação do pagamento

  4. PaymentInProgress (230)

    • Pagamento em processamento
    • Aguardando retorno do gateway

  5. PaymentError (250)

    • Erro no pagamento
    • Requer ação do cliente

  6. PaymentApproved (300)

    • Pagamento aprovado
    • Pedido pronto para próxima fase

2. Processamento e Faturamento​

  1. OrderInvoiced (350)

    • Pedido faturado
    • Nota fiscal emitida

  2. OrderBeingPrepared (400)

    • Pedido em preparação/separação

3. Envio e Entrega​

  1. ReadyForPickupOrDelivery (500)

    • Pronto para retirada pelo cliente ou envio

  2. Shipped (600)

    • Pedido enviado
    • Em trânsito

  3. Delivered (700)

    • Entregue ao cliente
    • Estado final para entrega normal

4. Cancelamento​

  1. OrderCancellationAnalysis (750)

    • Análise de cancelamento em andamento

  2. OrderCancelled (800)

    • Pedido cancelado
    • Estado final de cancelamento

5. Falha e Devolução​

  1. DeliveryFailed (900)

    • Entrega não realizada
    • Requer ação adicional

  2. OrderReturned (1000)

    • Pedido devolvido

  3. RefundInProgress (1100)

    • Reembolso em processamento

  4. RefundCompleted (1200)

    • Reembolso concluído
    • Estado final para devolução

6. Atualização​

  1. OrderUpdated (1300)
    • Pedido atualizado (itens ou valores alterados)

Diagrama de Estados​

diagrama de status de pedidos

Notificações via Webhook​

Para cada mudança de estado, uma notificação é enviada via webhook com a seguinte estrutura:

{
  "operationId": "5f1d265b-d836-40f7-84dd-7ded9804039d",
  "relatedEntity": 0,
  "eventType": 14,
  "data": {
    "id": "1653576b-3dfe-43b3-42ea-08dd92f2e015",
    "contractAccountId": "e9a2fca6-198f-4b4a-a183-2356ef6562f5",
    "status": 300,
    "number": 1000367,
    "createdAt": "2025-05-14T14:31:52.2747054",
    "updatedAt": "2025-05-14T18:24:49.5674408",
    "items": [
      {
        "orderedQuantity": 2,
        "skuId": "9642791a-99b2-450f-542e-08dd038649c3",
        "ean": "7898994939788",
        "reference": "104752",
        "unitOfMeasure": "Un",
        "salePrice": 9.59,
        "totalPerProduct": 19.18
      }
    ],
    "subtotal": {
      "subtotal": 19.18,
      "discount": 0,
      "frete": 0,
      "total": 19.18
    },
    "deliveryType": 3
  },
  "contractAccountId": "e9a2fca6-198f-4b4a-a183-2356ef6562f5"
}

Boas Práticas​

  1. Monitoramento

    • Implementar tratamento para todos os estados possíveis
    • Manter histórico de transições
    • Validar sequência de estados

  2. Tratamento de Erros

    • Implementar retry para falhas de webhook
    • Armazenar estados não reconhecidos
    • Alertar sobre transições inválidas

  3. UX

    • Agrupar estados em fases lógicas
    • Mostrar progresso estimado
    • Destacar ações necessárias do cliente