Devoluções e contestações
Como o cliente devolve um produto ou contesta um pedido que não chegou direito.
Depois que o pedido chegou, duas coisas podem dar errado, e a API trata cada uma com um instrumento diferente. Quando o produto chegou e o cliente quer mandá-lo de volta (defeito, tamanho, arrependimento), ele abre uma devolução. Quando o pedido não chegou, veio diferente ou danificado e o cliente quer uma solução do seller, ele abre uma contestação. Esta seção cobre os dois, sempre em nome de um cliente logado.
Como funciona
O ciclo da devolução
status | Significado | Quem move |
|---|---|---|
requested | O cliente abriu o pedido de devolução; a loja ainda não decidiu. | Cliente (cria) |
approved | A loja aceitou. O cliente deve enviar o produto (veja reverse_*). | Loja ou seller |
item_received | A mercadoria chegou de volta e foi conferida. | Loja ou seller, ou o rastreio reverso |
refunded | O dinheiro (ou o crédito) foi devolvido. | Loja |
rejected | A loja recusou. admin_notes explica. | Loja ou seller |
closed | Caso encerrado depois de reembolsado ou recusado. | Loja |
cancelled | O cliente desistiu enquanto estava requested. | Cliente |
Se a loja ligou a aprovação automática, a devolução já nasce approved. O cliente só age em dois momentos: abrir a devolução e, se desistir antes da decisão, cancelar. Todo o resto é decisão da loja ou do seller.
Devolução ou contestação?
| Situação do cliente | Instrumento |
|---|---|
| Recebi, mas quero devolver (defeito, tamanho, desisti) | Devolução |
| Não recebi, veio errado ou diferente da descrição, chegou danificado | Contestação |
| Quero só desistir de um pedido ainda não enviado | Cancelar pedido |
Conceitos-chave
Resolução e destino do dinheiro
resolution diz o que o cliente quer: refund (dinheiro de volta), replacement (troca pelo mesmo produto) ou store_credit (crédito). refund_destination diz para onde vai o reembolso: original (volta pela forma de pagamento) ou wallet (carteira da loja; a política mostra o bônus que a loja dá nesse caso).
Uma devolução ativa por vez
Enquanto houver uma devolução em requested, approved ou item_received para o mesmo pedido (ou para a mesma linha, quando order_item_id é enviado), uma nova é recusada. Para devolver duas linhas do mesmo pedido, envie order_item_id em cada uma.
Endpoints
| Método e caminho | Para quê | Página |
|---|---|---|
POST /api/v1/storefront/orders/{orderId}/return | Abre uma devolução | Pedir devolução |
GET /api/v1/storefront/returns | Lista as devoluções do cliente | Acompanhar devoluções |
GET /api/v1/storefront/returns/{id} | Detalhe de uma devolução | Acompanhar devoluções |
DELETE /api/v1/storefront/returns/{id} | Cancela uma devolução ainda solicitada | Acompanhar devoluções |
GET /api/v1/storefront/returns/{id}/reverse-events | Linha do tempo da logística reversa | Acompanhar devoluções |
GET /api/v1/storefront/returns/policy | Janela, motivo obrigatório e bônus | Política e motivos |
GET /api/v1/storefront/returns/reasons | Motivos de devolução | Política e motivos |
POST /api/v1/storefront/account/orders/{orderId}/disputes | Abre uma contestação | Contestações |
GET /api/v1/storefront/account/disputes | Lista as contestações | Contestações |
GET /api/v1/storefront/account/disputes/{id} | Detalhe de uma contestação | Contestações |
POST /api/v1/storefront/account/disputes/{id}/accept-proposal | Aceita a proposta do seller | Contestações |
POST /api/v1/storefront/account/disputes/{id}/escalate | Leva o caso à loja | Contestações |