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

Acompanhar devoluções

Lista, consulta e cancela devoluções do cliente e vê a logística reversa.

Quatro rotas para o cliente acompanhar o que pediu: a lista das devoluções, o detalhe de uma, o cancelamento enquanto a loja ainda não decidiu e a linha do tempo da logística reversa (o caminho de volta do produto). Todas só enxergam devoluções do próprio cliente.

GET/api/v1/storefront/returnsCliente

Lista as devoluções do cliente

Parâmetros de consulta

pageintegerpadrão: 1

Página, a partir de 1.

per_pageintegerpadrão: 20

Itens por página.

bash

curl "$BASE_URL/api/v1/storefront/returns?page=1&per_page=20" \
  -H "Authorization: Bearer $TOKEN"

200Devoluções do cliente

json

{
  "returns": [
    {
      "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"
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 20,
  "total_pages": 1
}

Cada item tem os campos descritos em Pedir devolução. returns vem como lista vazia quando o cliente não tem nenhuma.

Status	Quando	Corpo
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"}`
500	Falha ao listar	`{"error":"failed to list returns","detail":"..."}`

GET/api/v1/storefront/returns/{id}Cliente

Detalhe de uma devolução

Parâmetros de caminho

iduuidobrigatório

Id da devolução.

bash

curl "$BASE_URL/api/v1/storefront/returns/$RETURN_ID" \
  -H "Authorization: Bearer $TOKEN"

200Devolução

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

Status	Quando	Corpo
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"}`
404	Devolução inexistente, ou que não é sua	`{"error":"return not found"}`
500	`id` que não é UUID (a plataforma responde 500 em vez de 400) ou falha interna	`{"error":"failed to get return","detail":"..."}`

DELETE/api/v1/storefront/returns/{id}Cliente

Cancela uma devolução ainda solicitada

O cliente desiste da devolução. Só vale enquanto o status é requested; depois que a loja aprovou ou recusou, o cancelamento é recusado. A devolução não é apagada: ela passa a cancelled e continua nas listas.

Parâmetros de caminho

iduuidobrigatório

Id da devolução.

bash

curl -X DELETE "$BASE_URL/api/v1/storefront/returns/$RETURN_ID" \
  -H "Authorization: Bearer $TOKEN"

200Devolução cancelada

json

{ "message": "return request cancelled" }

Status	Quando	Corpo
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"}`
400	Devolução inexistente, de outro cliente ou que já saiu de `requested`	`{"error":"failed to cancel return","detail":"return not found, not owned by you, or not in 'requested' status"}`

GET/api/v1/storefront/returns/{id}/reverse-eventsCliente

Linha do tempo da logística reversa

Depois que a devolução é aprovada e a loja gera a etiqueta de retorno, o produto viaja de volta e a transportadora registra eventos. Esta rota lista esses eventos para o cliente acompanhar. Antes disso, a lista vem vazia (null).

Parâmetros de caminho

iduuidobrigatório

Id da devolução.

bash

curl "$BASE_URL/api/v1/storefront/returns/$RETURN_ID/reverse-events" \
  -H "Authorization: Bearer $TOKEN"

200Eventos

json

{
  "events": [
    { "status": "in_transit", "description": "Objeto em trânsito", "location": "Campinas, SP", "occurred_at": "2026-10-14T09:30:00Z" }
  ]
}

Campos da resposta

eventsarray

Eventos em ordem de ocorrência. null quando ainda não há.

statusstring

Situação registrada pela transportadora.

descriptionstring

Texto do evento.

locationstring

Local do evento.

occurred_atstring

Quando ocorreu, RFC 3339.

Status	Quando	Corpo
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"}`
404	Devolução inexistente, ou que não é sua	`{"error":"return not found"}`
500	Falha ao ler os eventos	`{"error":"reverse_events_failed","detail":"..."}`

Veja também

Acompanhar devoluções

Lista, consulta e cancela devoluções do cliente e vê a logística reversa.

GET/api/v1/storefront/returnsCliente

Lista as devoluções do cliente

Parâmetros de consulta

pageintegerpadrão: 1

Página, a partir de 1.

per_pageintegerpadrão: 20

Itens por página.

bash

curl "$BASE_URL/api/v1/storefront/returns?page=1&per_page=20" \
  -H "Authorization: Bearer $TOKEN"

200Devoluções do cliente

json

{
  "returns": [
    {
      "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"
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 20,
  "total_pages": 1
}

Cada item tem os campos descritos em Pedir devolução. returns vem como lista vazia quando o cliente não tem nenhuma.

Status	Quando	Corpo
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"}`
500	Falha ao listar	`{"error":"failed to list returns","detail":"..."}`

GET/api/v1/storefront/returns/{id}Cliente

Detalhe de uma devolução

Parâmetros de caminho

iduuidobrigatório

Id da devolução.

bash

curl "$BASE_URL/api/v1/storefront/returns/$RETURN_ID" \
  -H "Authorization: Bearer $TOKEN"

200Devolução

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

Status	Quando	Corpo
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"}`
404	Devolução inexistente, ou que não é sua	`{"error":"return not found"}`
500	`id` que não é UUID (a plataforma responde 500 em vez de 400) ou falha interna	`{"error":"failed to get return","detail":"..."}`

DELETE/api/v1/storefront/returns/{id}Cliente

Cancela uma devolução ainda solicitada

Parâmetros de caminho

iduuidobrigatório

Id da devolução.

bash

curl -X DELETE "$BASE_URL/api/v1/storefront/returns/$RETURN_ID" \
  -H "Authorization: Bearer $TOKEN"

200Devolução cancelada

json

{ "message": "return request cancelled" }

Status	Quando	Corpo
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"}`
400	Devolução inexistente, de outro cliente ou que já saiu de `requested`	`{"error":"failed to cancel return","detail":"return not found, not owned by you, or not in 'requested' status"}`

GET/api/v1/storefront/returns/{id}/reverse-eventsCliente

Linha do tempo da logística reversa

Parâmetros de caminho

iduuidobrigatório

Id da devolução.

bash

curl "$BASE_URL/api/v1/storefront/returns/$RETURN_ID/reverse-events" \
  -H "Authorization: Bearer $TOKEN"

200Eventos

json

{
  "events": [
    { "status": "in_transit", "description": "Objeto em trânsito", "location": "Campinas, SP", "occurred_at": "2026-10-14T09:30:00Z" }
  ]
}

Campos da resposta

eventsarray

Eventos em ordem de ocorrência. null quando ainda não há.

statusstring

Situação registrada pela transportadora.

descriptionstring

Texto do evento.

locationstring

Local do evento.

occurred_atstring

Quando ocorreu, RFC 3339.

Status	Quando	Corpo
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"}`
404	Devolução inexistente, ou que não é sua	`{"error":"return not found"}`
500	Falha ao ler os eventos	`{"error":"reverse_events_failed","detail":"..."}`