API atual/Referência completa/Devoluções

Decisões sobre devoluções

Aprova ou recusa uma devolução e avança o estado até o reembolso e o encerramento.

Duas operações mudam o rumo de uma devolução. Processar é a decisão inicial (aprovar ou recusar) e o único lugar onde você define o valor do reembolso e a resolução. Atualizar avança os estados seguintes: recebido, reembolsado, encerrado. Ambas exigem manage_returns ou manage_orders e o módulo de devoluções.

Processar uma devolução

Aprova ou recusa uma devolução que está em requested. Ao aprovar, a plataforma também cria o envio de devolução por seller e, se a logística reversa automática estiver ligada no módulo, pede a autorização de postagem ao transportador em segundo plano. Em qualquer caso um evento de mudança de estado é publicado para integrações.

POST/api/v1/admin/returns/{id}/processAdmin

Aprova ou recusa uma devolução

Parâmetros de caminho

iduuidobrigatório

Id da devolução.

Corpo da requisição

actionstringobrigatório

approvereject

approve leva a devolução para approved; reject leva para rejected.

admin_notesstring

Observação interna. Substitui a anterior. Quando a ação é recusar, é um bom lugar para o motivo.

resolutionstring

refundreplacementstore_credit

Sobrescreve a resolução pedida pelo cliente. Valor fora da lista é ignorado em silêncio.

refund_amountinteger

Valor a reembolsar, em centavos. Obrigatório na prática se você pretende reembolsar depois: sem ele a devolução fica com 0 e não pode ir a refunded.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/returns/2f495c2f-dab7-4580-8004-54e39fa56c75/process" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "approve",
    "admin_notes": "Defeito confirmado",
    "resolution": "refund",
    "refund_amount": 4990
  }'

Resposta

200Devolução decidida

json

{
  "id": "2f495c2f-dab7-4580-8004-54e39fa56c75",
  "order_id": "615b4147-6cb2-4057-9e25-ee82281b9d68",
  "customer_id": "220b672c-90fe-4841-ae86-bd4f1ace982e",
  "status": "approved",
  "admin_notes": "Defeito confirmado",
  "resolution": "refund",
  "refund_amount": 4990,
  "quantity": 1,
  "processed_at": "2026-10-11T22:10:00Z",
  "processed_by": "ec5e10b3-8cb1-43e9-9aa8-964b64eda8de",
  "reverse_status": "none",
  "refund_destination": "original"
}

A resposta é a devolução completa, no formato descrito em Solicitações; o exemplo está abreviado. Se a logística reversa automática está ligada, reverse_status ainda pode estar none ou requested na resposta, porque a emissão corre em segundo plano.

Erros

Status	Quando	Corpo
400	Corpo inválido	`{"error":"invalid request body","detail":"..."}`
400	`action` vazia	`{"error":"action is required (approve or reject)"}`
400	`action` diferente de `approve` e `reject`	`{"error":"failed to process return","detail":"invalid action: x (must be 'approve' or 'reject')"}`
400	Devolução fora de `requested`	`{"error":"failed to process return","detail":"cannot approve a return in 'closed' status"}`
400	Devolução inexistente	`{"error":"failed to process return","detail":"return not found"}`
401 / 403	Sem token, sem privilégio, ou módulo desligado	`{"error":"module_disabled","module":"returns"}`

Atualizar o estado

Avança a devolução pelo fluxo. Use para marcar que o produto chegou (item_received), para reembolsar (refunded) e para encerrar (closed). Também aceita cancelled a partir de requested ou approved. Só são aceitas as transições da tabela do índice; qualquer outra volta 400.

Ao ir para refunded, a plataforma devolve o dinheiro: se o refund_destination for wallet, credita a carteira do cliente; se for original, pede o estorno ao gateway de pagamento do pedido. Só depois do sucesso o estado muda. A resposta guarda o id do estorno em refund_txn_id.

PUT/api/v1/admin/returns/{id}Admin

Avança o estado de uma devolução

Parâmetros de caminho

iduuidobrigatório

Id da devolução.

Corpo da requisição

statusstringobrigatório

approveditem_receivedrefundedrejectedclosedcancelled

Novo estado, pela palavra (não a letra). Precisa ser uma transição permitida a partir do estado atual.

admin_notesstring

Observação interna. Se vazia, a observação atual é mantida.

restockbooleanpadrão: true

Informa aos módulos de estoque se o item volta ao estoque vendável quando o estado muda. Envie false para item danificado ou com defeito. Só tem efeito na chegada do produto.

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/admin/returns/2f495c2f-dab7-4580-8004-54e39fa56c75" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status": "refunded", "admin_notes": "Reembolso integral"}'

Resposta

200Estado atualizado

json

{
  "id": "2f495c2f-dab7-4580-8004-54e39fa56c75",
  "status": "refunded",
  "admin_notes": "Reembolso integral",
  "resolution": "refund",
  "refund_amount": 4990,
  "refund_txn_id": "re_1Nxyz",
  "processed_at": "2026-10-11T22:30:00Z",
  "processed_by": "ec5e10b3-8cb1-43e9-9aa8-964b64eda8de",
  "refund_destination": "original"
}

A resposta é a devolução completa; o exemplo está abreviado.

Erros

Status	Quando	Corpo
400	Corpo inválido	`{"error":"invalid request body","detail":"..."}`
400	`status` vazio	`{"error":"status is required"}`
400	Transição não permitida	`{"error":"failed to update return","detail":"invalid status transition from 'requested' to 'refunded'"}`
400	Ir a `refunded` com `refund_amount` zerado	`{"error":"failed to update return","detail":"cannot refund return ...: refund_amount is zero (set refund_amount via ProcessReturn before transitioning to refunded)"}`
400	Devolução inexistente	`{"error":"failed to update return","detail":"return not found"}`
400	Falha ao creditar a carteira	`{"error":"failed to update return","detail":"wallet credit failed: ..."}`
502	O gateway recusou o estorno. O estado não mudou	`{"error":"refund could not be processed at this time ...","detail":"the return remains in its current status; please retry or issue a manual refund"}`

Veja também

API atual/Referência completa/Devoluções

Decisões sobre devoluções

Aprova ou recusa uma devolução e avança o estado até o reembolso e o encerramento.

Processar uma devolução

POST/api/v1/admin/returns/{id}/processAdmin

Aprova ou recusa uma devolução

Parâmetros de caminho

iduuidobrigatório

Id da devolução.

Corpo da requisição

actionstringobrigatório

approvereject

approve leva a devolução para approved; reject leva para rejected.

admin_notesstring

Observação interna. Substitui a anterior. Quando a ação é recusar, é um bom lugar para o motivo.

resolutionstring

refundreplacementstore_credit

Sobrescreve a resolução pedida pelo cliente. Valor fora da lista é ignorado em silêncio.

refund_amountinteger

Valor a reembolsar, em centavos. Obrigatório na prática se você pretende reembolsar depois: sem ele a devolução fica com 0 e não pode ir a refunded.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/returns/2f495c2f-dab7-4580-8004-54e39fa56c75/process" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "approve",
    "admin_notes": "Defeito confirmado",
    "resolution": "refund",
    "refund_amount": 4990
  }'

Resposta

200Devolução decidida

json

{
  "id": "2f495c2f-dab7-4580-8004-54e39fa56c75",
  "order_id": "615b4147-6cb2-4057-9e25-ee82281b9d68",
  "customer_id": "220b672c-90fe-4841-ae86-bd4f1ace982e",
  "status": "approved",
  "admin_notes": "Defeito confirmado",
  "resolution": "refund",
  "refund_amount": 4990,
  "quantity": 1,
  "processed_at": "2026-10-11T22:10:00Z",
  "processed_by": "ec5e10b3-8cb1-43e9-9aa8-964b64eda8de",
  "reverse_status": "none",
  "refund_destination": "original"
}

Erros

Status	Quando	Corpo
400	Corpo inválido	`{"error":"invalid request body","detail":"..."}`
400	`action` vazia	`{"error":"action is required (approve or reject)"}`
400	`action` diferente de `approve` e `reject`	`{"error":"failed to process return","detail":"invalid action: x (must be 'approve' or 'reject')"}`
400	Devolução fora de `requested`	`{"error":"failed to process return","detail":"cannot approve a return in 'closed' status"}`
400	Devolução inexistente	`{"error":"failed to process return","detail":"return not found"}`
401 / 403	Sem token, sem privilégio, ou módulo desligado	`{"error":"module_disabled","module":"returns"}`

Atualizar o estado

PUT/api/v1/admin/returns/{id}Admin

Avança o estado de uma devolução

Parâmetros de caminho

iduuidobrigatório

Id da devolução.

Corpo da requisição

statusstringobrigatório

approveditem_receivedrefundedrejectedclosedcancelled

Novo estado, pela palavra (não a letra). Precisa ser uma transição permitida a partir do estado atual.

admin_notesstring

Observação interna. Se vazia, a observação atual é mantida.

restockbooleanpadrão: true

Informa aos módulos de estoque se o item volta ao estoque vendável quando o estado muda. Envie false para item danificado ou com defeito. Só tem efeito na chegada do produto.

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/admin/returns/2f495c2f-dab7-4580-8004-54e39fa56c75" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status": "refunded", "admin_notes": "Reembolso integral"}'

Resposta

200Estado atualizado

json

{
  "id": "2f495c2f-dab7-4580-8004-54e39fa56c75",
  "status": "refunded",
  "admin_notes": "Reembolso integral",
  "resolution": "refund",
  "refund_amount": 4990,
  "refund_txn_id": "re_1Nxyz",
  "processed_at": "2026-10-11T22:30:00Z",
  "processed_by": "ec5e10b3-8cb1-43e9-9aa8-964b64eda8de",
  "refund_destination": "original"
}

A resposta é a devolução completa; o exemplo está abreviado.

Erros

Status	Quando	Corpo
400	Corpo inválido	`{"error":"invalid request body","detail":"..."}`
400	`status` vazio	`{"error":"status is required"}`
400	Transição não permitida	`{"error":"failed to update return","detail":"invalid status transition from 'requested' to 'refunded'"}`
400	Ir a `refunded` com `refund_amount` zerado	`{"error":"failed to update return","detail":"cannot refund return ...: refund_amount is zero (set refund_amount via ProcessReturn before transitioning to refunded)"}`
400	Devolução inexistente	`{"error":"failed to update return","detail":"return not found"}`
400	Falha ao creditar a carteira	`{"error":"failed to update return","detail":"wallet credit failed: ..."}`
502	O gateway recusou o estorno. O estado não mudou	`{"error":"refund could not be processed at this time ...","detail":"the return remains in its current status; please retry or issue a manual refund"}`