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

Cancelamentos pedidos pelo cliente

Lista as solicitações de cancelamento dos pedidos do seller e aprova ou recusa cada uma.

Quando o cliente pede para cancelar uma compra, a loja segue a política que 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. Quem decide é o seller dono do pedido (ou a loja): aprova ou recusa.

Estas rotas são a fila dessa revisão para o seller. Quem abre o pedido de cancelamento é o cliente, pela vitrine; o seller lista as solicitações e decide. O seller enxerga as solicitações dos pedidos dele, inclusive as feitas sobre o pedido pai de uma compra em que ele tem um sub-pedido.

Situação de uma solicitação

statusSignificado
pendingAguardando decisão.
processingAprovação em andamento (estorno e mudança de status sendo feitos). Na lista, aparece junto com pending.
approvedAprovada; 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.

Listar as solicitações

GET/api/v1/vendor/order-cancellationsSeller

Lista as solicitações de cancelamento do seller

Lista até 200 solicitações, da mais recente para a mais antiga. Exige um privilégio de pedidos do seller.

Parâmetros de consulta

statusstringpadrão: pending
pendingapprovedrejected
Filtro de situação. pending inclui as processing; approved inclui as auto_approved. Omitido ou vazio vale pending: não existe valor que traga todas.

Exemplo de requisição: listar

bash
curl "$BASE_URL/api/v1/vendor/order-cancellations?status=pending" \
  -H "Authorization: Bearer $TOKEN"

Resposta: listar

200Solicitações de cancelamento
json
{
  "requests": [
    {
      "id": "7c1d3f50-52a8-4a43-9a6d-1d8ee3a0c2b4",
      "order_id": "e148b6aa-d495-4b89-92ab-f38b5979a43f",
      "order_number": "PEDIDO-20261011-0001-V1",
      "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"
    }
  ]
}

Campos da resposta

requestsarray
Solicitações encontradas. Lista vazia ([]) quando não há nenhuma.
requests[].iduuid
Id da solicitação. É o que approve e reject recebem.
requests[].order_iduuid
Pedido a cancelar.
requests[].order_numberstring
Número do pedido.
requests[].vendor_iduuid
Seller do pedido, quando há.
requests[].customer_iduuid
Cliente que pediu.
requests[].customer_namestring
Nome do cliente.
requests[].customer_emailstring
E-mail do cliente.
requests[].statusstring
pendingprocessingapprovedauto_approvedrejected
Situação da solicitação.
requests[].processing_modestring
reviewautomatic
review (precisa de decisão) ou automatic (cancelado na hora).
requests[].request_reasonstring
Motivo informado pelo cliente.
requests[].decision_reasonstring
Justificativa de quem decidiu.
requests[].requested_byuuid
Quem abriu a solicitação.
requests[].decided_byuuid
Quem decidiu.
requests[].previous_order_statusstring
Letra do status do pedido quando a solicitação foi aberta.
requests[].requested_order_statusstring
Status para o qual a solicitação moveu o pedido enquanto aguardava, quando a política faz isso.
requests[].resulting_order_statusstring
Status final do pedido depois da decisão.
requests[].refund_requestedboolean
true quando o cliente pediu o dinheiro de volta.
requests[].refund_completedboolean
true quando o estorno foi confirmado.
requests[].refund_amountinteger
Valor estornado, em centavos.
requests[].refund_referencestring
Identificador do estorno no gateway.
requests[].failure_codestring
Motivo, quando o estorno não pôde ser confirmado (por exemplo refund_unconfirmed ou cancellation_failed).
requests[].created_atstring (RFC 3339)
Abertura.
requests[].decided_atstring (RFC 3339)
Decisão.
requests[].updated_atstring (RFC 3339)
Última alteração.

Aprovar uma solicitação

POST/api/v1/vendor/order-cancellations/{id}/approveSeller

Aprova uma solicitação de cancelamento

Aprova a solicitação: o pedido é movido para o status de cancelamento que a loja configurou 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 um dos dois falhar, nada é cancelado, a solicitação volta a pending e a resposta é 502. Exige o privilégio de gerenciar pedidos do seller.

A chamada é idempotente: decidir uma solicitação que já foi decidida devolve 200 com a solicitação como está e "idempotent": true.

Parâmetros de caminho

iduuidobrigatório
Id da solicitação (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 na solicitação e no histórico do pedido.

Recusar uma solicitação

POST/api/v1/vendor/order-cancellations/{id}/rejectSeller

Recusa 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. Sem reason, vale o texto padrão "Solicitação não aprovada. Entre em contato com o seller em caso de dúvida." Exige o privilégio de gerenciar pedidos do seller.

Parâmetros de caminho

iduuidobrigatório
Id da solicitação.

Corpo da requisição (opcional)

reasonstring
Justificativa mostrada ao cliente, até 2000 caracteres.

Exemplo de requisição: decidir

bash
# Aprovar
curl -X POST "$BASE_URL/api/v1/vendor/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/vendor/order-cancellations/$REQUEST_ID/reject" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Pedido já saiu para entrega" }'

Resposta: decidir

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": 24000,
    "refund_reference": "re_9Vq2kLxYzNwB41pD",
    "decided_at": "2026-10-11T21:40:12Z"
  }
}

Campos da resposta

requestobject
A solicitação depois da decisão, com os campos descritos na lista.
idempotentboolean | omitted
true quando a solicitação já tinha sido decidida e nada foi feito agora.

Erros

StatusQuandoCorpo de exemplo
401Token ausente ou inválido.{"error":"missing authorization header"}
403O token não é de um usuário seller, ou ele não tem privilégio de pedidos (para decidir, o de gerenciar pedidos).{"error":"insufficient vendor privileges","privilege_required_any":["vendor_orders", "vendor_manage_orders"]}
403O usuário não está ligado a nenhum seller.{"error":"no vendor account associated with this user"}
400Corpo que não é JSON.{"error":"invalid request body"}
404A solicitação não existe ou não é dos pedidos do seller.{"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. 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 pediu o reembolso (refund_requested). Sem isso, a aprovação cancela o pedido e o reembolso precisa ser feito à parte. Confira refund_completed na resposta.

Veja também

  • Mudar o status do pedido
  • Devoluções
  • Visão geral
Anterior
Acompanhamento do pedido
Próxima
Devoluções do seller
Nesta página
  • Situação de uma solicitação
  • Listar as solicitações
  • Exemplo de requisição: listar
  • Resposta: listar
  • Aprovar uma solicitação
  • Recusar uma solicitação
  • Exemplo de requisição: decidir
  • Resposta: decidir
  • Erros
  • Veja também