VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Pedidos

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

statusSignificado
pendingAguardando decisão.
processingAprovação em andamento (o estorno e a mudança de status estão sendo feitos). Na lista, aparece junto com pending.
approvedAprovada por alguém da loja; o pedido foi cancelado.
auto_approvedCancelada automaticamente pela política da loja. Na lista, aparece junto com approved.
rejectedRecusada; 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

Resposta

200Lista de solicitações
200Solicitação aprovada

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

StatusQuandoCorpo
400Corpo inválido{"error":"invalid request body"}
401Sem credenciais ou token expirado{"error":"invalid or expired token"}
403Sem permissão{"error":"insufficient privileges","required":"manage_orders"}
404Solicitação não encontrada{"error":"cancellation request not found"}
409O 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"}
502O 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"}
500Falha interna{"error":"failed to complete cancellation decision"}
Use o id da solicitação, não o do pedido

approve e reject recebem o id da solicitação (o id de cada item da lista), e não o order_id. Mandar o id do pedido devolve 404 cancellation request not found.

O que aprovar significa para o dinheiro

O estorno automático só acontece quando a loja ligou essa opção na política de cancelamento e o cliente marcou que quer o reembolso (refund_requested). Sem isso, a aprovação cancela o pedido e o reembolso precisa ser feito à parte (veja Reembolsos). Confira refund_completed na resposta.

Veja também

  • Reembolsos
  • Cancelar e excluir pedido
  • Alterar o status
Anterior
Reembolsos
Próxima
Fatura e NF-e
Nesta página
  • Situação de uma solicitação
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também
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"}'
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"
    }
  ]
}
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"
  }
}