1. 返品1件を取得
GET /api/returns/R-1042
状態と次に動く人、その件のサポート担当、期限(保留中かどうかを含む)、商品ごとの検品結果と提案額、承認が必要かどうか、決済サービス側ですでに返金された額が必要。どの操作を出すかは状態と役割と担当の組み合わせで決まるが、そのルールを画面側に持たせたくない。返金IDを受け取れなかった場合も、この件の依頼の有無を確かめたい。
出せる操作の判定はサーバーで可能。決済サービスの返金記録は、開くたびに問い合わせると遅くなるので、決済サービスからの通知で更新した記録を、更新時刻とともに返す。この件にひもづく返金の依頼と承認の依頼も含められる。
出せる操作は、出せない理由のコードとあわせて受け取る。承認の条件はレスポンスで受け取り、金額を編集している間の判定(P1)に使う。画面を開いている間はこのAPIを定期的に取得し、状態・次に動く人・出せる操作を更新する(H6)。
リクエストとレスポンスの形式
{
"returnId": "R-1042",
"version": 7,
"status": "awaiting_decision",
"nextActor": { "role": "support", "userId": "u_mia", "name": "Mia Keller" },
"stalled": false,
"deadline": { "date": "2026-10-28", "state": "active" },
"returnProof": null,
"items": [
{ "itemId": "it_1", "name": "Electric kettle", "paid": 8900, "arrival": "received", "grade": "no_issue", "suggestedRefund": 8900, "refund": 8900 },
{ "itemId": "it_2", "name": "Coffee grinder", "paid": 11900, "arrival": "received", "grade": "signs_of_use", "suggestedRefund": 9500, "refund": 9500 }
],
"providerRefunds": { "total": 0, "syncedAt": "2026-10-26T09:12:00Z" },
"approvalRules": { "amountThreshold": 15000, "uninspected": true, "aboveSuggested": true, "destinationChange": true },
"availableActions": [
{ "action": "request_approval" },
{ "action": "edit_amounts" },
{ "action": "request_refund", "enabled": false, "reason": "APPROVAL_REQUIRED" }
],
"refunds": [],
"approvalRequest": null,
"followUps": []
}次に動く人と、動きが止まっているか(H2)は、サーバーが判定して返す。共通のルールを画面側で作り直さない。
deadline.stateは、到着も返送の証明もない間はwithheld(保留中)になる(H3)。期限の日付そのものは変わらない。
versionは、保存・依頼・承認のたびに送り、サーバーが照合する(H6、P3)。入力中の金額を保持する間は、その入力の前提になったversionも保持し、定期取得した値に差し替えない。
refundsとapprovalRequestには、この件の依頼と状態が入る。応答が届かなかった依頼も、送ったキー(requestKey)でここから探せる(R2)。
followUpsは返金後の対応の未解決の内容で、それぞれが次に動く人を持つ(H4)。




