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.

GET/api/v1/admin/order-cancellationsAdmin

Lista 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: pending

pendingapprovedrejected

Filtro de situação. pending inclui as que estão em processing; approved inclui as auto_approved. Omitido, ou vazio, vale pending.

POST/api/v1/admin/order-cancellations/{id}/approveAdmin

Aprova 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ório

Id da solicitação (campo id da lista, não o id do pedido).

Corpo da requisição (opcional)

reasonstring

Justificativa da decisão, até 2000 caracteres. Fica registrada na solicitação e no histórico do pedido.

POST/api/v1/admin/order-cancellations/{id}/rejectAdmin

Rejeita 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ório

Id da solicitação.

Corpo da requisição (opcional)

reasonstring

Justificativa mostrada ao cliente, até 2000 caracteres.

Exemplo de requisição

bash

# Fila de solicitações pendentes
curl "$BASE_URL/api/v1/admin/order-cancellations?status=pending" \
  -H "Authorization: Bearer $TOKEN"

# Aprovar
curl -X POST "$BASE_URL/api/v1/admin/order-cancellations/$REQUEST_ID/approve" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"reason":"Pedido ainda não separado"}'

# Recusar
curl -X POST "$BASE_URL/api/v1/admin/order-cancellations/$REQUEST_ID/reject" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"reason":"Pedido já saiu para entrega"}'

Resposta

200Lista de solicitações

json

{
  "requests": [
    {
      "id": "7c1d3f50-52a8-4a43-9a6d-1d8ee3a0c2b4",
      "order_id": "e148b6aa-d495-4b89-92ab-f38b5979a43f",
      "order_number": "PEDIDO-20261011-0001",
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "customer_id": "f12f30a9-cbec-40ba-98f1-b7fa8f2e8e10",
      "customer_name": "Maria Souza",
      "customer_email": "maria.souza@example.com",
      "status": "pending",
      "processing_mode": "review",
      "request_reason": "Comprei o produto errado",
      "requested_by": "f12f30a9-cbec-40ba-98f1-b7fa8f2e8e10",
      "previous_order_status": "P",
      "refund_requested": true,
      "refund_completed": false,
      "created_at": "2026-10-11T21:30:00Z",
      "updated_at": "2026-10-11T21:30:00Z"
    }
  ]
}

200Solicitação aprovada

json

{
  "request": {
    "id": "7c1d3f50-52a8-4a43-9a6d-1d8ee3a0c2b4",
    "order_id": "e148b6aa-d495-4b89-92ab-f38b5979a43f",
    "status": "approved",
    "decision_reason": "Pedido ainda não separado",
    "decided_by": "d4613dde-ac7a-431c-9232-50d8cd6ad5fc",
    "resulting_order_status": "cancelled",
    "refund_requested": true,
    "refund_completed": true,
    "refund_amount": 192895,
    "refund_reference": "re_9Vq2kLxYzNwB41pD",
    "refund_confirmed_at": "2026-10-11T21:40:12Z",
    "decided_at": "2026-10-11T21:40:12Z"
  }
}

Campos da resposta

requestsarray

Solicitações encontradas.

requestobject

(approve/reject) A solicitação depois da decisão.

idempotentboolean

(approve/reject) true quando a solicitação já tinha sido decidida e nada foi feito agora.

iduuid

Id da solicitação.

order_iduuid

Pedido a cancelar.

order_numberstring

Número do pedido.

vendor_iduuid

Seller do pedido, quando há.

customer_iduuid

Cliente que pediu.

customer_namestring

Nome do cliente.

customer_emailstring

E-mail do cliente.

statusstring

pendingprocessingapprovedauto_approvedrejected

Situação da solicitação.

processing_modestring

reviewautomatic

Como a política tratou o pedido: review (precisa de decisão de alguém da loja) ou automatic (cancelado na hora).

request_reasonstring

Motivo informado pelo cliente.

decision_reasonstring

Justificativa de quem decidiu.

requested_byuuid

Quem abriu a solicitação.

decided_byuuid

Quem decidiu.

previous_order_statusstring

Letra do status do pedido quando a solicitação foi aberta.

requested_order_statusstring

Status para o qual a solicitação moveu o pedido enquanto aguardava, quando a política faz isso.

resulting_order_statusstring

Status final do pedido depois da decisão.

refund_requestedboolean

true quando o cliente pediu o dinheiro de volta.

refund_completedboolean

true quando o estorno foi confirmado.

refund_amountinteger

Valor estornado em centavos.

refund_referencestring

Identificador do estorno no gateway.

refund_confirmed_atstring

Quando o estorno foi confirmado. RFC 3339.

refund_confirmed_byuuid

Quem confirmou o estorno (quando foi manual).

failure_codestring

Motivo, quando o estorno não pôde ser confirmado (por exemplo refund_unconfirmed ou cancellation_failed).

created_atstring

Abertura. RFC 3339.

decided_atstring

Decisão. RFC 3339.

updated_atstring

Última alteração. RFC 3339.

Erros

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"}`

Veja também

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.

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.

GET/api/v1/admin/order-cancellationsAdmin

Lista 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: pending

pendingapprovedrejected

Filtro de situação. pending inclui as que estão em processing; approved inclui as auto_approved. Omitido, ou vazio, vale pending.

POST/api/v1/admin/order-cancellations/{id}/approveAdmin

Aprova uma solicitação de cancelamento

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ório

Id da solicitação (campo id da lista, não o id do pedido).

Corpo da requisição (opcional)

reasonstring

Justificativa da decisão, até 2000 caracteres. Fica registrada na solicitação e no histórico do pedido.

POST/api/v1/admin/order-cancellations/{id}/rejectAdmin

Rejeita uma solicitação de cancelamento

Path parameters

iduuidobrigatório

Id da solicitação.

Corpo da requisição (opcional)

reasonstring

Justificativa mostrada ao cliente, até 2000 caracteres.

Exemplo de requisição

bash

# Fila de solicitações pendentes
curl "$BASE_URL/api/v1/admin/order-cancellations?status=pending" \
  -H "Authorization: Bearer $TOKEN"

# Aprovar
curl -X POST "$BASE_URL/api/v1/admin/order-cancellations/$REQUEST_ID/approve" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"reason":"Pedido ainda não separado"}'

# Recusar
curl -X POST "$BASE_URL/api/v1/admin/order-cancellations/$REQUEST_ID/reject" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"reason":"Pedido já saiu para entrega"}'

Resposta

200Lista de solicitações

json

{
  "requests": [
    {
      "id": "7c1d3f50-52a8-4a43-9a6d-1d8ee3a0c2b4",
      "order_id": "e148b6aa-d495-4b89-92ab-f38b5979a43f",
      "order_number": "PEDIDO-20261011-0001",
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "customer_id": "f12f30a9-cbec-40ba-98f1-b7fa8f2e8e10",
      "customer_name": "Maria Souza",
      "customer_email": "maria.souza@example.com",
      "status": "pending",
      "processing_mode": "review",
      "request_reason": "Comprei o produto errado",
      "requested_by": "f12f30a9-cbec-40ba-98f1-b7fa8f2e8e10",
      "previous_order_status": "P",
      "refund_requested": true,
      "refund_completed": false,
      "created_at": "2026-10-11T21:30:00Z",
      "updated_at": "2026-10-11T21:30:00Z"
    }
  ]
}

200Solicitação aprovada

json

{
  "request": {
    "id": "7c1d3f50-52a8-4a43-9a6d-1d8ee3a0c2b4",
    "order_id": "e148b6aa-d495-4b89-92ab-f38b5979a43f",
    "status": "approved",
    "decision_reason": "Pedido ainda não separado",
    "decided_by": "d4613dde-ac7a-431c-9232-50d8cd6ad5fc",
    "resulting_order_status": "cancelled",
    "refund_requested": true,
    "refund_completed": true,
    "refund_amount": 192895,
    "refund_reference": "re_9Vq2kLxYzNwB41pD",
    "refund_confirmed_at": "2026-10-11T21:40:12Z",
    "decided_at": "2026-10-11T21:40:12Z"
  }
}

Campos da resposta

requestsarray

Solicitações encontradas.

requestobject

(approve/reject) A solicitação depois da decisão.

idempotentboolean

(approve/reject) true quando a solicitação já tinha sido decidida e nada foi feito agora.

iduuid

Id da solicitação.

order_iduuid

Pedido a cancelar.

order_numberstring

Número do pedido.

vendor_iduuid

Seller do pedido, quando há.

customer_iduuid

Cliente que pediu.

customer_namestring

Nome do cliente.

customer_emailstring

E-mail do cliente.

statusstring

pendingprocessingapprovedauto_approvedrejected

Situação da solicitação.

processing_modestring

reviewautomatic

Como a política tratou o pedido: review (precisa de decisão de alguém da loja) ou automatic (cancelado na hora).

request_reasonstring

Motivo informado pelo cliente.

decision_reasonstring

Justificativa de quem decidiu.

requested_byuuid

Quem abriu a solicitação.

decided_byuuid

Quem decidiu.

previous_order_statusstring

Letra do status do pedido quando a solicitação foi aberta.

requested_order_statusstring

Status para o qual a solicitação moveu o pedido enquanto aguardava, quando a política faz isso.

resulting_order_statusstring

Status final do pedido depois da decisão.

refund_requestedboolean

true quando o cliente pediu o dinheiro de volta.

refund_completedboolean

true quando o estorno foi confirmado.

refund_amountinteger

Valor estornado em centavos.

refund_referencestring

Identificador do estorno no gateway.

refund_confirmed_atstring

Quando o estorno foi confirmado. RFC 3339.

refund_confirmed_byuuid

Quem confirmou o estorno (quando foi manual).

failure_codestring

Motivo, quando o estorno não pôde ser confirmado (por exemplo refund_unconfirmed ou cancellation_failed).

created_atstring

Abertura. RFC 3339.

decided_atstring

Decisão. RFC 3339.

updated_atstring

Última alteração. RFC 3339.

Erros

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"}`