Acompanhamento de Pedido
O sistema Grocers possui um sistema robusto de acompanhamento de pedidos que cobre todo o ciclo de vida, desde a criação até possíveis devoluções ou trocas.
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
-
Cart (1)
- Pedido adicionado ao carrinho
- Ainda não finalizado
-
OrderCreated (100)
- Pedido criado
- Aguardando processamento
-
PaymentPending (200)
- Aguardando confirmação do pagamento
4 PaymentError (250)
- Erro no pagamento
- Requer ação do cliente
-
PaymentApproved (300)
- Pagamento aprovado
- Pedido pronto para próxima fase
2. Cancelamento
-
CancellationWindow (7)
- Período permitido para cancelamento
- Cliente pode solicitar cancelamento
-
CancellationPending (8)
- Solicitação de cancelamento em processamento
-
Canceled (9)
- Pedido cancelado
- Estado final
3. Processamento
-
Hold (10)
- Pedido em espera
- Pode ser por falta de estoque ou verificação de segurança
-
Invoiced (11)
- Pedido faturado
- Nota fiscal emitida
-
ReadyForHandling (12)
- Pronto para processamento
- Aguardando separação
4. Envio e Entrega
-
ShippingHandling (13)
- Pedido em preparação para envio
-
ReadyForCustomerPickup (14)
- Pronto para retirada pelo cliente
- Aplicável para retirada em loja
-
PickedUpByCustomer (15)
- Coletado pelo cliente
- Estado final para retirada
-
ReadyForPickupByCarrier (16)
- Pronto para coleta pelo transportador
-
PickedUpByCarrier (17)
- Coletado pelo transportador
-
ArrivalAtLocalFacility (18)
- Chegou ao centro de distribuição local
-
Shipped (19)
- Pedido enviado
- Em trânsito
-
OutForDelivery (20)
- Em rota de entrega
-
DeliveryAttempted (21)
- Tentativa de entrega realizada
- Sem sucesso
-
Delivered (22)
- Entregue ao cliente
- Estado final para entrega normal
-
FailedDelivery (23)
- Entrega não realizada
- Requer ação adicional
5. Devoluções
-
ReturnRequested (24)
- Cliente solicitou devolução
-
ReturnApproved (25)
- Devolução aprovada
-
ReturnDenied (26)
- Devolução negada
-
ReturnShipped (27)
- Cliente enviou item para devolução
-
ReturnReceived (28)
- Item devolvido recebido
-
RefundPending (29)
- Reembolso em processamento
-
Refunded (30)
- Reembolso concluído
- Estado final para devolução
6. Trocas
-
ExchangeRequested (31)
- Cliente solicitou troca
-
ExchangeApproved (32)
- Troca aprovada
-
ExchangeDenied (33)
- Troca negada
-
ExchangeShipped (34)
- Item de troca enviado
-
ExchangeDelivered (35)
- Item de troca entregue
- Estado final para troca
Diagrama de Estados
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": {
{
"transactionId": "1653576b-3dfe-43b3-42ea-08dd92f2e015",
"acquirerTransactionId": "10463608574LE7UMLD8E",
"eventType": 14,
"seller": {
"id": "db59b59d-56c0-4912-aea8-08dd0572838d",
"name": "Loja 14 - Leblon",
"country": "Brasil",
"state": "RJ",
"city": "Rio de Janeiro",
"neighborhood": "Leblon",
"zipCode": "22431000",
"street": "Rua Bartolomeu Mitre",
"number": "705",
"complement": null,
"reference": null,
"phoneNumber": "(21) 2512-2200",
"description": "Loja Física",
"sellerCode": "14",
"active": true
},
"currency": "BRL",
"paymentAttempts": [
{
"id": "c71639a6-2b6c-4453-f7dd-08dd92f2e041",
"orderId": "1653576b-3dfe-43b3-42ea-08dd92f2e015",
"serviceProviderPaymentMethod": {
"id": "adb67343-c252-49f1-8121-08dca1ae2d23",
"paymentMethod": {
"id": 1,
"name": "Cartão de Crédito"
},
"contractServiceProvider": {
"serviceProvider": {
"id": 2,
"name": "Braspag"
},
"name": "Braspag"
}
},
"userPaymentMethod": {
"id": "94ef1e54-b0b0-49bc-0744-08dd6556528d",
"userId": "b439fd4f-e902-4178-b1a0-08dd65546bd1",
"data": "{\"cardToken\":\"\",\"last4Numbers\":\"1151\",\"holderName\":\"Leandro Nascimento\",\"customerId\":null,\"paymentMethodId\":\"1\",\"cardBrand\":\"Mastercard\"}",
"displayValue": "**** 1151",
"additionalInfo": "string",
"addressType": "string",
"city": "Paulista",
"country": "Brasil",
"neighborhood": "Janga",
"number": "320",
"reference": null,
"state": "PE",
"street": "Rua Palmares",
"zipCode": "53437570",
"transactionId": "1653576b-3dfe-43b3-42ea-08dd92f2e015",
"acquirerTransactionId": "10463608574LE7UMGENE",
"active": 1
},
"status": "Success",
"data": null
},
{
"id": "241be114-4083-4de9-f7dc-08dd92f2e041",
"orderId": "1653576b-3dfe-43b3-42ea-08dd92f2e015",
"serviceProviderPaymentMethod": {
"id": "adb67343-c252-49f1-8121-08dca1ae2d23",
"paymentMethod": {
"id": 1,
"name": "Cartão de Crédito"
},
"contractServiceProvider": {
"serviceProvider": {
"id": 2,
"name": "Braspag"
},
"name": "Braspag"
}
},
"userPaymentMethod": {
"id": "dc3e76b9-b5ee-42e4-032f-08dd92f2dab8",
"userId": "48816a89-d07c-46a8-8075-08dd61ad19b9",
"data": "{\"cardToken\":\"\",\"last4Numbers\":\"3607\",\"holderName\":\"Paulo H Weber\",\"customerId\":null,\"paymentMethodId\":\"1\",\"cardBrand\":\"Mastercard\"}",
"displayValue": "**** 3607",
"additionalInfo": "string",
"addressType": "string",
"city": "Rio de Janeiro",
"country": "Brasil",
"neighborhood": "Leblon",
"number": "12",
"reference": null,
"state": "RJ",
"street": "Praça Poeta Gibraim",
"zipCode": "22430030",
"transactionId": "1653576b-3dfe-43b3-42ea-08dd92f2e015",
"acquirerTransactionId": "10463608574LE7UMLD8E",
"active": 1
},
"status": "Rebilling",
"data": null
},
{
"id": "b9c15904-914f-4b45-f7db-08dd92f2e041",
"orderId": "1653576b-3dfe-43b3-42ea-08dd92f2e015",
"serviceProviderPaymentMethod": {
"id": "adb67343-c252-49f1-8121-08dca1ae2d23",
"paymentMethod": {
"id": 1,
"name": "Cartão de Crédito"
},
"contractServiceProvider": {
"serviceProvider": {
"id": 2,
"name": "Braspag"
},
"name": "Braspag"
}
},
"userPaymentMethod": {
"id": "94ef1e54-b0b0-49bc-0744-08dd6556528d",
"userId": "b439fd4f-e902-4178-b1a0-08dd65546bd1",
"data": "{\"cardToken\":\"\",\"last4Numbers\":\"1151\",\"holderName\":\"Leandro Nascimento\",\"customerId\":null,\"paymentMethodId\":\"1\",\"cardBrand\":\"Mastercard\"}",
"displayValue": "**** 1151",
"additionalInfo": "string",
"addressType": "string",
"city": "Paulista",
"country": "Brasil",
"neighborhood": "Janga",
"number": "320",
"reference": null,
"state": "PE",
"street": "Rua Palmares",
"zipCode": "53437570",
"transactionId": "1653576b-3dfe-43b3-42ea-08dd92f2e015",
"acquirerTransactionId": "10463608574LE7UMLD8E",
"active": 1
},
"status": "Pending",
"data": null
}
],
"user": {
"id": "48816a89-d07c-46a8-8075-08dd61ad19b9",
"gender": "Prefiro não informar",
"firstName": "Paulo",
"lastName": "Weber",
"email": "paulloweber@gmail.com",
"document": "07713322973",
"phoneDDI": "55",
"phoneNumber": "45999301872",
"birthDate": "1996-08-30",
"active": true,
"contractAccountId": "e9a2fca6-198f-4b4a-a183-2356ef6562f5",
"contractAccount": null,
"userRole": null
},
"items": [
{
"orderedQuantity": 2,
"id": "76301163-e0f9-44a1-eb67-08dd03864ebb",
"skuId": "9642791a-99b2-450f-542e-08dd038649c3",
"ean": "7898994939788",
"reference": "104752",
"unitOfMeasure": "Un",
"arithmeticFactor": 1,
"minimumWeightForSale": null,
"brandId": "bebb0536-dfb5-45a7-359a-08dd038fea21",
"categoryId": "16575ab7-0832-4c5e-bff1-cd96b4015728",
"commercialPolicyId": "b6a2f813-9952-4f35-fbc5-08dcf2bc3756",
"fiscalCode": "11111",
"salePrice": 9.59,
"arithmeticFactorPrice": 9.59,
"totalPerProduct": 19.18,
"priceStartDateTime": null,
"priceEndDateTime": null
}
],
"id": "1653576b-3dfe-43b3-42ea-08dd92f2e015",
"contractAccountId": "e9a2fca6-198f-4b4a-a183-2356ef6562f5",
"deviceId": null,
"orderAddressId": "d437982a-4bcf-47ca-57b7-08dd92f296a7",
"orderAddress": {
"id": "d437982a-4bcf-47ca-57b7-08dd92f296a7",
"country": "Brasil",
"state": "RJ",
"city": "Rio de Janeiro",
"neighborhood": "Leblon",
"street": "Praça Poeta Gibraim",
"number": "12",
"zipCode": "22430030",
"addressType": "residence",
"additionalInfo": "nothing",
"reference": ""
},
"status": 300,
"number": 1000367,
"createdAt": "2025-05-14T14:31:52.2747054",
"updatedAt": "2025-05-14T18:24:49.5674408",
"orderStatusRegistry": null,
"shippingPolicy": {
"id": "b28a3aaa-6c51-40e8-1080-08dd0a6c89d2",
"name": "Retirada - Loja 14",
"createdAt": "2024-11-21T20:39:04.1474183",
"updatedAt": "2025-04-02T16:42:37.6955952",
"sellerId": "db59b59d-56c0-4912-aea8-08dd0572838d",
"expressDelivery": null,
"scheduledDelivery": null,
"pickupPoint": {
"id": "2fb54427-a396-44e1-702b-08dd0a6c89d4",
"shippingPolicyId": "b28a3aaa-6c51-40e8-1080-08dd0a6c89d2",
"shippingPolicy": {
"id": "b28a3aaa-6c51-40e8-1080-08dd0a6c89d2",
"contractAccountId": "e9a2fca6-198f-4b4a-a183-2356ef6562f5",
"sellerId": "db59b59d-56c0-4912-aea8-08dd0572838d",
"isDefault": false
},
"seller": {
"id": "db59b59d-56c0-4912-aea8-08dd0572838d",
"name": "Loja 14 - Leblon",
"country": "Brasil",
"state": "RJ",
"city": "Rio de Janeiro",
"neighborhood": "Leblon",
"zipCode": "22431000",
"street": "Rua Bartolomeu Mitre",
"number": "705",
"complement": null,
"reference": null
},
"separationTime": "02:00:00",
"hoursLimit": "02:00:00",
"minimumQuantityItems": 0,
"maximumQuantityItems": 70,
"minimumPurchaseValue": 0,
"ordersOutsideOfPurchasingHours": false
}
},
"subtotal": {
"subtotal": 19.18,
"discount": 0,
"couponDiscount": null,
"appliedCouponCode": null,
"frete": 0,
"isFreeShipping": false,
"total": 19.18,
"appliedPromotions": []
},
"couponId": null,
"deliveryType": 3,
"acceptedOrderDetails": {
"userPaymentData": "{\"cardToken\":\"\",\"last4Numbers\":\"3607\",\"holderName\":\"Paulo H Weber\",\"customerId\":null,\"paymentMethodId\":\"1\",\"cardBrand\":\"Mastercard\"}",
"shippingPolicyName": "Retirada - Loja 14",
"paymentProvider": "Braspag",
"paymentMethod": "Cartão de Crédito",
"subtotal": 9.59,
"discount": 0,
"netDiscount": 0,
"frete": 0,
"total": 9.59,
"couponDiscount": null,
"appliedCouponCode": null,
"cashChange": 0,
"scheduledDate": null,
"scheduledDayOfWeek": null,
"scheduledStartTime": null,
"scheduledEndTime": null,
"expressStartDate": null,
"expressSubtypeName": null,
"expressMinimumQuantityItems": null,
"expressMaximumQuantityItems": null,
"expressMaximumDeliveryTime": null,
"expressMinimumPurchaseValue": null,
"pickupPointHoursLimit": "02:00:00",
"pickupPointPackageItemsMinimumItems": 0,
"pickupPointPackageItemsMaximumItems": 70,
"pickupOrdersOutsideOfPurchasingHours": null,
"pickupPointCountryName": null,
"pickupPointState": null,
"pickupPointCity": null,
"pickupPointNeighborhood": null,
"pickupPointZipCode": null,
"pickupPointStreet": null,
"pickupPointNumber": null,
"pickupPointComplement": null,
"pickupPointReference": null,
"pickupPointName": null,
"additionalInformation": [
{
"title": "Quem irá receber as compras?",
"value": "Eu mesmo",
"dataType": 1
},
{
"title": "Observações",
"value": "",
"dataType": 1
},
{
"title": "Aceita substituição de item?",
"value": true,
"dataType": 2
},
{
"title": "CPF na nota?",
"value": false,
"dataType": 2
}
]
},
"canBeCancelled": false,
"itemAmount": 2
},
"contractAccountId": "e9a2fca6-198f-4b4a-a183-2356ef6562f5"
}
Boas Práticas
-
Monitoramento
- Implementar tratamento para todos os estados possíveis
- Manter histórico de transições
- Validar sequência de estados
-
Tratamento de Erros
- Implementar retry para falhas de webhook
- Armazenar estados não reconhecidos
- Alertar sobre transições inválidas
-
UX
- Agrupar estados em fases lógicas
- Mostrar progresso estimado
- Destacar ações necessárias do cliente