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.

Pré-requisitos: leia primeiro Devoluções: visão geral. Este guia cobre só o trecho final do trilho — de received até closed.

O ponto de decisão

Quando a devolução chega em received, o produto está fisicamente de volta. A partir daí a plataforma (não o seller) decide entre dois desfechos:

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 ao longo do tempo, cada uma com seu próprio trilho e seu próprio desfecho. Duas regras controlam isso:

1. Uma devolução ativa por vez. Enquanto houver devolução em andamento (qualquer status exceto rejected, cancelled ou closed), o pedido não aceita nova solicitação. Encerrou (closed), libera.
2. Saldo devolvível por item. Cada item tem um saldo: quantidade comprada − quantidade já devolvida (devoluções rejeitadas/canceladas devolvem o saldo, pois a mercadoria nunca saiu). Solicitar acima do saldo é rejeitado com 422.

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.

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

Você não precisa fazer nada. Após received, a plataforma cria a solicitação de estorno (status=refunded) e o financeiro processa. Quando concluir, a devolução fecha com resolution=refunded. Acompanhe pelo detalhe:

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

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

Combine com a operação da plataforma (via atendimento/ocorrência) antes do desfecho. A operação encerra a devolução sem estorno e registra o acordo:

{
  "status": "closed",
  "resolution": "resolved_externally",
  "resolution_notes": "Seller reenviou produto novo via transportadora própria — acordo registrado no atendimento #4412."
}

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 'já existe uma solicitação ativa'"

A devolução anterior ainda não encerrou — provavelmente está em refunded (estorno em processamento). O pedido libera nova solicitação quando ela fechar (closed). Veja em que pé está com o filtro por order_id.

Cuidados

resolution é só leitura para o seller. O desfecho é decidido pela operação da plataforma. O que o seller controla é o início do trilho (aprovar/rejeitar) e a logística reversa; o fim (estornar ou encerrar por fora) reflete nos campos.

Acordo por fora sem registro = risco. Se você reenviar produto ao cliente sem combinar com a operação, a devolução pode seguir o trilho padrão e terminar em estorno — você perde o produto e o valor. Sempre formalize pelo atendimento antes do desfecho.

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. A trava de "uma devolução ativa por vez" é que é por pedido.