Devoluções: Resolução e reembolso

O que acontece depois que o produto volta à loja (received): quem decide o desfecho, como o estorno é calculado em devoluções parciais, e o caso em que a devolução encerra sem reembolso porque foi resolvida fora da plataforma.

O ponto de decisão

Quando a devolução chega em received, o produto está fisicamente de volta. A partir daí você (o seller) decide entre dois desfechos. A execução do estorno (o pagamento em si) continua com o financeiro da plataforma:

Os dois campos novos no detalhe da devolução:

{
  "id": "01JMGAZ8K6Q2W7XV5DNRTN0M4P",
  "status": "closed",
  "status_label": "Encerrado",
  "resolution": "resolved_externally",
  "resolution_notes": "Seller reenviou o produto direto ao cliente (acordo via chat em 28/04).",
  "...": "..."
}

resolution é null enquanto a devolução não chega ao desfecho.

Como o valor do estorno é calculado

O estorno cobre apenas os itens daquela devolução, não o pedido inteiro. O valor é a soma de preço unitário pago × quantidade devolvida de cada item:

Pedido de exemplo:

Devolução aberta com items:

{
  "items": [
    { "order_item_id": "01JMG9ZC4T8RWX2QHV6DKN3M7E", "quantity": 1, "reason_key": "defective" }
  ]
}

→ Estorno de R$ 100,00 (1 × R$ 100,00). A outra furadeira e o kit de brocas não entram.

O preço usado é o efetivamente pago (com desconto aplicado), o mesmo unit_price que aparece nos itens do pedido. O freight_cost da coleta reversa entra à parte, no acerto financeiro da devolução.

Devoluções parciais sucessivas

Um mesmo pedido pode ter várias devoluções, inclusive em andamento ao mesmo tempo, cada uma com seu próprio trilho e seu próprio desfecho. Uma única regra controla isso:

Saldo devolvível por item. Cada item tem um saldo: quantidade comprada − quantidade já solicitada em devoluções anteriores. O saldo desconta também as devoluções ainda em andamento (pending, forwarded_to_seller, approved, em coleta), então o total devolvido nunca ultrapassa o comprado. Devoluções rejeitadas ou canceladas devolvem o saldo, pois a mercadoria nunca saiu. Solicitar acima do saldo é rejeitado com 422 e a mensagem "Quantidade excede o saldo devolvível deste item (disponível: N)".

Um detalhe que costuma confundir: estornos por item feitos pela operação da plataforma também consomem esse saldo. Se o suporte já estornou 1 unidade de um item diretamente, essa unidade não pode voltar em uma devolução — por isso o saldo pode vir menor do que a sua conta de "comprado menos devolvido" sugeriria.

Exemplo: o cliente devolve em três rodadas

Pedido com 4 unidades do mesmo item:

Repare na 2ª rodada: o desfecho foi sem estorno, e mesmo assim consumiu saldo. A mercadoria voltou à loja do mesmo jeito. E a 3ª não precisou esperar a 2ª encerrar; devoluções coexistem, o teto é sempre o saldo por item.

Para acompanhar todas as devoluções de um pedido:

GET /api/v1/sellers/orders/returns?order_id=01JMG9ZB1QDC0R8Y6W3ETKHM2V

Cenários comuns

"Aprovei, o produto voltou com defeito confirmado. Quando o cliente recebe o dinheiro?"

Em received, solicite o estorno (POST /request-refund, sem corpo): a devolução vira status=refunded e a solicitação vai para o financeiro processar. O valor é o dos itens devolvidos, calculado automaticamente. Quando o financeiro concluir, a devolução fecha com resolution=refunded.

POST /api/v1/sellers/orders/returns/01JMGAZ8K6Q2W7XV5DNRTN0M4P/request-refund

Acompanhe o status do estorno pelo bloco refund do detalhe (pending → processing → completed):

GET /api/v1/sellers/orders/returns/01JMGAZ8K6Q2W7XV5DNRTN0M4P

"Combinei com o cliente de mandar outro produto no lugar. Não quero que ele seja estornado"

Em received, encerre você mesmo a devolução sem estorno com POST /close-without-refund, informando a justificativa obrigatória (notes):

POST /api/v1/sellers/orders/returns/01JMGAZ8K6Q2W7XV5DNRTN0M4P/close-without-refund
{
  "notes": "Reenviei produto novo via transportadora própria. Acordo com o cliente em 28/04."
}

A devolução fecha com status=closed e resolution=resolved_externally, e a justificativa fica em resolution_notes. Nenhum valor é movimentado; o caso aparece encerrado para o cliente com a resolução combinada.

"A devolução está em refunded há dias. Está travada?"

refunded significa "estorno em processamento no financeiro". O tempo depende do meio de pagamento original (PIX é rápido; cartão depende da adquirente). Quando o estorno liquida, a devolução fecha sozinha (closed). Se o prazo estiver anormal, abra uma ocorrência.

"O cliente quer devolver o restante mas a API recusa com 'quantidade excede o saldo devolvível'"

Alguma devolução anterior (mesmo em andamento) já reservou essas unidades: o saldo desconta tudo que não foi rejeitado nem cancelado. Veja quanto sobra por item listando as devoluções do pedido com o filtro por order_id e somando as quantidades já solicitadas.

Cuidados

Você decide o desfecho; o financeiro executa. Em received você escolhe entre solicitar o estorno (/request-refund) e encerrar por fora (/close-without-refund). A plataforma só executa o pagamento do estorno. O campo resolution é preenchido pela sua decisão e, a partir daí, é só leitura.

Reenviou produto? Encerre por fora. Se você resolver o caso fora da plataforma (ex.: reenviar um produto novo) mas não encerrar com /close-without-refund, a devolução fica parada em received sem desfecho. Registre a decisão para fechar o caso e deixar o acordo em resolution_notes.

Devolução parcial estorna valor parcial. Cliente que devolve 1 de 2 unidades recebe o valor de 1 unidade. Se o cliente alegar valor diferente, o caso é da operação (divergência de valor), não do trilho automático.

Saldo devolvível é por item do pedido, não por pedido. Um pedido com 3 itens diferentes tem 3 saldos independentes, e cada saldo já desconta as devoluções em andamento daquele item. Não existe trava de "uma devolução por vez": o que impede exagero é o saldo.