Yoko Shiina

画面仕様設計書のサンプル:架空のEC事業者の「返品・返金を処理する社内画面」

このページでは、架空のEC事業者の返品・返金業務を題材に、画面仕様設計書を紹介しています。1人が1回の操作で1日分を置き換える画面は1日分のシフトのアップロードのサンプル、来館者が館内と自宅で一人で使う公開のガイドは美術館のガイドのサンプルをご覧ください。

止まっている返品には、必ず引き受けている人がいて、次の一手が分かる。

倉庫の返品担当、サポート担当、チームリードの3つの役割と、決済サービスが関わる返品・返金の社内画面を、この原則で設計した。

返品1件の詳細画面。商品ごとの返金額の入力欄、合計€184.00、チームリードの承認が必要というメッセージと「Request approval」ボタン。

この画面仕様設計書には、2種類の注記があります。

システムの視点:データと実装上の制約から、なぜこの形にしているか。

ユーザーの視点
ユーザーの視点:どこでつまずきやすく、画面でどう対処するべきか。

この画面の目的

EC事業者の返品1件を、受け付けから返金後の対応まで扱う社内画面。

1件の返品は、数日かけて倉庫の返品担当、サポート担当、チームリードの手を渡る。返金は決済サービスに依頼し、結果は後から届く。一定の条件に当てはまる返金には、承認が必要になる。

設計の軸にしたのは、どの1件も、止まっている間に引き受ける人が決まっていて、次に何をすれば進むかが分かること。エラーや通知を出して終わりにせず、誰が拾い、何をすれば次へ進むかまでつなげる。

シフトのサンプルは、1人が1回の操作で結果を確定させる画面だった。ここでは、操作した人と対処する人が違うことが多い。なので、エッジケースの表に「引き受ける人」と「次の操作」を項目として持たせている。

ユーザーの視点
返金が止まっていても、画面の上では誰かの担当に見えることがある。本人が休んでいる、結果が届いたのが本人の帰った後だった、承認の後で前提が変わった。そうした件は、気づかれないまま期限を迎える。この仕様は、その「誰のものでもない時間」をなくすためにある。

前提

Halden Home(架空)は、小型キッチン家電をオランダ、ドイツ、ベルギーで販売する中規模の小売業者。倉庫は1か所で、返品は1日に数十件。決済は外部の決済サービスを使い、返金もそこを通す。この画面は社内の開発チームが作る社内ツール、という設定。

製品の表示言語は英語なので、画面と画面に出す文言は英語のまま載せている。

返金の期限
撤回の通知から14日(EUの撤回権)。商品の到着か返送の証明の早い方までは、返金を保留できる。
承認が必要になる条件
合計が€150以上、検品前に返金する、提案額を超えて返金する、返金先を変える。依頼した人と承認する人は別にする。
期限が近い
期限まで3日以内。
停滞
期限が近く、担当者の最終操作から2営業日を過ぎた件。
結果が届かない
決済サービスへの依頼から48時間。処理が続いていると分かって返金処理中に戻した場合は、その時点から数え直す。
返金後の未着
返送の証明で先に返金した件で、返金から14日。

期限と保留の条件は、架空の社内ルールではなく、実在の撤回権に合わせた。キューに期限が付く理由と、待機から対応へ切り替わる理由が、業務の都合ではなく規則から出てくる。数値のうち21日、3日、2営業日、48時間、返金後の14日、€150は架空の社内基準。

登場人物

この画面を使うのは3つの役割。画面を使わない関係者も、件の状態を動かす。

この画面を使う

  • 倉庫の返品担当

    届いた荷物を返品と照合し、商品ごとに検品結果を記録する。返金の操作はしない。

  • サポート担当

    顧客とやり取りし、検品結果をもとに返金額を決め、返金または承認を依頼する。返金が失敗したら対応する。

  • チームリード

    条件に当てはまる返金を承認する。止まった件を割り当て直し、返金後に残った仕事を引き受ける。サポート担当の操作も兼ねられる。

この画面を使わない

  • 顧客

    撤回を申請し、商品を返送する。この画面は使わない。

  • 運送会社

    返送の荷物を運ぶ。返送ラベルの追跡で、受け取りの記録が届く。

  • 決済サービス

    返金の依頼を受け、結果を後から返す。人ではない関係者。

  • 経理

    返金先を変えた場合の銀行振込を行う。この画面は使わない。

「その件のサポート担当」は、判断待ちになった件を最初に引き受けたサポート担当の1人。その後の返金失敗や差し戻しも、この人に戻る。顧客とのやり取りを1人に保つため。

倉庫の返品担当には1件ごとの割り当てを置かない。荷物は物理的に1か所にあり、2人が同じ荷物を検品する状況が起きにくいため。承認も割り当てではなく、依頼した人以外のチームリードなら誰でも行える。

社内の行為は「依頼」(承認の依頼、返金の依頼)、顧客の行為は「申請」と呼び分けている。仕様の中で「依頼者」とは書かず、誰が依頼したかは毎回役割で書く。同じ言葉が場所によって違う人を指すと、引き受ける人の定義が崩れる。

画面の構成

画面は2つ。役割ごとのキューを持つ一覧と、返品1件の詳細。一覧は、ログインした人の役割で開くキューと列が変わる。倉庫の返品担当には金額と顧客の連絡先を出さない。

詳細は、左の列に商品・返金・メッセージ、右の列に経過を置く。経過には、決済サービスからの結果と人による記録の両方が残る。

サポート担当の一覧。判断待ちのキューが選ばれ、期限の近い件に時計のアイコンが付いている。
01 一覧(サポート担当)キューは役割ごと。件数を常に出し、期限が3日以内の件は太字と時計のアイコンで示す。
返品1件の詳細。商品ごとの返金額の入力欄、合計、承認が必要というメッセージと承認を依頼するボタン。
04 判断待ち(承認が必要)金額を変えた時点で承認の要否を示す。承認は普通の流れなので「次の作業」の段階で出す。
承認モーダル2種類。決済サービス経由の返金と、銀行振込での返金。
05 承認モーダル承認する内容をボタンより先に読ませる。ボタンには金額と、押した結果を書く。
返金完了のメッセージと、未着の商品が残っているという次の作業のメッセージ。
11 返金後の対応返金完了と対応終了を分ける。返金の後に残った仕事にも、次に動く人を持たせる。

画面はFigmaで11の状態として描いている。このページでは主な4つを載せ、全体はFigmaで見られる。

ユーザーフロー

返品1件は6つのステップを、別々の人が、別々の時間に進める。そのうち1つは画面の外で行う。各ステップについて、つまずきやすい点と、その対処を対にして示す。

撤回を申請し、商品を返送する画面外の操作

行う人
顧客
つまずくところ
返送したのに返金されない、と感じる。事業者の側では、届いていない件と届いた件の区別がつかない。
どう対処するか
返送ラベルの追跡で運送会社の受け取りを記録し、返送の証明として扱う。証明が届いた時点で、待機から対応へ切り替える。

届いた荷物を照合し、検品を記録する

行う人
倉庫の返品担当
つまずくところ
どの荷物がどの件か分からない。申請と中身が違うとき、どう記録すればいいか分からない。
どう対処するか
返送ラベルの読み取りで件を開く。金額や顧客の連絡先は出さない。商品ごとに検品結果と「届いていない」「別の商品」を記録できる。

返金額を決める

行う人
サポート担当
つまずくところ
どの金額なら承認が要るのか、依頼してみるまで分からない。開いている間に検品結果が変わっても気づけない。
どう対処するか
商品ごとに提案額を示し、金額を変えた時点で承認の要否を表示する。件が更新されても入力は残し、変わった点を示す。

承認する

行う人
チームリード
つまずくところ
何を承認するのか、承認したら何が起きるのかが見えないまま押してしまう。
どう対処するか
承認する内容をボタンより先に読ませ、ボタンに金額と結果を書く。承認と同時に返金の依頼か振込の手配に進む。

返金を処理する

行う人
決済サービス
つまずくところ
処理中なのか、失敗したのか、何もしなくていいのかが分からない。失敗は依頼した人がいない時に届く。
どう対処するか
処理中は操作を置かず、今は何もしなくていいと示す。失敗と、結果が届かない件は、引き受ける人のキューに入れる。

返金後に残った仕事を片付ける

行う人
倉庫の返品担当・チームリード
つまずくところ
返金が終わると件が閉じたように見え、未着の商品や返金後の誤りが誰のものでもなくなる。
どう対処するか
返金完了と対応終了を分け、未解決の内容があれば返金後の対応に入れる。未解決の内容ごとに次に動く人を持たせる。返送の証明で先に返金した件の到着と検品は倉庫の返品担当で、問題がなければ自動で終了。傷み、返金から14日を過ぎた未着、一部商品の追加返金、返金後の誤りはチームリード。

返金は1件につき1回にまとめた。同じ返品の中で商品ごとに別々の返金を行う形にすると、1件に複数の返金処理が生まれ、後から届く結果の扱いが一気に複雑になる。一部だけ届いた件は、届いた分で返金し、残りを返金後の対応として引き受け先とともに残す。

ユーザーの視点
自分の手を離れた件が、その後どうなったかは見えにくい。依頼した返金が失敗していても、承認が取り下げられていても、本人のキューに戻ってこなければ気づけない。戻る先を状態ごとに決めておくのは、そのため。

表示の段階と操作の出し方

業務画面では、ただの情報と、危険な状態と、自分の作業が同じ見た目で並びやすい。ここでは、使い手がすべきことで段階を分け、段階ごとに見た目を割り当てている。

メッセージの5段階

各段階は、左の太い帯、アイコン、太字の見出しを持つ。状態は必ず文字で伝え、色・帯・アイコンは補助の手がかりにする。

段階使う場面
すぐ対応何かが失敗した、期限に間に合わない恐れがある。
確認してから進む前提が変わった、結果が分からない。日常の規則には使わない。
あなたの次の作業自分が引き受けている仕事。危険ではないが、自分が動かないと進まない。
待つだけ処理中、または他の人の番。今は何もしなくていい。
完了返金が完了した。

操作の出し方

操作の種類見せ方理由
画面の主な一手ブルーの塗り1画面に1つ。次に何をすればいいかを、迷わず見つけられるようにする。
お金が動く操作ブルーの塗りに金額とアイコンを入れるボタンそのものに結果を書く。「Approve and refund €184.00」のように、押す前に何が起きるか分かる。
それ以外の操作枠だけ主な一手と並んでも、どちらが先かが見て分かる。
今の状態では行えない操作置かずに、別の操作に置き換える承認が必要なら「Request approval」に、処理中なら操作を置かない。代わりに進む操作がはっきりあるので、押せないボタンを残すより迷いが少ない。

入力欄と囲み

画面の中で四角い枠を持つのは入力欄だけ。読むだけの領域は囲まず、上の線と余白で区切る。

入力欄の背景には色を付けない。グレーの面は無効の入力欄に見えやすいため。枠は中くらいのグレー(白に対して5.10:1)で、ホバーで枠がインクに、フォーカスでブルーのリングが付く。

警告の色(琥珀)は、前提が変わったときと結果が分からないときだけに使う。承認が必要という表示にも琥珀を使うと、高額の返金のたびに琥珀が出て日常の色になり、本当に前提が変わったときに目立たなくなる。

ブルーは「操作できるもの」の色で、選択・フォーカス・主な一手に使う。状態の色には青を使っていないので、選んでいるだけの行が状態に見えることはない。

ユーザーの視点
この画面を使う人は、一日中ここで作業する。目を惹く色を状態に使うと疲れるうえに、本当に危ない件が埋もれる。色が強いのは、すぐ対応が必要なときと、自分が押す一手だけにしている。

返品1件の状態

状態図は、画面の状態ではなく、返品1件の状態の移り変わりを示す。各状態には、その状態で次に動く人がいる。

申請受付顧客返送待ち顧客・運送会社未着の確認サポート担当検品待ち倉庫の返品担当判断待ちサポート担当承認待ちチームリード返金処理中決済サービス確認が必要サポート担当返金失敗サポート担当外部での返金チームリード返金完了返金後の対応チームリード・倉庫の返品担当対応終了通常の流れ人に戻る状態返金の後

人に戻る状態は、決まった時間や結果をきっかけに、人のキューへ戻る状態。返金完了の後は、未解決の仕事がある場合だけ返金後の対応を通る。図は状態のつながりを示し、それぞれの移り先のきっかけは下の一覧に載せている。

承認待ちから判断待ちへ戻る道は、差し戻しと、前提の変化による取り下げの2つ。差し戻しは独立した状態にせず、判断待ちの中の「Sent back」キューとして扱う。

確認が必要は、件の状態であって返金の状態ではない。返金そのものは処理中のまま、人に確認を戻す。返金の状態と件の状態を分けて持つことで、結果が後から届いても矛盾しない。

ユーザーの視点
状態の名前は、その状態で何をすればいいかが分かる言葉にしている。「エラー」や「保留」のような、何が起きているかだけを表す名前は避けた。

13の状態と、次に動く人

通常の流れ

  • 申請受付REQUESTED

    顧客が撤回を申請し、返送ラベルが発行された。

    次に動く人
    顧客
    移り先
    • 返送待ち
  • 返送待ちAWAITING_PARCEL

    商品の到着か返送の証明を待っている。どちらもない間は、返金の期限を保留として扱う。

    次に動く人
    顧客・運送会社
    移り先
    • 検品待ち (到着)
    • 判断待ち (返送の証明)
    • 未着の確認 (21日)
  • 検品待ちAWAITING_INSPECTION

    荷物が倉庫に届き、検品を待っている。

    次に動く人
    倉庫の返品担当
    移り先
    • 判断待ち (検品)
  • 判断待ちAWAITING_DECISION

    検品結果(または返送の証明)をもとに、サポート担当が商品ごとの返金額を決める。差し戻された件もここに戻る。

    次に動く人
    サポート担当
    移り先
    • 返金処理中 (承認不要)
    • 承認待ち (承認が必要)
    • 返金完了 (返金済み)
    • 返送待ち (残りを待つ)
  • 承認待ちAWAITING_APPROVAL

    承認の条件に当てはまる返金を、依頼した人以外のチームリードが判断する。

    次に動く人
    チームリード
    移り先
    • 判断待ち (差し戻し・取り下げ)
    • 返金処理中 (承認(決済サービス))
    • 外部での返金 (承認(銀行振込))
  • 返金処理中REFUND_PROCESSING

    決済サービスに返金を依頼し、結果を待っている。人の対応は不要。

    次に動く人
    決済サービス
    移り先
    • 返金完了 (成功)
    • 返金失敗 (失敗)
    • 確認が必要 (48時間)
  • 返金完了REFUNDED

    返金が完了した。未解決の仕事がなければ対応終了、あれば返金後の対応へ進む。

    移り先
    • 対応終了 (未解決なし)
    • 返金後の対応 (未解決あり)
  • 対応終了CLOSED

    この返品で残っている仕事はない。終了の後に検品や完了の記録の誤りが見つかった場合は、返金後の対応に戻る。

    移り先
    • 返金後の対応 (終了後の誤り)

人に戻る状態

  • 未着の確認NOT_RECEIVED_CHECK

    撤回の通知から21日を過ぎても、到着も返送の証明もない。サポート担当が運送会社の記録と顧客に確認する。

    次に動く人
    サポート担当
    移り先
    • 検品待ち (到着)
    • 判断待ち (返送の証明)
  • 確認が必要NEEDS_CHECK

    依頼から48時間、決済サービスの結果が届いていない。返金そのものは処理中のまま、人に戻す。

    次に動く人
    サポート担当
    移り先
    • 返金完了 (結果が判明)
    • 返金失敗 (結果が判明)
    • 返金処理中 (処理中と判明)
  • 返金失敗REFUND_FAILED

    決済サービスが返金の失敗を返した。期限は止まらない。

    次に動く人
    サポート担当
    移り先
    • 返金処理中 (同じ方法で再依頼)
    • 承認待ち (返金先の変更)
  • 外部での返金EXTERNAL_REFUND

    返金先を銀行振込に変えて承認された。経理が振込を行い、チームリードが証跡を付けて完了を記録する。

    次に動く人
    チームリード
    移り先
    • 返金完了 (完了の記録)

返金の後

  • 返金後の対応AFTER_REFUND

    返金は終わったが、引き受ける人のいる仕事が残っている。返送の証明で先に返金した件の「到着と検品」は倉庫の返品担当が引き受け、問題がなければ自動で対応終了になる。傷みがあるか、返金から14日を過ぎても届かなければチームリードへ移る。一部商品の追加返金と、返金後に見つかった誤りは、最初からチームリードが引き受ける。

    次に動く人
    チームリード・倉庫の返品担当
    移り先
    • 対応終了 (結果の記録)

エッジケース

H・R・Pの3つに分けている。人の手を渡る流れ、後から届く結果、条件で変わる承認。番号はこの仕様書内の参照番号で、シフトのサンプルのB・A・Sとは別のもの。

各項目には「引き受ける人」と「次の操作」を持たせている。通知やエラーを出すだけで解決したことにせず、誰が拾い、何をすれば次へ進むかまでを仕様として決める。

表示内容は製品の表示言語である英語のまま載せている。文言はすべてフロントエンドで定義する。

人の手を渡る流れ

1件の返品が、数日かけて3つの役割の間を渡る。止まっている間に引き受ける人がいない状態を作らない。

全6項目の詳細
H1

担当中の件を、別のサポート担当が開く

表示内容
Tom Weber is working on this return (last action 18 Oct). If you take it over, you become the support agent for this return.
挙動
閲覧はできる。操作は「Take over」だけを置き、引き継いだことは経過に記録する。保存時の照合はシフトのサンプルのS4と同じ考え方。
理由
2人が同時に判断を進めると、顧客への連絡も返金額も二重になる。ロックにしないのは、担当者が不在のときに件が止まらないようにするため。
ユーザーの視点
「担当中」と出ても、本人は休みかもしれない。最後の操作日時が見えれば、待つか引き継ぐかを自分で判断できる。
引き受ける人
その件のサポート担当(引き継いだ場合は、引き継いだサポート担当)
次の操作
待つか、引き継ぐ。
H2

その件のサポート担当が動かないまま、期限が近づく

表示内容
Due in 2 days. No action for 3 days.
挙動
期限まで3日以内で、最終操作から2営業日を過ぎた件を、チームリードの「Stalled」キューにも出す。サポート担当のキューからは外さない。判定はサーバーが行う。
理由
担当者が不在でも、誰の目にも入らないまま期限を迎えないようにする。
引き受ける人
チームリード
次の操作
別のサポート担当に割り当て直すか、自分で引き受ける。
H3

返送待ちのまま、商品が届かない

表示内容
On hold: not received / Not received · proof of return / It has been 21 days since the withdrawal, and neither the item nor proof of return has arrived.
挙動
到着も返送の証明もない間は、期限を保留として表示する。返送ラベルの追跡で運送会社の受け取りが分かればシステムが、顧客から控えが届けばサポート担当が、証明として記録し、判断待ちへ移す。撤回の通知から21日を過ぎても到着も証明もなければ、「Not received」キューに入れる。証明で先に返金した件は、返金完了の後に返金後の対応へ移し、「到着と検品」を未解決の内容として残す。届いたら倉庫の返品担当が検品し、問題がなければ自動で対応終了。傷みがあるか、返金から14日を過ぎても届かなければ、チームリードへ移る。
理由
EUの撤回権では、事業者が返金を保留できるのは、商品の到着か返送の証明の早い方まで。新しい情報が届いた時点で、待機から対応へ切り替える必要がある。21日は、返送の期限14日に輸送の余裕7日を足した架空の社内基準。返金後に問題なく届いた件までチームリードに回すと、例外ではない仕事でリードのキューが埋まる。
ユーザーの視点
保留できる件まで急ぎに見えると、本当に急ぐ件が埋もれる。かといって放置すれば、顧客を待たせ続ける。
引き受ける人
証明があれば、その件のサポート担当。「Not received」はサポート担当の共有キューで、引き受けた人がその件のサポート担当になる。返金後に届いた商品の検品は倉庫の返品担当、傷みや未着はチームリード。
次の操作
証明があれば、検品前の返金として承認を依頼する。なければ運送会社の記録を確認し、顧客に連絡する。
H4

届いたものが申請と一致しない(申請2点のうち1点だけ届いた、など)

表示内容
Parcel arrived · 1 of 2 items / Your next step: Coffee grinder has not arrived
挙動
倉庫の返品担当が、商品ごとに「届いていない」「別の商品」を記録する。件は不一致の印を付けて判断待ちへ進む。サポート担当が残りを待つことを選んだら、返送待ちに戻す。返金は1件につき1回。届いた分で進めた場合は、返金完了の後に返金後の対応へ移し、未解決の内容を記録する。残りが届いたら倉庫の返品担当が検品を記録でき、チームリードに戻る。
理由
届いていない商品まで返金すると、取り戻しにくい。全部が揃うまで待つと、届いた分の返金まで遅れる。2回目の返金はこの画面の範囲外とし、範囲外に出した仕事にも引き受け先を残す。
引き受ける人
記録は倉庫の返品担当、判断はその件のサポート担当、返金後に残った分はチームリード
次の操作
サポート担当は、残りを待つか、届いた分で進めるかを選ぶ。チームリードは、残りの結果を記録して対応を終える。
H5

検品結果が修正される

表示内容
Changed since you asked: Coffee grinder inspection, No issues → Signs of use (Jonas Berg, 26 Oct).
挙動
返金の依頼前なら修正でき、理由の入力は必須。判断待ちならそのまま判断し直す。承認待ちなら依頼を取り下げる(P3)。依頼の後は倉庫側に修正の操作を置かず、誤りはチームリードが返金後の対応として扱う。対応終了の後に見つかった場合も、返金後の対応に戻す。
理由
判断の前提が、判断した人の知らないうちに変わらないようにする。
引き受ける人
修正は倉庫の返品担当、判断し直すのはその件のサポート担当、返金後はチームリード
次の操作
サポート担当は、変わった点を確認して返金額を見直す。
H6

金額を入力している間に、件が更新される

表示内容
This return was updated (Coffee grinder inspection). Your amounts have been kept. / Lena Vos assigned this return to Tom Weber.
挙動
画面を開いている間は返品1件を定期的に取得し、状態・次に動く人・出せる操作を更新する。入力中の金額は上書きしない。その入力の前提になったversionも保持し、定期取得した最新のversionに自動で差し替えない。送信の時点でサーバーが照合し、前提が変わっていれば止める。担当が変わった場合は、操作が出なくなった理由を示す。
理由
定期的な更新が入力中の値を消すと、それ自体が新しい事故になる。一方で、金額だけ古い判断のまま残してversionだけ最新にすると、意図した競合の検出が働かなくなる。
ユーザーの視点
打ち込んだ金額が消えると、何を入れていたか思い出せないまま入れ直すことになる。
引き受ける人
その件のサポート担当
次の操作
変わった点を確認し、金額を見直して送信する。

後から届く結果

決済サービスの結果は、依頼した人が画面を離れた後に届くことがある。成功と失敗に加えて「まだ分からない」を状態として扱う。

全5項目の詳細
R1

返金を依頼し、決済サービスの結果を待っている

表示内容
Waiting for the payment provider. … There is nothing to do on this return right now. Tell the customer the refund is complete only after the result arrives.
挙動
依頼の操作を置かない。結果が届いたら状態を更新し、経過に記録する。
理由
処理中に二重に依頼すると、二重返金になる。
ユーザーの視点
何もしなくていいと分からないと、不安から顧客に先に「返金しました」と伝えたり、別の方法で返金しようとしたりする。「今は何もしなくていい」も、次の操作の答えの一つ。
引き受ける人
決済サービス(人の対応は不要)
次の操作
待つ。結果が出たら返金完了か返金失敗へ。
R2

返金の依頼に応答が返らない

表示内容
We couldn’t confirm whether the refund request was received. Checking again will not refund the customer twice. / There is no record of this request on the server. Sending it again with the same details will not refund the customer twice.
挙動
依頼ごとに一意のキーを付けて送る。「Check result」では返品1件を取得し直し、そのキーで依頼を探す。見つかればその状態を表示する。見つからなければ「未実行」とは表示せず、同じキーでの再送を置く。この件に処理中の返金がある間は、別のキーによる新しい依頼をサーバーが受け付けない。
理由
応答がないことは、失敗を意味しない(シフトのサンプルのS1と同じ考え方)。返金IDを受け取れていなくても、返品番号から確かめられるようにする。
引き受ける人
返金を依頼した人。承認が不要な件ではその件のサポート担当、承認が必要な件では承認したチームリード。
次の操作
結果を確認する。それでも分からなければR4へ。
R3

後日、返金が失敗する

表示内容
Refund failed on 25 Oct. Reason from the payment provider: the card is no longer valid. This is on the customer’s side, so the same payment method won’t work. The refund is still due by 30 Oct.
挙動
返金失敗のキューに入れる。失敗の理由を、顧客側の理由と一時的な理由に分けて表示する。一時的な理由なら「Try the same method again」、顧客側の理由なら「Confirm bank details and request approval」を置く。
理由
理由によって次の手が違う。失敗しても期限は止まらない。返金先の変更は不正の手口にもなるため、承認を通す。
引き受ける人
その件のサポート担当。不在ならチームリード。
次の操作
同じ方法で依頼し直すか、顧客に振込先を確認して承認を依頼する。
R4

依頼から48時間、決済サービスの結果が届かない

表示内容
No result from the payment provider 48 hours after the request.
挙動
件を「Needs check」へ移す。返金そのものの状態はpendingのまま。自動で依頼し直さない。結果を人が手で記録する操作は置かない。問い合わせで、決済サービスの側で処理が続いていると分かれば返金処理中に戻し、48時間の判定はその時点から数え直す。
理由
手で記録した状態と決済サービスの実際の状態がずれると、どちらが正しいか分からなくなる。
引き受ける人
その件のサポート担当。状態を取得し直しても分からなければ、チームリード。
次の操作
決済サービスに状態を問い合わせ直す。
R5

同じ注文に、別の経路ですでに返金された額がある

表示内容
€89.00 has already been refunded for this order (payment provider record). You can request up to the remaining €95.00.
挙動
決済サービスの返金記録を、返金額の上限に反映する。全額返金済みなら「Mark as already refunded」を置き、理由の入力は必須。件は返金完了へ進み、未着の商品などの仕事が残っていれば返金後の対応、なければ対応終了になる。
理由
決済サービスの管理画面から直接返金されることは、実際にある。決済サービスの記録を正とする。
引き受ける人
その件のサポート担当
次の操作
残額だけを依頼するか、理由を付けて返金済みとして記録する。

条件で変わる承認

承認は、承認した時点の事実に結びつく。前提が変わったら判断した人に戻し、承認したら間を空けずに実行へ進む。

全6項目の詳細
P1

返金が承認の条件に当てはまる

表示内容
Needs a team lead’s approval. The total is €150 or more. A team lead reviews it, and the refund is sent as soon as it is approved.
挙動
金額を変えるたびに判定し、操作を「Request approval」に切り替える。条件(€150以上、検品前の返金、提案額を超える返金、返金先の変更)はサーバーから受け取り、画面側で固定しない。依頼の時点でもサーバーが判定し直す。
理由
依頼した後で承認が必要と返すと、やり直しになる。承認は高額の返金にとって普通の流れなので、警告の色ではなく「次の作業」の段階で示す。
引き受ける人
その件のサポート担当
次の操作
承認を依頼する。
P2

チームリードが、自分で承認を依頼した件を開く

表示内容
You requested approval for this return, so another team lead approves it.
挙動
自分の依頼は承認キューに出さない。承認できるのは、依頼した人以外のチームリード。チームリードが1人しかいない日は、代理の承認者が承認する(架空の社内ルール)。
理由
返金は取り戻せない操作なので、依頼と承認を同じ人にしない。
引き受ける人
別のチームリード(いなければ代理の承認者)
次の操作
承認するか、差し戻す。
P3

承認待ちの間に、検品結果か金額が変わる

表示内容
Your approval request was withdrawn. Changed since you asked: … / This request was withdrawn. No action needed.
挙動
サーバーが依頼を取り下げ、判断待ちに戻す。承認の時点でもサーバーが照合する(シフトのサンプルのS4と同じ考え方)。開いていたチームリードには、対応が不要になったことを示す。
理由
承認は、承認した時点の事実に対するもの。前提が変わったら、判断した人に戻す。
引き受ける人
その件のサポート担当
次の操作
変わった点を確認し、返金額を見直して承認を依頼し直す。
P4

承認の依頼が差し戻される

表示内容
Sent back by Lena Vos: Signs of use, so please consider a reduced amount instead of a full refund.
挙動
差し戻しの理由は入力必須。判断待ちに戻し、サポート担当の「Sent back」キューに入れる。
理由
理由がなければ、何を直せば通るのか分からない。
引き受ける人
承認を依頼したサポート担当(その件のサポート担当)。不在ならチームリード。
次の操作
金額を直して依頼し直すか、顧客と相談してから依頼し直す。
P5

チームリードが承認する

表示内容
Approve and refund €184.00 / Approve and arrange transfer €95.00
挙動
承認モーダルには、依頼時のスナップショット(商品ごとの金額、合計、当てはまった条件、返金先、依頼した人)を表示する。承認と同時に、決済サービスへの返金の依頼か、経理への振込の手配に進む。
理由
承認と依頼の間を空けないことで、承認済みなのに誰も依頼していない状態をなくす。ボタンに金額と結果を書き、押す前に何が起きるか分かるようにする。
引き受ける人
依頼した人以外のチームリード
次の操作
承認するか、差し戻す。
P6

外部での返金(銀行振込)の完了を記録する

表示内容
Your next step: record the bank transfer / Bank transfer of €95.00 completed · recorded by Lena Vos · proof of payment attached (FIN-2026-0412)
挙動
振込は経理が画面の外で行う。完了はチームリードが、実行日・金額・経理の参照番号・証跡を付けて記録する。金額が承認額と違えば受け付けない。経過では、決済サービスからの結果と区別して表示する。記録の取り消しは置かず、誤りは返金後の対応として扱う。対応終了の後に見つかった場合も同じ。
理由
決済サービスを通らない返金は、結果が自動では届かない。人による記録は、誰がいつ何を根拠に記録したかが残ってはじめて、決済サービスからの結果と並べて扱える。
引き受ける人
チームリード(振込の実行は経理)
次の操作
振込が済んだら、証跡を付けて完了を記録する。

APIの仕様

以下の5つは、見せたい設計に必要な範囲に絞ったAPI仕様案。倉庫の検品の記録、引き継ぎ、未着の確認などは画面の設計で伝わるため、ここには書いていない。決済サービスからの通知(webhook)は、サーバー側の実装として存在だけを前提にしている。

まずフロントエンドが、各画面でいつどんなデータが必要かを示す。バックエンドが返せる形を提案し、それを受けてフロントエンドでどう扱うかを決める。各エンドポイントには、このやり取りを記している。

金額はすべてセント単位の整数で表す(€184なら18400)。小数で持つと計算の誤差が出るため。

1フロントエンドから求めたこと

2バックエンドからの回答

3それを受けて決めたこと

1. 返品1件を取得

GET /api/returns/R-1042
1

状態と次に動く人、その件のサポート担当、期限(保留中かどうかを含む)、商品ごとの検品結果と提案額、承認が必要かどうか、決済サービス側ですでに返金された額が必要。どの操作を出すかは状態と役割と担当の組み合わせで決まるが、そのルールを画面側に持たせたくない。返金IDを受け取れなかった場合も、この件の依頼の有無を確かめたい。

2

出せる操作の判定はサーバーで可能。決済サービスの返金記録は、開くたびに問い合わせると遅くなるので、決済サービスからの通知で更新した記録を、更新時刻とともに返す。この件にひもづく返金の依頼と承認の依頼も含められる。

3

出せる操作は、出せない理由のコードとあわせて受け取る。承認の条件はレスポンスで受け取り、金額を編集している間の判定(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)。

2. 返金を依頼

POST /api/returns/R-1051/refunds
Idempotency-Key: 4f9b2c1e-...

{ "expectedVersion": 4, "items": [{ "itemId": "it_1", "amount": 7900 }, { "itemId": "it_2", "amount": 2900 }, { "itemId": "it_3", "amount": 2500 }] }
1

応答が返らないときに再送しても、二重返金にならないことを保証したい(R2)。受け付けた時点で返金処理中にしたいが、完了と混同させたくない(R1)。

2

決済サービス自体が依頼ごとの一意のキーに対応しているので、画面から受け取ったキーをそのまま渡せる。依頼は受け付けの結果だけをすぐ返し、最終結果は決済サービスからの通知で後から更新する。

3

キーは返金の依頼を始めた時点で1回だけ作り、再送時も同じキーを使う。応答は202(受け付け)だけで、画面は受け付けを完了として表示しない。

レスポンスの形式

202 — 受け付け

{ "result": "accepted", "refundId": "rf_301", "status": "pending", "version": 5 }

422 — 承認が必要(金額が条件に当てはまっていた場合。P1の再判定)

{ "result": "rejected", "code": "APPROVAL_REQUIRED", "conditions": ["AMOUNT_THRESHOLD"] }

422 — 返金済みの額を超える(R5)

{ "result": "rejected", "code": "AMOUNT_EXCEEDS_REMAINING", "remaining": 10400 }

409 — 前提の変化(H6)

{ "result": "conflict", "code": "STALE_DATA", "version": 6, "changed": ["items.it_2.grade"] }

409 — 処理中の返金がある(R2)

{ "result": "conflict", "code": "REFUND_IN_PROGRESS", "refundId": "rf_301" }

サーバーは、決済サービスに送る前にキーと依頼の内容を記録する。そのため、応答が届かなくても、返品1件の取得で依頼の有無と状態を確かめられる。

同じキーで再送されたら、新しい依頼を作らず最初の依頼の結果を返す。この件に処理中の返金がある間は、別のキーによる新しい依頼を受け付けない。画面の再読み込みなどでキーが失われた場合でも、二重返金を状態の側で防ぐため。

承認が必要な件では、このAPIは使わない。承認の判断(4)がサーバーの中で同じ処理を起動し、キーもサーバーが作る。

3. 返金の状態を取得

GET /api/returns/R-1090/refunds/rf_290
GET /api/returns/R-1090/refunds/rf_290?refresh=true
1

結果は後から届くので、画面を開いている間に状態が変われば反映したい。開いていなくても、失敗はキューに出したい。「Check result」にも使いたい。

2

状態は決済サービスからの通知でサーバー側が更新する。画面への即時の通知の仕組みは、今回のサービスにはない。必要なときは、サーバーから決済サービスに直接問い合わせることもできる。

3

件の状態・次に動く人・出せる操作の更新は、返品1件の取得(1)で行う。このAPIは、失敗の理由などの返金の詳細と、refresh=trueによる決済サービスへの問い合わせ(R2、R4)に使う。キューへの反映はサーバー側の状態で行うので、画面を開いているかどうかに左右されない。

リクエストとレスポンスの形式
{
  "refundId": "rf_290",
  "status": "failed",
  "failure": { "category": "customer", "code": "CARD_INVALID" },
  "source": "payment_provider",
  "updatedAt": "2026-10-25T03:40:00Z"
}

failure.categoryは、決済サービスの失敗コードをサーバーが顧客側(customer)と一時的(temporary)に分けたもの(R3)。決済サービス固有のコードを画面側で解釈しない。

48時間結果が届かない場合、返金の状態はpendingのまま、件の状態を確認が必要に移す(R4)。返金の状態と件の状態は別に持つ。

sourceは、決済サービスからの結果ならpayment_provider。外部での返金の記録(5)はmanual_recordで、経過の表示でも区別する。

4. 承認を依頼する/判断する

POST /api/returns/R-1042/approval-requests
{ "expectedVersion": 7, "items": [...], "destination": { "type": "original_payment" } }

POST /api/approval-requests/ap_55/decision
{ "decision": "approve", "expectedSnapshotVersion": 1 }
1

承認モーダルには、承認の対象(商品ごとの金額、合計、当てはまった条件、返金先、依頼した人)を表示したい。承認した内容と、実際に返金される内容が同じであることを保証したい。依頼の後に前提が変わったら、自動で取り下げたい(P3)。

2

承認の依頼の時点で、金額と検品結果と返金先をスナップショットとして保存できる。検品結果や金額が更新されたら、サーバー側で依頼を取り下げられる。依頼した人と承認する人が同じかどうかも、サーバーで判定できる(P2)。

3

承認モーダルは、件の現在の値ではなくスナップショットを表示する。承認の結果、決済サービスへの依頼と経理への手配のどちらに進んだかは、レスポンスで受け取る(P5)。

レスポンスの形式

200 — 承認(決済サービス経由)

{ "result": "approved", "next": { "type": "provider_refund", "refundId": "rf_302", "status": "pending" } }

200 — 承認(外部での返金)

{ "result": "approved", "next": { "type": "external_transfer", "transferId": "tr_12", "status": "awaiting_finance" } }

409 — 取り下げ済み(P3)

{ "result": "conflict", "code": "REQUEST_WITHDRAWN", "changed": ["items.it_2.grade"] }

403 — 自分の依頼(P2)

{ "result": "forbidden", "code": "SELF_APPROVAL_NOT_ALLOWED" }

差し戻しはdecisionをrejectにし、理由を必須にする(P4)。理由がなければ422。

承認と返金の記録(pending)は一緒に保存し、決済サービスへの送信はその後にサーバーが行う。送信に失敗しても記録が残るので、同じキーで送り直せる。承認だけが成立して、返金の依頼がどこにも残らない状態を作らない。

外部での返金の振込先はスナップショットに含めるが、画面には口座番号の末尾4桁だけを出す。

5. 外部での返金の完了を記録

POST /api/external-transfers/tr_12/completion
Content-Type: multipart/form-data

executedAt: 2026-10-28
amount:     9500
reference:  FIN-2026-0412
evidence:   (振込の証跡ファイル)
1

決済サービスからの結果と、人が記録した完了を、画面の上で区別して見せたい。記録の誤りも防ぎたい。

2

証跡のファイルを保存でき、記録した人と時刻も残せる。金額は、承認されたスナップショットと照合できる。

3

証跡は必須。金額がスナップショットと違えば受け付けない。記録はmanual_recordとして保存し、経過では記録した人と証跡があることを示す(P6)。記録できるのはチームリード。承認した本人に限らないのは、本人が不在でも完了を記録できるようにするため。

レスポンスの形式

200 — 記録済み

{ "result": "recorded", "transferId": "tr_12", "status": "completed", "source": "manual_record" }

422 — 金額の不一致

{ "result": "rejected", "code": "AMOUNT_MISMATCH", "approved": 9500, "entered": 9000 }

記録の取り消しの操作は置かない。誤りがあった場合は、返金後の対応として扱う。

画面仕様設計書がエンジニアに任せること

この画面仕様設計書で決めるのは、どの状態で誰が引き受けるか、何をいつ表示するか、どのデータをどちらが正とするか、メッセージに何を書くか。

どう実装するかはエンジニアに任せる。返品1件を取得する間隔と通信の方法、決済サービスからの通知の受け取り方と再試行、停滞や48時間の判定を動かす仕組み、コンポーネントとstateの構成など。

引き受ける人と次の操作を決めないままにすると、その判断は実装中に、エラーメッセージの文言として行われる。先に決めておけば、エンジニアは定義された挙動をもとに、実装方法の判断に集中できる。

このサンプルについて

画面はFigmaで設計した。トークン(色・余白・角丸・文字)、コンポーネント、11の状態の画面、主な4画面のアクセシビリティの注記を含む。色の組み合わせは、すべてWCAG 2.2のAAで確認している。

シフトのサンプルと同じトークンの構造を使い、値だけをこの製品に合わせている。一つの設計体系を、別の業務と別のブランドに載せ替えた例でもある。

設計を見る

このページで使用

React / TypeScript / Next.js / Tailwind CSS

設計で使用

Figma(Variables、コンポーネントのバリアントとプロパティ)