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

POSTPedir devolução

Abre uma devolução de um pedido entregue, com motivo, resolução e destino do reembolso.

Abre uma devolução de um pedido entregue: o cliente escolhe a linha (ou o pedido todo), o motivo, o que quer receber e, se a loja pedir, anexa fotos. A devolução nasce requested e a loja (ou o seller) decide. Antes de mostrar o botão, consulte a política para saber o prazo e se o motivo é obrigatório.

POST/api/v1/storefront/orders/{orderId}/returnCliente

Abre uma devolução de um pedido do cliente

Parâmetros de caminho

orderIduuidobrigatório

Id do pedido. Precisa ser do cliente (customer_id); caso contrário a resposta é 400 com "order not found or does not belong to this customer".

Corpo da requisição

order_item_iduuid

Linha do pedido a devolver (o items[].id de Consultar pedido). Sem ela, a devolução é do pedido todo.

reason_iduuid

Motivo da lista de motivos.

reasonstring

Motivo em texto livre. Quando a loja exige motivo, mande este campo ou reason_id.

customer_notesstring

Detalhes do cliente para a loja.

resolutionstringpadrão: refund

refundreplacementstore_credit

O que o cliente quer receber.

quantityintegerpadrão: 1

Unidades a devolver. Valor menor que 1 vira 1.

refund_destinationstringpadrão: original

originalwallet

Para onde vai o reembolso. Qualquer outro valor vale original.

imagesarray

URLs de fotos de evidência, já enviadas antes pelo envio de mídia da loja (a devolução recebe só as URLs, nunca o arquivo). Algumas categorias de produto exigem fotos.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/storefront/orders/$ORDER_ID/return" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "order_item_id": "a43b9f10-5590-424b-87c8-dffa34bae43d",
  "reason_id": "0bc9dc6e-3655-44bc-96ba-b2645336a403",
  "customer_notes": "A caneca chegou trincada.",
  "resolution": "refund",
  "quantity": 1,
  "refund_destination": "original"
}'

Resposta

201Devolução aberta

json

{
  "id": "6f986d87-2541-4f6e-b7fb-ee1dafde286d",
  "order_id": "6af86ed3-d949-474d-8e04-513c6e83bfe4",
  "order_item_id": "a43b9f10-5590-424b-87c8-dffa34bae43d",
  "customer_id": "264a70c1-9c69-458d-ac73-838543f87da2",
  "vendor_id": "9d9d9d56-eb43-4719-889d-055632f7c7da",
  "reason_id": "0bc9dc6e-3655-44bc-96ba-b2645336a403",
  "reason": "",
  "status": "requested",
  "admin_notes": "",
  "customer_notes": "A caneca chegou trincada.",
  "resolution": "refund",
  "refund_amount": 0,
  "quantity": 1,
  "refund_destination": "original",
  "reverse_status": "none",
  "order_number": "PEDIDO-20261011-0009",
  "product_name": "Caneca Exemplo",
  "reason_name": "Defective product",
  "created_at": "2026-10-11T21:06:56.061306Z",
  "updated_at": "2026-10-11T21:06:56.061306Z"
}

Campos da resposta

iduuid

Id da devolução.

order_iduuid

Pedido de origem. order_number traz o número para exibir.

order_item_iduuid

Linha do pedido devolvida. Ausente quando a devolução cobre o pedido todo.

vendor_iduuid

Seller que vai analisar e receber. Ausente se não foi possível determiná-lo.

reason_iduuid

Motivo escolhido da lista de motivos. reason_name traz o nome, e reason o texto livre, se houver.

statusstring

requestedapproveditem_receivedrefundedrejectedclosedcancelled

Situação da devolução (veja o ciclo na home da seção).

resolutionstring

refundreplacementstore_credit

O que o cliente quer receber: reembolso, troca ou crédito na loja.

quantityinteger

Unidades devolvidas.

refund_amountinteger

Valor reembolsado, em centavos. É 0 até a loja aprovar e conferir a mercadoria.

refund_destinationstring

originalwallet

Para onde vai o dinheiro: original (mesma forma de pagamento) ou wallet (crédito na carteira da loja, com bônus se a loja oferecer). Não muda depois de aprovada.

customer_notesstring

O que o cliente escreveu. admin_notes é a resposta da loja.

reverse_statusstring

Situação da logística reversa (o caminho de volta do produto): none quando ainda não há. Com a reversa ativa, vêm também reverse_authorization_code, reverse_tracking_code, reverse_label_url (etiqueta para imprimir) e reverse_cost_cents. Os eventos estão em Acompanhar devoluções.

imagesarray

URLs das fotos de evidência enviadas. triage traz o resultado da análise automática das fotos, quando a loja usa.

created_atstring

Criação, RFC 3339. updated_at é a última alteração e processed_at o momento da decisão da loja.

Erros

Status	Quando	Corpo
400	Corpo que não é JSON	`{"error":"invalid request body","detail":"..."}`
400	Regra de negócio: pedido que não é seu, status não elegível (precisa ser entregue/concluído), janela vencida, motivo ausente, já existe devolução ativa, linha que não é do pedido, resolução inválida	`{"error":"create_return_failed","detail":"order status 'O' is not eligible for returns (must be delivered or completed)"}`
401	Sem token, ou token inválido ou expirado	`{"error":"missing authorization header"}` / `{"error":"invalid or expired token"}`
403	Módulo `returns` desligado na loja	`{"error":"module_disabled","module":"returns"}`
422	A categoria do produto exige fotos de evidência	`{"error":"return_photos_required","detail":"Evidence photos are required for this category."}`

Veja também

POSTPedir devolução

Abre uma devolução de um pedido entregue, com motivo, resolução e destino do reembolso.

POST/api/v1/storefront/orders/{orderId}/returnCliente

Abre uma devolução de um pedido do cliente

Parâmetros de caminho

orderIduuidobrigatório

Id do pedido. Precisa ser do cliente (customer_id); caso contrário a resposta é 400 com "order not found or does not belong to this customer".

Corpo da requisição

order_item_iduuid

Linha do pedido a devolver (o items[].id de Consultar pedido). Sem ela, a devolução é do pedido todo.

reason_iduuid

Motivo da lista de motivos.

reasonstring

Motivo em texto livre. Quando a loja exige motivo, mande este campo ou reason_id.

customer_notesstring

Detalhes do cliente para a loja.

resolutionstringpadrão: refund

refundreplacementstore_credit

O que o cliente quer receber.

quantityintegerpadrão: 1

Unidades a devolver. Valor menor que 1 vira 1.

refund_destinationstringpadrão: original

originalwallet

Para onde vai o reembolso. Qualquer outro valor vale original.

imagesarray

URLs de fotos de evidência, já enviadas antes pelo envio de mídia da loja (a devolução recebe só as URLs, nunca o arquivo). Algumas categorias de produto exigem fotos.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/storefront/orders/$ORDER_ID/return" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "order_item_id": "a43b9f10-5590-424b-87c8-dffa34bae43d",
  "reason_id": "0bc9dc6e-3655-44bc-96ba-b2645336a403",
  "customer_notes": "A caneca chegou trincada.",
  "resolution": "refund",
  "quantity": 1,
  "refund_destination": "original"
}'

Resposta

201Devolução aberta

json

{
  "id": "6f986d87-2541-4f6e-b7fb-ee1dafde286d",
  "order_id": "6af86ed3-d949-474d-8e04-513c6e83bfe4",
  "order_item_id": "a43b9f10-5590-424b-87c8-dffa34bae43d",
  "customer_id": "264a70c1-9c69-458d-ac73-838543f87da2",
  "vendor_id": "9d9d9d56-eb43-4719-889d-055632f7c7da",
  "reason_id": "0bc9dc6e-3655-44bc-96ba-b2645336a403",
  "reason": "",
  "status": "requested",
  "admin_notes": "",
  "customer_notes": "A caneca chegou trincada.",
  "resolution": "refund",
  "refund_amount": 0,
  "quantity": 1,
  "refund_destination": "original",
  "reverse_status": "none",
  "order_number": "PEDIDO-20261011-0009",
  "product_name": "Caneca Exemplo",
  "reason_name": "Defective product",
  "created_at": "2026-10-11T21:06:56.061306Z",
  "updated_at": "2026-10-11T21:06:56.061306Z"
}

Campos da resposta

iduuid

Id da devolução.

order_iduuid

Pedido de origem. order_number traz o número para exibir.

order_item_iduuid

Linha do pedido devolvida. Ausente quando a devolução cobre o pedido todo.

vendor_iduuid

Seller que vai analisar e receber. Ausente se não foi possível determiná-lo.

reason_iduuid

Motivo escolhido da lista de motivos. reason_name traz o nome, e reason o texto livre, se houver.

statusstring

requestedapproveditem_receivedrefundedrejectedclosedcancelled

Situação da devolução (veja o ciclo na home da seção).

resolutionstring

refundreplacementstore_credit

O que o cliente quer receber: reembolso, troca ou crédito na loja.

quantityinteger

Unidades devolvidas.

refund_amountinteger

Valor reembolsado, em centavos. É 0 até a loja aprovar e conferir a mercadoria.

refund_destinationstring

originalwallet

Para onde vai o dinheiro: original (mesma forma de pagamento) ou wallet (crédito na carteira da loja, com bônus se a loja oferecer). Não muda depois de aprovada.

customer_notesstring

O que o cliente escreveu. admin_notes é a resposta da loja.

reverse_statusstring

imagesarray

URLs das fotos de evidência enviadas. triage traz o resultado da análise automática das fotos, quando a loja usa.

created_atstring

Criação, RFC 3339. updated_at é a última alteração e processed_at o momento da decisão da loja.

Erros

Status	Quando	Corpo
400	Corpo que não é JSON	`{"error":"invalid request body","detail":"..."}`
400	Regra de negócio: pedido que não é seu, status não elegível (precisa ser entregue/concluído), janela vencida, motivo ausente, já existe devolução ativa, linha que não é do pedido, resolução inválida	`{"error":"create_return_failed","detail":"order status 'O' is not eligible for returns (must be delivered or completed)"}`
401	Sem token, ou token inválido ou expirado	`{"error":"missing authorization header"}` / `{"error":"invalid or expired token"}`
403	Módulo `returns` desligado na loja	`{"error":"module_disabled","module":"returns"}`
422	A categoria do produto exige fotos de evidência	`{"error":"return_photos_required","detail":"Evidence photos are required for this category."}`