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

Solicitações de devolução

Lista as devoluções com filtros, consulta uma devolução completa e mostra os contadores gerais.

Três consultas, todas somente leitura: a lista (para a fila de análise), o detalhe de uma devolução e os contadores do painel. Exigem o módulo de devoluções e acesso de leitura a pedidos.

Listar devoluções

Devolve as devoluções da loja, da mais nova para a mais antiga, com os dados do pedido, do cliente, do produto e do motivo já juntos. Use para montar a fila de análise (status=requested).

GET/api/v1/admin/returnsAdmin

Lista as devoluções

Parâmetros de consulta

statusstring

requestedapproveditem_receivedrefundedrejectedclosedcancelled

Filtra por estado. Aceita a palavra ou a letra interna (P, A, V, F, R, C, D). Um valor desconhecido não dá erro: vira requested.

customer_iduuid

Só as devoluções deste cliente.

vendor_iduuid

Só as devoluções dos itens deste seller.

date_fromstring

Criadas a partir desta data, YYYY-MM-DD.

date_tostring

Criadas até esta data, YYYY-MM-DD, com o dia inteiro incluído.

pageintegerpadrão: 1

Página, a partir de 1.

per_pageintegerpadrão: 20

Itens por página, de 1 a 100. Fora disso volta para 20.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/returns?status=requested&date_from=2026-10-01&per_page=20" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Devoluções retornadas

json

{
  "returns": [
    {
      "id": "2f495c2f-dab7-4580-8004-54e39fa56c75",
      "order_id": "615b4147-6cb2-4057-9e25-ee82281b9d68",
      "order_item_id": "936266b5-fb89-4a3f-84b6-05155f1c54d9",
      "customer_id": "220b672c-90fe-4841-ae86-bd4f1ace982e",
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "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,
      "created_at": "2026-10-11T21:06:56.061306Z",
      "updated_at": "2026-10-11T21:06:56.061306Z",
      "order_number": "PEDIDO-20261011-0009",
      "customer_name": "Maria Souza",
      "customer_email": "maria.souza@example.com",
      "product_name": "Caneca de cerâmica",
      "reason_name": "Produto com defeito"
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 20,
  "total_pages": 1
}

Campos da resposta

returnsarray

Devoluções da página. Vazio ([]) quando nenhuma casa.

totalinteger

Total que casa com o filtro, em todas as páginas.

pageinteger

Página devolvida.

per_pageinteger

Itens por página aplicados.

total_pagesinteger

Número de páginas.

Os campos de cada item estão descritos na seção Consultar uma devolução, logo abaixo. Na lista, os dados de logística reversa, as imagens e a triagem não vêm; use o detalhe.

Erros

Status	Quando	Corpo
401 / 403	Sem token, sem privilégio, ou módulo desligado	`{"error":"module_disabled","module":"returns"}`
500	Falha interna, ou `customer_id`/`vendor_id`/data em formato inválido	`{"error":"failed to list returns","detail":"..."}`

Consultar uma devolução

Devolve uma devolução completa: dados do pedido e do cliente, valores, logística reversa, fotos de evidência e a triagem.

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

Detalha uma devolução

Parâmetros de caminho

iduuidobrigatório

Id da devolução.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/returns/2f495c2f-dab7-4580-8004-54e39fa56c75" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Devolução retornada

json

{
  "id": "2f495c2f-dab7-4580-8004-54e39fa56c75",
  "order_id": "615b4147-6cb2-4057-9e25-ee82281b9d68",
  "order_item_id": "936266b5-fb89-4a3f-84b6-05155f1c54d9",
  "customer_id": "220b672c-90fe-4841-ae86-bd4f1ace982e",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "reason_id": "0bc9dc6e-3655-44bc-96ba-b2645336a403",
  "reason": "Produto chegou com defeito",
  "status": "closed",
  "admin_notes": "Reembolso processado pelo administrador",
  "customer_notes": "Produto chegou com defeito",
  "resolution": "refund",
  "refund_amount": 49980,
  "quantity": 1,
  "created_at": "2026-07-12T13:41:51.351302Z",
  "updated_at": "2026-07-21T06:49:58.472408Z",
  "processed_at": "2026-07-21T06:49:58.472408Z",
  "processed_by": "ec5e10b3-8cb1-43e9-9aa8-964b64eda8de",
  "order_number": "97213",
  "customer_name": "Priscila Gomes",
  "customer_email": "priscila.gomes@example.com",
  "product_name": "Smartphone Moderno Roxo",
  "reason_name": "Produto com defeito",
  "reverse_status": "none",
  "refund_destination": "original"
}

Campos da resposta

iduuid

Id da devolução.

order_iduuid

Pedido de origem.

order_item_iduuid

Item devolvido. Ausente quando a devolução é do pedido todo.

customer_iduuid

Cliente que pediu.

vendor_iduuid

Seller dono do item. Ausente se o item é da loja.

reason_iduuid

Motivo escolhido da lista de motivos.

reasonstring

Motivo em texto livre dado pelo cliente.

statusstring

requestedapproveditem_receivedrefundedrejectedclosedcancelled

Estado atual.

admin_notesstring

Observação interna da análise.

customer_notesstring

Observação do cliente.

resolutionstring

refundreplacementstore_credit

O que o cliente quer receber.

refund_amountinteger

Valor a reembolsar, em centavos. É 0 até alguém defini-lo.

refund_txn_idstring

Id do estorno no gateway de pagamento, quando já houve reembolso e o gateway informou um.

quantityinteger

Quantidade de unidades devolvidas.

created_atstring

Abertura, RFC 3339 em UTC.

updated_atstring

Última alteração, RFC 3339 em UTC.

processed_atstring

Quando foi decidida pela última vez. Ausente antes disso.

processed_byuuid

Usuário que decidiu. Ausente antes disso.

order_numberstring

Número do pedido, como o cliente vê.

customer_namestring

Nome do cliente no pedido.

customer_emailstring

E-mail do cliente no pedido.

product_namestring

Nome do produto devolvido.

reason_namestring

Nome do motivo escolhido.

reverse_statusstring

nonerequestedauthorizedfailedpostedin_transitdeliveredcancelled

Situação da logística reversa.

reverse_authorization_codestring

Código de autorização de postagem. Só após a emissão.

reverse_tracking_codestring

Código de rastreio do objeto de volta.

reverse_label_urlstring

Link da etiqueta de postagem.

reverse_cost_centsinteger

Custo da logística reversa, em centavos.

refund_destinationstring

originalwallet

Para onde vai o reembolso: meio de pagamento original ou carteira da loja.

imagesarray

URLs das fotos de evidência enviadas pelo cliente. Ausente se não houver.

triageobject

Resultado da triagem automática das fotos, quando existe: status (pending, done, skipped, failed), classification, confidence (0 a 1), rationale e auto_approved.

Erros

Status	Quando	Corpo
404	Nenhuma devolução com esse id	`{"error":"return not found"}`
500	`id` que não é UUID válido	`{"error":"failed to get return","detail":"o valor \"abc\" não é um uuid válido. ..."}`
401 / 403	Sem token, sem privilégio, ou módulo desligado	`{"error":"module_disabled","module":"returns"}`

Contadores

Resume a carteira de devoluções. Alimenta os cartões do painel.

GET/api/v1/admin/returns/statsAdmin

Contadores de devoluções

Sem parâmetros.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/returns/stats" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Contadores

json

{
  "total_requests": 1535,
  "pending_requests": 0,
  "approved_count": 0,
  "rejected_count": 0,
  "refunded_count": 2,
  "total_refunded": 107585065
}

Campos da resposta

total_requestsinteger

Todas as devoluções, em qualquer estado.

pending_requestsinteger

Aguardando análise (requested).

approved_countinteger

Aprovadas e aguardando o produto (approved e item_received).

rejected_countinteger

Recusadas (rejected). Não inclui as já encerradas.

refunded_countinteger

Reembolsadas (refunded). Não inclui as já encerradas.

total_refundedinteger

Soma do refund_amount das devoluções reembolsadas ou encerradas (qualquer encerrada entra), em centavos.

Erros

Status	Quando	Corpo
401 / 403	Sem token, sem privilégio, ou módulo desligado	`{"error":"module_disabled","module":"returns"}`
500	Falha interna	`{"error":"failed to get return stats","detail":"..."}`

Veja também

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

Solicitações de devolução

Lista as devoluções com filtros, consulta uma devolução completa e mostra os contadores gerais.

Três consultas, todas somente leitura: a lista (para a fila de análise), o detalhe de uma devolução e os contadores do painel. Exigem o módulo de devoluções e acesso de leitura a pedidos.

Listar devoluções

Devolve as devoluções da loja, da mais nova para a mais antiga, com os dados do pedido, do cliente, do produto e do motivo já juntos. Use para montar a fila de análise (status=requested).

GET/api/v1/admin/returnsAdmin

Lista as devoluções

Parâmetros de consulta

statusstring

requestedapproveditem_receivedrefundedrejectedclosedcancelled

Filtra por estado. Aceita a palavra ou a letra interna (P, A, V, F, R, C, D). Um valor desconhecido não dá erro: vira requested.

customer_iduuid

Só as devoluções deste cliente.

vendor_iduuid

Só as devoluções dos itens deste seller.

date_fromstring

Criadas a partir desta data, YYYY-MM-DD.

date_tostring

Criadas até esta data, YYYY-MM-DD, com o dia inteiro incluído.

pageintegerpadrão: 1

Página, a partir de 1.

per_pageintegerpadrão: 20

Itens por página, de 1 a 100. Fora disso volta para 20.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/returns?status=requested&date_from=2026-10-01&per_page=20" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Devoluções retornadas

json

{
  "returns": [
    {
      "id": "2f495c2f-dab7-4580-8004-54e39fa56c75",
      "order_id": "615b4147-6cb2-4057-9e25-ee82281b9d68",
      "order_item_id": "936266b5-fb89-4a3f-84b6-05155f1c54d9",
      "customer_id": "220b672c-90fe-4841-ae86-bd4f1ace982e",
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "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,
      "created_at": "2026-10-11T21:06:56.061306Z",
      "updated_at": "2026-10-11T21:06:56.061306Z",
      "order_number": "PEDIDO-20261011-0009",
      "customer_name": "Maria Souza",
      "customer_email": "maria.souza@example.com",
      "product_name": "Caneca de cerâmica",
      "reason_name": "Produto com defeito"
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 20,
  "total_pages": 1
}

Campos da resposta

returnsarray

Devoluções da página. Vazio ([]) quando nenhuma casa.

totalinteger

Total que casa com o filtro, em todas as páginas.

pageinteger

Página devolvida.

per_pageinteger

Itens por página aplicados.

total_pagesinteger

Número de páginas.

Os campos de cada item estão descritos na seção Consultar uma devolução, logo abaixo. Na lista, os dados de logística reversa, as imagens e a triagem não vêm; use o detalhe.

Erros

Status	Quando	Corpo
401 / 403	Sem token, sem privilégio, ou módulo desligado	`{"error":"module_disabled","module":"returns"}`
500	Falha interna, ou `customer_id`/`vendor_id`/data em formato inválido	`{"error":"failed to list returns","detail":"..."}`

Consultar uma devolução

Devolve uma devolução completa: dados do pedido e do cliente, valores, logística reversa, fotos de evidência e a triagem.

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

Detalha uma devolução

Parâmetros de caminho

iduuidobrigatório

Id da devolução.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/returns/2f495c2f-dab7-4580-8004-54e39fa56c75" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Devolução retornada

json

{
  "id": "2f495c2f-dab7-4580-8004-54e39fa56c75",
  "order_id": "615b4147-6cb2-4057-9e25-ee82281b9d68",
  "order_item_id": "936266b5-fb89-4a3f-84b6-05155f1c54d9",
  "customer_id": "220b672c-90fe-4841-ae86-bd4f1ace982e",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "reason_id": "0bc9dc6e-3655-44bc-96ba-b2645336a403",
  "reason": "Produto chegou com defeito",
  "status": "closed",
  "admin_notes": "Reembolso processado pelo administrador",
  "customer_notes": "Produto chegou com defeito",
  "resolution": "refund",
  "refund_amount": 49980,
  "quantity": 1,
  "created_at": "2026-07-12T13:41:51.351302Z",
  "updated_at": "2026-07-21T06:49:58.472408Z",
  "processed_at": "2026-07-21T06:49:58.472408Z",
  "processed_by": "ec5e10b3-8cb1-43e9-9aa8-964b64eda8de",
  "order_number": "97213",
  "customer_name": "Priscila Gomes",
  "customer_email": "priscila.gomes@example.com",
  "product_name": "Smartphone Moderno Roxo",
  "reason_name": "Produto com defeito",
  "reverse_status": "none",
  "refund_destination": "original"
}

Campos da resposta

iduuid

Id da devolução.

order_iduuid

Pedido de origem.

order_item_iduuid

Item devolvido. Ausente quando a devolução é do pedido todo.

customer_iduuid

Cliente que pediu.

vendor_iduuid

Seller dono do item. Ausente se o item é da loja.

reason_iduuid

Motivo escolhido da lista de motivos.

reasonstring

Motivo em texto livre dado pelo cliente.

statusstring

requestedapproveditem_receivedrefundedrejectedclosedcancelled

Estado atual.

admin_notesstring

Observação interna da análise.

customer_notesstring

Observação do cliente.

resolutionstring

refundreplacementstore_credit

O que o cliente quer receber.

refund_amountinteger

Valor a reembolsar, em centavos. É 0 até alguém defini-lo.

refund_txn_idstring

Id do estorno no gateway de pagamento, quando já houve reembolso e o gateway informou um.

quantityinteger

Quantidade de unidades devolvidas.

created_atstring

Abertura, RFC 3339 em UTC.

updated_atstring

Última alteração, RFC 3339 em UTC.

processed_atstring

Quando foi decidida pela última vez. Ausente antes disso.

processed_byuuid

Usuário que decidiu. Ausente antes disso.

order_numberstring

Número do pedido, como o cliente vê.

customer_namestring

Nome do cliente no pedido.

customer_emailstring

E-mail do cliente no pedido.

product_namestring

Nome do produto devolvido.

reason_namestring

Nome do motivo escolhido.

reverse_statusstring

nonerequestedauthorizedfailedpostedin_transitdeliveredcancelled

Situação da logística reversa.

reverse_authorization_codestring

Código de autorização de postagem. Só após a emissão.

reverse_tracking_codestring

Código de rastreio do objeto de volta.

reverse_label_urlstring

Link da etiqueta de postagem.

reverse_cost_centsinteger

Custo da logística reversa, em centavos.

refund_destinationstring

originalwallet

Para onde vai o reembolso: meio de pagamento original ou carteira da loja.

imagesarray

URLs das fotos de evidência enviadas pelo cliente. Ausente se não houver.

triageobject

Resultado da triagem automática das fotos, quando existe: status (pending, done, skipped, failed), classification, confidence (0 a 1), rationale e auto_approved.

Erros

Status	Quando	Corpo
404	Nenhuma devolução com esse id	`{"error":"return not found"}`
500	`id` que não é UUID válido	`{"error":"failed to get return","detail":"o valor \"abc\" não é um uuid válido. ..."}`
401 / 403	Sem token, sem privilégio, ou módulo desligado	`{"error":"module_disabled","module":"returns"}`

Contadores

Resume a carteira de devoluções. Alimenta os cartões do painel.

GET/api/v1/admin/returns/statsAdmin

Contadores de devoluções

Sem parâmetros.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/returns/stats" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Contadores

json

{
  "total_requests": 1535,
  "pending_requests": 0,
  "approved_count": 0,
  "rejected_count": 0,
  "refunded_count": 2,
  "total_refunded": 107585065
}

Campos da resposta

total_requestsinteger

Todas as devoluções, em qualquer estado.

pending_requestsinteger

Aguardando análise (requested).

approved_countinteger

Aprovadas e aguardando o produto (approved e item_received).

rejected_countinteger

Recusadas (rejected). Não inclui as já encerradas.

refunded_countinteger

Reembolsadas (refunded). Não inclui as já encerradas.

total_refundedinteger

Soma do refund_amount das devoluções reembolsadas ou encerradas (qualquer encerrada entra), em centavos.

Erros

Status	Quando	Corpo
401 / 403	Sem token, sem privilégio, ou módulo desligado	`{"error":"module_disabled","module":"returns"}`
500	Falha interna	`{"error":"failed to get return stats","detail":"..."}`