Devoluções

Uma devolução (também chamada de RMA, de "return merchandise authorization") é o pedido que o cliente faz para devolver, trocar ou ser reembolsado por um item de um pedido já comprado. O Código de Defesa do Consumidor garante esse direito, e por isso a plataforma tem um fluxo próprio: o cliente abre o pedido de devolução, a loja analisa, aprova ou recusa, recebe o produto de volta e devolve o dinheiro.

Estas são as rotas do administrador da loja. O cliente abre a devolução pela API da vitrine e o seller acompanha pelo painel dele; aqui você analisa, decide e acompanha tudo.

Como funciona

O ciclo da devolução

Pelo caminho de recusa: Solicitada > Recusada > Encerrada. O cliente também pode cancelar enquanto a devolução está solicitada.

Resolução

O campo resolution diz o que o cliente quer receber: refund (dinheiro de volta), replacement (troca por outro item) ou store_credit (crédito na loja). Ao processar a devolução você pode sobrescrevê-lo.

Logística reversa

É o caminho de volta do produto. Quando o recurso está ligado no módulo, aprovar uma devolução pede ao transportador uma autorização de postagem (um código e uma etiqueta que o cliente leva à agência). O andamento aparece em reverse_status e na linha do tempo da logística reversa.

Destino do reembolso

O cliente escolhe refund_destination: original (volta ao meio de pagamento usado) ou wallet (crédito na carteira da loja). No reembolso por wallet não há estorno no gateway; o valor é creditado na carteira do cliente.

Conceitos importantes

Quem enxerga o quê

Estas rotas veem todas as devoluções da loja. O seller só vê as devoluções dos próprios pedidos, por rotas dele. O cliente vê as suas.

Motivos e regras

Os motivos são as opções que o cliente escolhe ("Produto com defeito", "Desisti da compra"). As regras por categoria definem prazo, exigência de fotos e aprovação automática para cada categoria de produto. Os dois são configuráveis nas páginas Motivos e Regras por categoria.

Triagem das fotos

Quando o cliente envia fotos de evidência, a plataforma pode analisá-las automaticamente e, em categorias configuradas para isso, aprovar sozinha casos de baixo valor. O resultado aparece no campo triage da devolução (status, classification, confidence, rationale, auto_approved). Trate-o como apoio à decisão, não como veredicto.

Endpoints

Erros comuns

1. Tentar reembolsar com refund_amount zerado. A transição para refunded é recusada. Defina o valor ao processar a devolução.
2. Usar PUT para aprovar. O PUT só troca o estado. Para aprovar com valor, resolução e logística reversa, use POST /process.
3. Pular etapas. Não se vai de requested direto a refunded. A resposta 400 diz invalid status transition from 'x' to 'y'.
4. Filtrar por status com texto desconhecido. Em vez de erro, o filtro vira requested. Confira a grafia.
5. Esperar 404 em id mal formado. GET /returns/abc devolve 500 (não é um UUID); um UUID válido que não existe devolve 404.
6. Esperar que a logística reversa sempre emita. Se o transportador não estiver configurado ou recusar o pedido, a chamada devolve 502 reverse_failed e o reverse_status fica failed.
7. Repetir o reembolso após 502. O 502 significa que nada foi marcado; é seguro tentar de novo ou reembolsar manualmente no gateway.

Próximos passos