j1.1.22
APIの概要
Inventory Reservation API を使用すると、Omnichannel Inventory を使用して予約の作成、管理、フルフィルメントを行えます。
Inventory Reservation API は、次の機能カテゴリに分類できます。
| カテゴリ | エンドポイントの説明 |
|---|---|
| 予約管理 | 注文予約データを作成および編集するための API エンドポイント。予約数量は、注文可能数量やフルフィルメント可能数量に影響します。 |
注: Omnichannel Inventory では、組織 ID の代わりにテナントグループ ID を使用します。詳細については、ベース URL とリクエストの作成を参照してください。
レート制限
ロードシェディングとレート制限の詳細については、ロードシェディングとレート制限を参照してください。
認証と認可
Omnichannel Inventory を呼び出すクライアントは、次の 2 つのいずれかの方法で認証できます。
- B2C Commerce の認証情報を使用して Account Manager で認証します。
- Salesforce org の認証情報を使用して認証します。
B2C Commerce と Salesforce Order Management の両方を使用している場合は、どちらの認証アプローチも使用できます。ただし、統合全体でアプローチが混在するのを避けるため、どちらか 1 つのみを選択することを推奨します。
認証アプローチが異なっていても、API の用途やパフォーマンスには影響しません。
各認証アプローチでは、それぞれ固有のスコープセットを使用します。
| Account Manager 認証のスコープ | Salesforce org 認証のスコープ |
|---|---|
| sfcc.inventory.impex-graphs | sfcc_inventory_impex_graphs |
| sfcc.inventory.impex-inventory.rw | sfcc_inventory_impex_inventory_rw |
| sfcc.inventory.impex-inventory | sfcc_inventory_impex_inventory |
| sfcc.inventory.availability | sfcc_inventory_availability |
| sfcc.inventory.availability.rw | sfcc_inventory_availability_rw |
| sfcc.inventory.reservations | sfcc_inventory_reservations |
| sfcc.inventory.reservations.rw | sfcc_inventory_reservations_rw |
API ゲートウェイ経由で Omnichannel Inventory を呼び出す場合は、有効な OAuth ベアラートークンが必要です。Omnichannel Inventory で使用されるテナント識別子は、トークンのヘッダーで指定されます。
すべてのリクエストボディおよびレスポンスボディのエンティティは、JSON で構成されます。
ユースケース
予約管理
これらの API エンドポイントを使用すると、注文予約データを作成および編集できます。予約数量は、注文可能数量およびフルフィルメント可能数量に影響します。
在庫の予約
このエンドポイントでは、クライアント注文を表すデータをリクエストボディに含めます。レスポンスボディには、Omnichannel Inventory が予約できた品目が含まれます。予約できた数量は、_要求した数量より少ない場合があります_。
予約の更新とキャンセル
このエンドポイントは、主に既存の予約にアイテムを追加するために使用します。予約 ID は URL の一部として指定され、その ID を使用して更新対象の予約ドキュメントを特定します。レスポンスボディには、追加できた品目に関する情報に加え、追加できなかった品目と、その失敗理由が含まれます。
このエンドポイントは、予約時に作成された予約 ID がある場合に、予約リクエストをキャンセルするためにも使用します。これは推奨されるキャンセル方法であり、予約 ID が利用可能な場合は常にこの方法を使用してください。予約 ID を指定して Cancel Reservation エンドポイントを使用すると、予約ドキュメントはキャンセル済みとしてマークされ、OCI は予約ドキュメントの詳細に基づいて予約数と在庫数を調整します。
予約数量の解放
このエンドポイントを使用すると、リクエストボディで指定した数量、SKU、および場所識別子 (group または location) に基づいて、以前に予約した数量を解放できます。このエンドポイントは、予約 ID を利用できない状況にある場合や、解放対象の詳細 (SKU、および Group または Location) を直接指定するほうが容易な場合のために提供されています。最終的な効果は Cancel Reservation エンドポイントを使用する場合と同じです。Unreserve を実行すると、予約ドキュメントの詳細ではなく、呼び出しで指定した詳細に基づいて、location または group から予約数が削除されます。
予約数量の移動
このエンドポイントを使用すると、リクエストボディで指定した数量と場所識別子に基づいて、group と location の間、location と group の間、または 2 つの location 間で予約数量を移動できます。予約の移動には、予約 ID は必要ありません。group 間または location 間の予約移動は OMS で決定され、予約済み数量をある group/location から別の group/location へ移動するだけで済みます。最初の予約ドキュメントを意識したり、変更したりする必要はありません
数量のフルフィルメント
このエンドポイントを使用すると、リクエストボディで指定した SKU、数量、および場所識別子 (group または location) に基づいて、location で予約数量のフルフィルメントを行えます。予約のフルフィルメントは、クライアントが注文を出荷し、予約数量と手持在庫数量が正しいことを保証する必要がある場合に行われます。これは、すべての値が正常に更新されることを保証するためのアトミック操作です。
エラーを含むレスポンスが返された場合、呼び出し元はリクエスト全体を再送信しないようにする必要があります。再送信すると、EntityAlreadyExists エラーレスポンスが返されます。HTTP 200 レスポンスを解析してエラーのある SKU を確認し、各 SKU を個別に処理して、再送信が必要かどうかを判断する必要があります。
以下の表は、システム内で発生し得る条件の例と、それらの条件に基づいて fulfill 呼び出しから想定されるレスポンスを示しています。
| 条件 | リクエスト | 結果 |
|---|---|---|
| 手持在庫 = 0、予約済み数量 = 1 | 数量 1 のフルフィルメントを要求 | エラーなしで予約がフルフィルメントされます |
| 手持在庫 = 1、予約済み数量 = 0 | 数量 1 のフルフィルメントを要求 | 数量不足の例外がスローされ、手持在庫は変わりません |
| 手持在庫 = 2、予約済み数量 = 1 | 数量 2 のフルフィルメントを要求 | 数量不足の例外がスローされ、手持在庫は 2 のまま、予約済み数量は 1 のままです |
| 手持在庫 = 1、予約済み数量 = 2 | 数量 2 のフルフィルメントを要求 | 2 件の予約はいずれもフルフィルメントされ、手持在庫は 0 に減少します |
予約ドキュメント
API コンシューマーは、予約に関連する重要な情報 (予約 ID、SKU、数量、ロケーショングループまたはロケーション) を含む参照情報として、予約ドキュメントを作成します。
API コンシューマーは、予約の一部として予約ドキュメントを OCI に送信し、注文の一部として OMS (SOM またはサードパーティ) に送信します。
予約ドキュメントは、OMS がルーティングのために、どのグループ/ロケーションに対して予約が行われたかを把握するために使用されます。
予約ドキュメントは、Cancel エンドポイントを使用して予約をキャンセルする必要がある場合に、OCI/ECOM によって使用されます。(unreserve エンドポイントも使用できます。この場合、予約 ID は不要ですが、SKU やグループまたはロケーションなど、予約に関するその他の重要な詳細が必要です)。
グループ予約
在庫はロケーションでのみ利用可能であるため、グループの入手可能性は、そのグループ内のすべてのロケーションを集計した結果を反映します。また、特定のロケーションにまだ割り当てられていない、グループに対して行われた予約も含まれます。
グループ予約の一般的なライフサイクル
reservation-documentsを使用してグループ予約を作成します。transfersを使用して、その予約をグループ内のロケーションに割り当てます。fulfillmentsを使用して、その予約をロケーションでフルフィルメントします。
フロー例:
Group A に Location 1 と Location 2 があるとします。
グループの状態が次のとおりである場合:
| 場所 | 手持在庫 | 予約済み数量 | ATO |
|---|---|---|---|
| Location 1 | 50 | 0 | 50 |
| Location 2 | 50 | 0 | 50 |
| Group A | 100 | 0 | 100 |
→ グループ予約 1 件を作成
| 場所 | 手持在庫 | 予約済み数量 | ATO |
|---|---|---|---|
| Location 1 | 50 | 0 | 50 |
| Location 2 | 50 | 0 | 50 |
| Group A | 100 | 1 | 99 |
→ 予約を Location 2 に割り当て
| 場所 | 手持在庫 | 予約済み数量 | ATO |
|---|---|---|---|
| Location 1 | 50 | 0 | 50 |
| Location 2 | 50 | 1 | 49 |
| Group A | 100 | 1 | 99 |
→ Location 2 でフルフィルメント
| 場所 | 手持在庫 | 予約済み数量 | ATO |
|---|---|---|---|
| Location 1 | 50 | 0 | 50 |
| Location 2 | 49 | 0 | 49 |
| Group A | 99 | 0 | 99 |
グループ予約は、ロケーションで報告される注文可能数量 (ATO) には影響しません。本質的に、グループ予約は、要求された予約数量をそのグループに属する 1 つ以上のロケーションが満たせることを、グループが約束するものです。Omnichannel Inventory が、そのような既存の約束に反すると判断した場合、ロケーションに対して行われた予約は失敗することがあります。
たとえば、報告上の ATO が 3 であるロケーションに対して予約数量 3 の予約を行っても、Insufficient Quantity レスポンスで失敗することがあります。このシナリオは、そのロケーションの在庫の一部または全部が、関連付けられたグループのいずれかで行われた約束 (グループ予約) によって利用不可になっている場合に発生します。
ただし、Omnichannel Inventory は、失敗になる前にグループ予約を成立させるためのあらゆる可能性を尽くします。
上記の Group A の例で示したように、グループ予約は、1 つ以上のロケーションに割り当てられた時点で初めて、ロケーションレベルに反映されます。
共有ロケーション
グループ間でロケーションを共有している場合、状況はやや複雑になります。たとえば、あるグループで行われたグループ予約が、別のグループと 1 つ以上のロケーションを共有している場合、その別のグループの予約数を増加させることがあります。
シナリオ例:
Group A に Location 1 と Location 2 があり、Group B にLocation 2 と Location 3 があるとします。
したがって、Location 2 は共有ロケーションです。
グループの状態が次のとおりである場合:
| 場所 | 手持在庫 | 予約済み数量 | ATO |
|---|---|---|---|
| Location 1 | 5 | 0 | 5 |
| Location 2 | 5 | 0 | 5 |
| Group A | 10 | 0 | 10 |
| Location 2 | 5 | 0 | 5 |
| Location 3 | 15 | 0 | 15 |
| Group B | 20 | 0 | 20 |
→ Group B で数量 17 の予約を作成
| 場所 | 手持在庫 | 予約済み数量 | ATO |
|---|---|---|---|
| Location 2 | 5 | 0 | 5 |
| Location 3 | 15 | 0 | 15 |
| Group B | 20 | 17 | 3 |
→ Group A の予約数が 2 増加
| 場所 | 手持在庫 | 予約済み数量 | ATO |
|---|---|---|---|
| Location 1 | 5 | 0 | 5 |
| Location 2 | 5 | 0 | 5 |
| Group A | 10 | 2 | 8 |
前述のとおり、グループ予約は、要求された予約数量をそのグループに属する 1 つ以上のロケーションが満たせることを、グループが約束するものです。その約束を判断する際、グループ予約では「共有度が最も低いロケーションを優先する」アプローチが採用されます。つまり、まず、他のグループとの共有度が最も低いロケーションの在庫が確保されます。そのため、Group B で数量 17 の予約が行われたとき、最初に 15 が Location 3 で確保され、残りの 2 が共有ロケーションである Location 2 で確保されました。その結果、それら 2 が他で確保済みであることを反映して、Group A の予約数は 2 増加しました。
一時予約
予約を作成する際、expirationSeconds 値は、予約が在庫を解放するまでの間、その在庫を保持し続ける時間 (秒数) を示します。この有効期限は概算時間です。これは、指定された有効期限時刻と、入手可能数に反映される実際の在庫解放との間に、通常は遅延があるためです (極端に高い負荷時には 60 秒超)。
そのため、expirationSeconds 値は、予期しない技術的問題によりクライアントが予約をキャンセルできない場合に、最終的に在庫が解放されることを保証するものとして使用することをお勧めします。言い換えると、過少販売を防ぎ、リアルタイムの入手可能数の精度を最適化するために、予約の有効期限に依存するのではなく、クライアント側で予約を適時にキャンセルするよう管理することを推奨します。
共通レスポンスコード
次のエラーコードは、すべての API エンドポイントに適用されます。各エンドポイントで想定されるエラーコードとレスポンスボディの完全な一覧については、API ドキュメントを参照してください。
- 401 - OATH ベアラートークンがそのテナントに対して有効ではないか、またはすでに無効になっています。詳細はレスポンスボディに含まれます。
- 403 - テナントはシステムでプロビジョニングされていません。
- 5XX - サーバーエラーが発生しました。詳細はレスポンスボディに含まれます。
- Unknown - Unknown エラータイプが返された場合は、不明な内部エラーが発生したことを示します。
外部参照識別子
現在、コンシューマーがリクエストとともに ExternalRefId を送信できる箇所がいくつかあります。これは、コンシューマーが、リクエストとともにユーザー生成データを他の外部システムデータへのリンクとして送信できるようにするためです。たとえば、注文 ID を持つ注文からデータを取得している場合、その注文 ID を予約リクエストとともに externalRefId として送信できます。これにより、予約に問題が発生した場合に、そのエラーまたは問題を生成した外部システム内の注文に関連付けることができます。これは、Salesforce Core やその他のサービスで使用されている externalRefId と混同しないでください。この用途は OCI 専用であり、他では使用されません。
Correlation-ID
OCI での処理の追跡を容易にするため、顧客は Correlation-ID という名前のヘッダーに値を設定する必要があります。この値は CDN を経由して、リクエストとともに OCI に送信されます。これにより、リクエストがサービス内を移動する際の追跡に役立ちます。受け入れられるには、correlation-id は有効な UUIDv2 である必要があります。そうでない場合は無視されます。
Web リクエストが CDN を経由する場合は、CDN の x-correlation-id ヘッダー値 (これはその ray-id に由来します) も関係します。この場合、指定された correlation-id は CDN の x-correlation-id の前に付加され、両方の値がコンマ区切りで渡されます。
一部のサービスでは、X-Correlation-ID ヘッダーを使用します。OCI では、このヘッダーを使用すると CDN によって新しい値で上書きされるため、ヘッダー本来の目的を果たせなくなります。一貫した結果を得るには、代わりに Correlation-ID を使用してください。
Let us know so we can improve!