j1.4.11
API の概要
Orders API を使用して、注文ステータスや注文支払ステータスの更新、配送先住所やカスタム注文プロパティの編集、注文支払手段の管理、および注文情報の取得を行います。
認証と認可
注文情報をリクエストするクライアントは、Order リソースへのアクセスが必要です。API リクエストでは、リクエストのヘッダーにシステムからシステムへのベアラートークンを渡します。POST /orders エンドポイントは ShopperTokenTsob セキュリティスキームを使用します。
SLAS トークンの生成に使用するクライアント ID には、関連するスコープを含める必要があります。詳細については、認可スコープカタログを参照してください。
注文ステータスの更新
注文では、ワークフロー状態を定義するために複数のステータスプロパティを使用します。これらの一部は、在庫の割り当てなど、内部プロセスをトリガーするために使用されます。その他にはデフォルトの機能はありませんが、カスタマイズで使用できます。
注文ステータス
注文ステータスは、注文全体のステータスを表します。注文ステータス間の遷移により、請求書の生成や在庫予約の解放などのアクションがトリガーされます。
注文ステータスには、次のいずれかの値を設定できます。
created- デフォルト値です。注文がシステム内で作成されているが、まだ確定されていないことを示します。new- 注文を確定するには、この値を設定します。この値を設定すると、システムは出荷番号と請求書番号を生成します。注文の確定後は、注文ステータスをcreatedまたはfailedに変更することはできません。failed- たとえば、注文を拒否した場合や支払いに失敗した場合に、注文を失敗にするにはこの値を設定します。この値を設定すると、システムは注文の在庫予約を解放し、クーポン使用をすべて削除します。この値を設定できるのは、現在の注文ステータスがcreatedの場合のみです。注文ステータスをfailedからcreatedに変更すると、システムはfailedの設定時に実行されたアクションの取り消しを試みます。在庫が利用できない場合は、取り消しに失敗することがあります。failed_with_reopen- 該当する場合は、注文を失敗にし、買い物カゴを再度開くにはこの値を設定します。注文ステータスはfailedに設定されます。completed- ビジネスプロセスに基づいて注文を完了としてマークするには、この値を設定します。たとえば、注文の支払い、エクスポート、出荷がすべて完了した場合です。cancelled- たとえば、買い物客が要求した場合に注文をキャンセルするには、この値を設定します。この値を設定すると、システムは注文の在庫予約を解放し、ほしい物リストの商品を復元し、クーポン使用をすべて削除します。注文ステータスをcancelledからcompletedまたはnewに変更すると、システムはcancelledの設定時に実行されたアクションの取り消しを試みます。在庫が利用できない場合は、取り消しに失敗することがあります。
確認ステータス
注文確認は、ベンダーが買い物客に送信する文書です。これは、注文が受領され、受け付けられたことを確認するものです。確認ステータスは、この文書の状態を反映するため、またはその他のカスタマイズのために使用できます。このフィールドはカスタマイズで使用するために提供されています。デフォルト機能には関連付けられていません。
確認ステータスには、次のいずれかの値を設定できます。
not_confirmed- デフォルト値です。confirmed- 注文確認が買い物客に送信されたときに、この値を設定します。
エクスポートステータス
注文が確定されると、フルフィルメントを行う必要があります。プロセスに倉庫管理システム (WMS) などの外部フルフィルメントシステムが含まれる場合は、エクスポートステータスを使用して、注文データの外部システムへのエクスポートを管理できます。たとえば、GET /orders エンドポイントを使用してエクスポート対象の注文データを取得した後、注文のエクスポートステータスを exported に設定します。エクスポートする注文を特定する場合、クエリにはエクスポートステータスが ready の注文を含め、エクスポートステータスが exported の注文を除外できます。
エクスポートステータスには、次のいずれかの値を設定できます。
not_exported- デフォルト値です。ready- (カスタム用途) 注文のエクスポート準備ができたときに、この値を設定します。exported- 注文がエクスポートされたときに、この値を設定します。この値を設定すると、システムは注文の在庫トランザクションを確定します。failed- (カスタム用途) 注文のエクスポートが失敗したときに、この値を設定します。
外部ステータス
外部ステータスフィールドには、任意の文字列値を保持できます。たとえば、外部フルフィルメントシステムに関連する値に使用できます。このフィールドはカスタマイズで使用するために提供されており、デフォルト機能には関連付けられていません。
支払ステータス
支払ステータスは、注文の支払いが一部完了しているか、または全額完了しているかを示すために使用します。このフィールドはカスタマイズで使用するために提供されており、デフォルト機能には関連付けられていません。
支払ステータスには、次のいずれかの値を設定できます。
not_paid- デフォルト値です。part_paid- 注文の支払いが一部完了したときに、この値を設定します。paid- 注文の支払いが全額完了したときに、この値を設定します。
配送ステータス
配送ステータスは、注文の出荷が一部完了しているか、または全量完了しているかを示すために使用します。このフィールドはカスタマイズで使用するために提供されており、デフォルト機能には関連付けられていません。
配送ステータスには、次のいずれかの値を設定できます。
not_shipped- デフォルト値です。part_shipped- 注文が一部出荷されたときに、この値を設定します。shipped- 注文が全量出荷されたときに、この値を設定します。
シナリオ例:
- 不正チェックと支払い承認が成功した後、注文ステータスを
newに設定します。 - 不正チェックまたは支払い承認が失敗した後、注文ステータスを
failedに設定します。 - 注文情報が倉庫システムにエクスポートされた後、エクスポートステータスを
exportedに設定します。 - 倉庫が注文を出荷した後、配送ステータスを
shippedに設定します。
配送先住所の変更
Orders API を使用して、注文の配送先住所を更新します。
たとえば、買い物客が注文を行った後、その注文の配送先住所の変更をリクエストする場合です。
注文データの取得
注文の取得、レポート、ダッシュボードなどには、Orders API のシステム間連携ユースケースを使用します。注文番号を指定して 1 件の注文に関する情報を取得することも、属性フィルターを使用して検索し、複数の注文に関する情報を取得することもできます。
使用できる属性フィルターは次のとおりです。
- 注文ステータス
- エクスポートステータス
- 外部ステータス
- 確認ステータス
- 支払ステータス
- 配送ステータス
- 作成日 (開始日/終了日)
- 最終更新日 (開始日/終了日)
- offset
- limit
次の属性を使用して、結果を昇順または降順で並べ替えることができます (デフォルト: 降順)。
- 作成日
- 最終更新日
注文の作成
createOrders エンドポイントを使用して、ソーシャルメディアプラットフォームなどのサードパーティシステムから注文を作成します。エンドポイントを使用する前に、まず注文手続き処理を完了する必要があります。つまり、すべての妥当性チェックの適用、在庫予約、支払い承認、プロモーションの適用、および注文の総コストの計算を完了しておく必要があります。サードパーティシステムによって作成された注文は、ステータス更新やエクスポートの処理方法を含め、B2C Commerce プラットフォームを通じて直接作成された注文と同様に扱われます。
注文の更新
updateOrder エンドポイントを使用して、カスタム注文属性を変更します。
Let us know so we can improve!