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

Devoluções do seller

Lista e consulta as devoluções dos pedidos do seller e faz a análise delas, aprovando, confirmando o recebimento do item ou recusando.

Uma devolução (também chamada de RMA, de "return merchandise authorization") nasce quando o cliente pede, pela vitrine, para devolver um item que comprou. O pedido da devolução traz o motivo, a quantidade e o que o cliente quer em troca: reembolso (refund), troca (replacement) ou crédito na loja (store_credit). O seller dono do pedido analisa: autoriza a devolução, confirma que o item voltou ou recusa.

O reembolso em si não é feito pelo seller. Depois que o item chega (item_received), quem move a devolução para refunded (e dispara o estorno no meio de pagamento ou o crédito na carteira) é o administrador da loja.

Situação da devolução

requested→approved→item_received→refunded→closed
statusSignificadoO seller pode definir?
requestedO cliente pediu e aguarda análise.Não (é o estado inicial)
approvedDevolução autorizada; o cliente deve enviar o item de volta.Sim, a partir de requested
item_receivedO item voltou e foi conferido.Sim, a partir de approved
refundedO reembolso foi feito.Não, só o administrador
rejectedRecusada.Sim, a partir de requested
closedEncerrada (depois de refunded ou rejected).Não
cancelledO cliente desistiu enquanto ainda era requested.Não

As respostas sempre trazem o nome do status (approved), nunca a letra guardada no banco.

Listar as devoluções

GET/api/v1/vendor/returnsSeller

Lista as devoluções dos pedidos do seller

Devolve as devoluções cujo pedido pertence ao seller, da mais recente para a mais antiga. Não há filtros: a paginação é a única forma de recortar.

Parâmetros de consulta

pageintegerpadrão: 1
Página, a partir de 1.
per_pageintegerpadrão: 20
Itens por página, de 1 a 100. Um valor fora dessa faixa volta silenciosamente para 20.

Exemplo de requisição: listar

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

Resposta: listar

200Devoluções do seller
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": "Produto com defeito",
      "status": "closed",
      "admin_notes": "Reembolso processado",
      "customer_notes": "Não liga",
      "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": "Maria Souza",
      "customer_email": "maria.souza@example.com",
      "product_name": "Smartphone Plus Roxo",
      "reason_name": "Defective product"
    }
  ],
  "total": 1534,
  "page": 1,
  "per_page": 20,
  "total_pages": 77
}

Campos da resposta

returnsarray
Devoluções da página. Cada item tem os campos descritos abaixo.
totalinteger
Total de devoluções do seller.
pageinteger
Página devolvida.
per_pageinteger
Tamanho da página aplicado.
total_pagesinteger
Quantidade de páginas.
returns[].iduuid
Id da devolução. É o que as outras rotas desta página recebem.
returns[].order_iduuid
Pedido de origem.
returns[].order_item_iduuid
Item do pedido devolvido. Pode faltar quando a devolução é do pedido todo.
returns[].customer_iduuid
Cliente que pediu.
returns[].vendor_iduuid
Seller dono do pedido.
returns[].reason_iduuid
Motivo escolhido no cadastro de motivos da loja. Pode faltar.
returns[].reasonstring
Motivo em texto livre informado pelo cliente. Pode ser vazio.
returns[].statusstring
requestedapproveditem_receivedrefundedrejectedclosedcancelled
Situação da devolução.
returns[].admin_notesstring
Anotações de quem analisou (seller ou administrador). Vazio se nunca houve.
returns[].customer_notesstring
Observações escritas pelo cliente.
returns[].resolutionstring
refundreplacementstore_credit
O que o cliente quer receber.
returns[].refund_amountinteger
Valor a reembolsar, em centavos (49980 = R$ 499,80). Fica 0 até a loja calcular o reembolso.
returns[].quantityinteger
Quantidade de unidades devolvidas.
returns[].created_atstring
Quando o cliente abriu o pedido de devolução (RFC 3339, UTC).
returns[].updated_atstring
Última alteração (RFC 3339, UTC).
returns[].processed_atstring
Quando foi analisada pela última vez. Ausente se ainda não foi.
returns[].processed_byuuid
Usuário que fez a última análise. Ausente se ainda não foi.
returns[].order_numberstring
Número do pedido, para exibição.
returns[].customer_namestring
Nome do cliente no pedido.
returns[].customer_emailstring
E-mail do cliente no pedido.
returns[].product_namestring
Nome do produto devolvido. Ausente quando não há item específico.
returns[].reason_namestring
Nome do motivo cadastrado. O texto vem do cadastro da loja e pode estar em outro idioma.

Consultar uma devolução

GET/api/v1/vendor/returns/{id}Seller

Consulta uma devolução do seller

Devolve uma devolução com os mesmos campos de cada item da lista. Uma devolução de outro seller responde 404, igual a uma que não existe.

Parâmetros de caminho

iduuidobrigatório
Id da devolução.

Exemplo de requisição: consultar

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

Resposta: consultar

200Devolução encontrada
json
{
  "id": "54ccbfdf-87db-43a5-bd7e-d7f2b39f896a",
  "order_id": "f678dbbd-7bde-47a3-8291-2fd08cd6027e",
  "customer_id": "67bf291c-0846-4053-9528-8cfd5ab0ebf1",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "reason_id": "b20ae1b7-3ed4-4a47-86c7-278c1ed20c6b",
  "reason": "",
  "status": "refunded",
  "admin_notes": "",
  "customer_notes": "",
  "resolution": "store_credit",
  "refund_amount": 20990,
  "quantity": 1,
  "created_at": "2026-07-12T00:40:14.533866Z",
  "updated_at": "2026-07-12T01:47:30.435203Z",
  "processed_at": "2026-07-12T00:43:53.060792Z",
  "processed_by": "67bf291c-0846-4053-9528-8cfd5ab0ebf1",
  "order_number": "80583",
  "customer_name": "Maria Souza",
  "customer_email": "maria.souza@example.com",
  "reason_name": "Changed my mind"
}

Analisar uma devolução

PUT/api/v1/vendor/returns/{id}/statusSeller

Aprova, confirma o recebimento ou recusa uma devolução

Move a devolução para o próximo estado permitido. O seller só pode escolher três destinos: approved, item_received e rejected. Cada mudança grava quem fez e quando (processed_by, processed_at) e dispara o evento de mudança de status, que alimenta e-mails ao cliente e a reposição de estoque.

Parâmetros de caminho

iduuidobrigatório
Id da devolução.

Corpo da requisição

statusstringobrigatório
approveditem_receivedrejected
Novo status. Qualquer outro valor, inclusive refunded, responde 403.
admin_notesstring
Anotação da análise, mostrada ao administrador. Enviada vazia, não apaga a anotação anterior.

Exemplo de requisição: analisar

bash
curl -X PUT "$BASE_URL/api/v1/vendor/returns/2f495c2f-dab7-4580-8004-54e39fa56c75/status" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status": "approved", "admin_notes": "Pode enviar pelos Correios"}'

Resposta: analisar

200Devolução atualizada
json
{
  "id": "2f495c2f-dab7-4580-8004-54e39fa56c75",
  "order_id": "615b4147-6cb2-4057-9e25-ee82281b9d68",
  "customer_id": "220b672c-90fe-4841-ae86-bd4f1ace982e",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "reason": "Produto com defeito",
  "status": "approved",
  "admin_notes": "Pode enviar pelos Correios",
  "customer_notes": "Não liga",
  "resolution": "refund",
  "refund_amount": 49980,
  "quantity": 1,
  "created_at": "2026-10-11T13:41:51Z",
  "updated_at": "2026-10-11T14:02:10Z",
  "processed_at": "2026-10-11T14:02:10Z",
  "processed_by": "0fd409fb-9869-4c50-a18c-a810a19abeed",
  "order_number": "97213",
  "customer_name": "Maria Souza",
  "customer_email": "maria.souza@example.com"
}

A resposta é a devolução completa depois da mudança. Pode trazer também campos de logística reversa (reverse_status, reverse_authorization_code, reverse_tracking_code, reverse_label_url, reverse_cost_cents), de destino do reembolso (refund_destination, original ou wallet) e da triagem das fotos de evidência (images, triage), quando a loja usa esses recursos. Eles só aparecem aqui, não na lista nem na consulta.

Erros

StatusQuandoCorpo de exemplo
400Corpo não é JSON.{"error":"invalid request body","detail":"..."}
400status ausente.{"error":"status is required"}
400A transição não é permitida a partir do status atual.{"error":"failed to update return status","detail":"invalid status transition from 'refunded' to 'approved'"}
401Sem token.{"error":"authentication required"}
403O destino não é um dos três do seller.{"error":"vendors can only set return status to approved, item_received, or rejected"}
403O usuário não tem seller associado.{"error":"no vendor account associated with this user"}
404Devolução inexistente ou de outro seller.{"error":"return not found"}
500id que não é um UUID válido (na consulta e na análise).{"error":"failed to get return","detail":"o valor \"abc\" não é um uuid válido. ..."}
Mensagens em português

O campo detail de alguns erros de validação vem em português, como o servidor devolve. Não dependa do texto: use o código HTTP.

O seller não conclui o reembolso

A rota recusa refunded com 403. Depois de item_received, a devolução fica esperando o administrador da loja fazer o reembolso. Se você integra um ERP, não espere ver refunded como resultado de uma chamada sua.

Estoque

Ao confirmar item_received, a quantidade devolvida volta ao estoque vendável automaticamente (uma única vez por devolução). A rota do seller não tem como desligar isso: se o item chegou danificado, avise o administrador antes de confirmar o recebimento.

Veja também

  • Cancelamentos pedidos pelo cliente
  • Pedidos do seller
  • Mudar o status do pedido
Anterior
Cancelamentos pedidos pelo cliente
Próxima
Enviar fatura por e-mail
Nesta página
  • Situação da devolução
  • Listar as devoluções
  • Exemplo de requisição: listar
  • Resposta: listar
  • Consultar uma devolução
  • Exemplo de requisição: consultar
  • Resposta: consultar
  • Analisar uma devolução
  • Exemplo de requisição: analisar
  • Resposta: analisar
  • Erros
  • Veja também