Cancelamentos pedidos pelo cliente
Lista as solicitações de cancelamento feitas pelos clientes e aprova ou recusa cada uma.
Quando o cliente pede para cancelar uma compra na loja, a plataforma segue a política que a loja configurou:
- Automática: dentro de uma janela definida pela loja, o pedido é cancelado na hora e, se a loja configurou, o dinheiro é devolvido.
- Com revisão: fora da janela, o pedido vira uma solicitação de cancelamento pendente. Alguém da loja (ou o seller dono do pedido) decide: aprova ou recusa.
As rotas desta página são a fila dessa revisão. Quem pede o cancelamento é o cliente, pela loja (POST /api/v1/storefront/orders/{id}/cancel, que não faz parte desta API de administração); você, como integrador ou atendente, lista as solicitações e decide.
Situação de uma solicitação
status | Significado |
|---|---|
pending | Aguardando decisão. |
processing | Aprovação em andamento (o estorno e a mudança de status estão sendo feitos). Na lista, aparece junto com pending. |
approved | Aprovada por alguém da loja; o pedido foi cancelado. |
auto_approved | Cancelada automaticamente pela política da loja. Na lista, aparece junto com approved. |
rejected | Recusada; o pedido volta ao que era antes do pedido de cancelamento. |
/api/v1/admin/order-cancellationsAdminLista as solicitações de cancelamento
Lista até 200 solicitações, da mais recente para a mais antiga. Exige view_orders ou manage_orders.
Query parameters
statusstringpadrão: pendingpendingapprovedrejectedpending inclui as que estão em processing; approved inclui as auto_approved. Omitido, ou vazio, vale pending./api/v1/admin/order-cancellations/{id}/approveAdminAprova uma solicitação de cancelamento
Aprova a solicitação: o pedido é movido para o status de cancelamento configurado pela loja e, se a política da loja prevê reembolso automático e o cliente o pediu, o estorno é solicitado ao gateway. Só depois de o estorno e a mudança de status darem certo a solicitação passa a approved. Se qualquer uma das duas falhar, nada é cancelado, a solicitação volta a pending e a resposta é 502. Exige manage_orders.
A chamada é idempotente: decidir uma solicitação que já foi decidida devolve 200 com a solicitação como está e "idempotent": true.
Path parameters
iduuidobrigatórioid da lista, não o id do pedido).Corpo da requisição (opcional)
reasonstring/api/v1/admin/order-cancellations/{id}/rejectAdminRejeita uma solicitação de cancelamento
Recusa a solicitação: o pedido segue o fluxo normal (se a própria solicitação o tinha movido de status, ele volta ao status anterior) e o cliente é avisado por e-mail. Se reason for omitido, vale o texto padrão "Solicitação não aprovada. Entre em contato com o seller em caso de dúvida." Exige manage_orders.
Path parameters
iduuidobrigatórioCorpo da requisição (opcional)
reasonstringExemplo de requisição
Resposta
Campos da resposta
requestsarrayrequestobjectidempotentbooleantrue quando a solicitação já tinha sido decidida e nada foi feito agora.iduuidorder_iduuidorder_numberstringvendor_iduuidcustomer_iduuidcustomer_namestringcustomer_emailstringstatusstringpendingprocessingapprovedauto_approvedrejectedprocessing_modestringreviewautomaticreview (precisa de decisão de alguém da loja) ou automatic (cancelado na hora).request_reasonstringdecision_reasonstringrequested_byuuiddecided_byuuidprevious_order_statusstringrequested_order_statusstringresulting_order_statusstringrefund_requestedbooleantrue quando o cliente pediu o dinheiro de volta.refund_completedbooleantrue quando o estorno foi confirmado.refund_amountintegerrefund_referencestringrefund_confirmed_atstringrefund_confirmed_byuuidfailure_codestringrefund_unconfirmed ou cancellation_failed).created_atstringdecided_atstringupdated_atstringErros
| Status | Quando | Corpo |
|---|---|---|
| 400 | Corpo inválido | {"error":"invalid request body"} |
| 401 | Sem credenciais ou token expirado | {"error":"invalid or expired token"} |
| 403 | Sem permissão | {"error":"insufficient privileges","required":"manage_orders"} |
| 404 | Solicitação não encontrada | {"error":"cancellation request not found"} |
| 409 | O pedido não pode mais ser cancelado (status final) ou não pôde ser validado | {"error":"order is no longer cancellable","detail":"its order or payment status is terminal"} |
| 502 | O estorno ou a mudança de status falhou; a solicitação segue pending | {"error":"cancellation could not be completed","detail":"payment refund or order transition failed; the request remains pending"} |
| 500 | Falha interna | {"error":"failed to complete cancellation decision"} |