j1.1.28
APIの概要
Inventory Impex API を使用すると、Omnichannel Inventory (OCI) の在庫の入手可能性のインポートとエクスポートを管理できます。
この API は、次の機能カテゴリに分類できます。
| カテゴリ | エンドポイントの説明 |
|---|---|
| 在庫のインポートとエクスポート | 在庫の入手可能性データをインポートおよびエクスポートするための API エンドポイント。 |
注: Omnichannel Inventory では、組織 ID の代わりにテナントグループ ID を使用します。詳細については、Commerce API 構成値を参照してください。
レート制限
ロードシェディングとレート制限の詳細については、ロードシェディングとレート制限を参照してください。
ベストプラクティス
ベストプラクティスについては、Inventory Impex ベストプラクティスを参照してください。
認証と認可
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 は、SKU ごとに品目を保持し、次の品目の入手可能性プロパティの集計を管理します。
| 入手可能性プロパティ | 説明 |
|---|---|
Available to Fulfill |
現時点でフルフィルメント可能な在庫 (Quantity on Hand - Quantity Reserved)。 |
Available to Order |
注文可能な在庫 ((Quantity on Hand + Future Inventory) - Quantity Reserved)。 |
Quantity on Hand |
利用可能な在庫数量。Future Inventory と Quantity Reserved は含みません。 |
Quantity Reserved |
フルフィルメント用に予約されている在庫数量。 |
Safety Stock Count |
意図的に確保され、Available to Order または Available to Fulfill の在庫数に含まれない在庫数量。 |
Future Inventory |
予約販売または取り寄せ注文にのみ使用できる在庫。現在は利用できず、入荷予定日を含みます。 |
Attribute Set |
品目に適用できる在庫属性 (例:groupEligibilityExclusion)。 |
availability-records imports POST エンドポイントを使用して、在庫の入手可能性データを Omnichannel Inventory に読み込む処理を開始します。インポートするデータの詳細は、POST リクエストのボディに含まれます。
開始呼び出しのレスポンスボディには、実際のインポート用データストリーム/ファイルを送信するためのリンクが含まれます。システムにアップロードするファイルが 100 MB を超える場合、ファイルを gzip で圧縮する _必要があります_。
ファイルが OCI システムに正常にアップロードされたら、availability-records imports status エンドポイントを呼び出して、インポートのステータスを確認できます。このエンドポイントを、ファイルアップロードで使用した importId と組み合わせて使用すると、インポート処理がまだ完了していないかどうかを確認できます。
ファイルがOCIによって正常に処理されると、レスポンスボディには COMPLETED ステータスが含まれます。インポートに関するその他のメトリクスも含まれており、それらは status 呼び出しのドキュメントに記載されています。
また、COMPLETED ステータスには、fullResults href も含まれます。この URI を使用すると、完了したインポート処理の詳細な結果を取得できます。
品目の入手可能性レコードのインポートを実行する場合は、次のエンドポイントをこの順序で使用します。
- imports POST URI を呼び出してインポートを開始します。
https://{shortCode}.api.commercecloud.salesforce.com/inventory/impex/v1/organizations/{organizationId}/availability-records/imports - 手順 1 のレスポンスボディに含まれる uploadLink を使用して、提供されたエンドポイントに POST 呼び出しを行い、データストリーム/ファイルを OCI にアップロードします。
https://{shortCode}.api.commercecloud.salesforce.com/inventory/impex/v1/organizations/{organizationId}/availability-records/imports/uploadlink/{uploadLinkId} - ファイルが OCI にアップロードされたら、開始呼び出し (手順 1 ) のレスポンスボディで提供された importStatusLink に対して GET 呼び出しを行い、インポートデータの処理ステータスを確認できます。
https://{shortCode}.api.commercecloud.salesforce.com/inventory/impex/v1/organizations/{organizationId}/availability-records/imports/{importId}/status - 手順 3 から返されたレスポンスボディのステータスフィールドが COMPLETED になったら、OCI への入手可能性レコードデータのインポートは完了です。ステータスレスポンスには、完了したインポート処理の詳細を取得するための URI を含む fullResults href フィールドが含まれます。この情報は、提供された URI に対する GET 呼び出しで取得します。
https://{shortCode}.api.commercecloud.salesforce.com/inventory/impex/v1/organizations/{organizationId}/availability-records/imports/{importId}/file-content
示されたエンドポイントを使用してこの順序で手順を実行することで、入手可能性レコードを OCI に正常にインポートできます。
ロケーション在庫インポートファイルレイアウト - 高性能版
すべての新規実装で、このインポートファイルレイアウトを使用することを強く推奨します。レガシーレイアウトを使用している既存の実装についても、パフォーマンス向上のメリットを得られるよう、この新しいレイアウトに移行することを推奨します。このレイアウトでは、元の仕様の Location Header と Location Inventory オブジェクト を 1 つのエンティティに統合しています。システムでは、元のレイアウトのコンテンツと新しいレイアウトのコンテンツを混在して使用することはできません。インポートファイルは、高性能レイアウトまたはレガシーレイアウトのいずれか一方のみを使用して、全体を構成する必要があります。
重要: パフォーマンスの向上を実現するには、次の例のように、SKU ごとにグループ化してファイルを構成する必要があります。
注: 現在サポートされているのは UPDATE のみであるため、mode は UPDATE と見なされます。
{"recordId":"0a87539d-f3dd-47bc-91c7-9c752e39dbe0","onHand":10,"sku":"sku1","effectiveDate":"2020-04-08T14:05:22.790896-07:00","futures":[{"quantity":1,"expectedDate":"2020-04-18T14:05:22.781-07:00"}],"safetyStockCount":0,"attributeSet":{"groupEligibilityExclusion":["GroupA","GroupB"]},"locationId":"wickenburg"}
{"recordId":"3127e2ad-748b-459a-917c-78bef741602c","onHand":10,"sku":"sku1","effectiveDate":"2020-04-08T14:05:22.790896-07:00","futures":[{"quantity":1,"expectedDate":"2020-04-18T14:05:22.781-07:00"}],"safetyStockCount":0,"attributeSet":{"groupEligibilityExclusion":["GroupA","GroupB"]},"locationId":"prescott"}
{"recordId":"b709e7a8-7d4f-4458-be0c-a88f1e594f1d","onHand":10,"sku":"sku2","effectiveDate":"2020-04-08T14:05:22.790896-07:00","futures":[{"quantity":1,"expectedDate":"2020-04-18T14:05:22.781-07:00"}],"safetyStockCount":0,"attributeSet":{"groupEligibilityExclusion":["GroupA","GroupB"]},"locationId":"wickenburg"}
{"recordId":"b34c99ea-e659-40f7-bcb4-2a3fdc4a80b0","onHand":10,"sku":"sku2","effectiveDate":"2020-04-08T14:05:22.790896-07:00","futures":[{"quantity":1,"expectedDate":"2020-04-18T14:05:22.781-07:00"}],"safetyStockCount":0,"attributeSet":{"groupEligibilityExclusion":["GroupA","GroupB"]},"locationId":"prescott"}
{"recordId":"4bf7b40b-c965-485c-afa0-cc56a8ea70eb","onHand":10,"sku":"sku3","effectiveDate":"2020-04-08T14:05:22.790896-07:00","futures":[{"quantity":1,"expectedDate":"2020-04-18T14:05:22.781-07:00"}],"safetyStockCount":0,"locationId":"wickenburg"}
{"recordId":"539d41b7-5f05-4908-831b-3dd0461794fc","onHand":10,"sku":"sku3","effectiveDate":"2020-04-08T14:05:22.790896-07:00","futures":[{"quantity":1,"expectedDate":"2020-04-18T14:05:22.781-07:00"}],"safetyStockCount":0,"locationId":"prescott"}
高性能レイアウトを使用していることを示すための、それ以外の要件はありません。システムはファイルを読み取り、処理方法を自動的に判断します。
フィールドの内容については、以下のインポートフィールド定義を参照してください。
ロケーション在庫インポートファイルレイアウト - CSV
CSV ファイルのインポートもサポートされています。CSV ファイルを送信するには、インポート開始呼び出しで fileType フィールドを CSV に設定する必要があります。これにより、次の形式でファイルを送信できます。
CSV 形式のインポートファイルで注目すべき点は、ヘッダー行と、将来在庫を含める方法です。CSV ファイルは JSON ファイルのようなネスト構造の処理には適していないため、将来在庫は次に示す方法で表現する必要があります。この形式を使用すると、インポート処理中に各品目に対して 2 件の将来在庫を適用できます。
Location ID,SKU,Quantity On Hand,Safety Stock,Effective Date,Future Date 1,Future Quantity 1,Future Date 2,Future Quantity 2,Group Eligibility Exclusion warehouse,red_shirt,10,1,2020-04-08T14:05:22.790896-07:00,2020-04-18T14:05:22.781-07:00,10,2020-05-18T14:05:22.781-07:00,100,"[G1, G2]" warehouse-2,white_shirt,200,10,2020-04-08T14:05:22.790896-07:00,,,,,
ロケーション在庫インポートファイルレイアウト - レガシー
注: システムでは現在もこのインポートファイルレイアウトをサポートしていますが、パフォーマンスが低いため、このレイアウトから移行することを推奨します。詳細については、インポートファイルレイアウト - 高性能版セクションを参照してください。
インポートデータストリームでは、ロケーションごとの在庫の入手可能性データと、Omnichannel Inventory が実行するインポート操作の種類 (たとえば、UPDATE、DELETE、REPLACE) を指定します。ストリームは、改行で区切られた 2 種類の JSON エンティティ (Location Header と Location Inventory) で構成されます。
フィールドの内容については、インポートフィールド定義セクションを参照してください。
重要: Location Header エンティティと Location Inventory エンティティは 1 対多の関係にあります。各 Location Header の後には、同じロケーションに対応する 1 つ以上の Location Inventory エンティティを続ける必要があります。各 Location Inventory エンティティの上に Location Header エンティティを配置することも可能ですが、インポート処理が _大幅に遅くなります_。
{"location":"wickenburg","mode":"UPDATE"}
{"recordId":"0a87539d-f3dd-47bc-91c7-9c752e39dbe0","onHand":10,"sku":"sku1","effectiveDate":"2020-04-08T14:05:22.790896-07:00","futures":[{"quantity":1,"expectedDate":"2020-04-18T14:05:22.781-07:00"}],"safetyStockCount":0}
{"recordId":"f4bf981e-321e-42bd-851f-3573a3263ab1","onHand":5,"sku":"sku2","effectiveDate":"2020-04-08T14:05:22.790896-07:00","safetyStockCount":1}
インポートフィールド定義
ロケーションヘッダー:
| フィールド | 説明 | 必須フィールド |
|---|---|---|
location |
在庫が保管されている物理ロケーション。 | TRUE |
mode |
実行するシステム操作の種類。現在サポートされているのは UPDATEのみです。 |
TRUE |
ロケーション在庫:
| フィールド | 説明 | 必須フィールド |
|---|---|---|
recordId |
在庫レコードの一意の識別子。 | TRUE |
sku |
品目の一意の識別子。: \ < > ; % / 、スペース、タブ、改行は使用できません。 | TRUE |
onHand |
現在の手持在庫数量。 | FALSE |
effectiveDate |
onHand の有効日 (ISO 形式)。 |
FALSE。詳細は、以下の追加説明を参照してください。 |
futures |
品目の将来数量情報のコレクション。(以下の「将来数量」を参照してください。)注: Inventory Availability API では、futures は futureStock という名前のコレクションで参照されます。これらは同じものです。 |
FALSE。指定する場合は、以下の必須フィールドを参照してください。 |
attributeSet |
品目に適用できる属性。(利用可能な属性については、以下の「属性セット」を参照してください。) | FALSE。指定する場合は、以下の必須フィールドを参照してください。 |
safetyStockCount |
安全在庫数。 | FALSE |
将来数量:
| フィールド | 説明 | 必須フィールド |
|---|---|---|
quantity |
今後入荷予定の数量。値は 0 より大きい必要があります。 | TRUE |
expectedDate |
将来数量の到着予定日 (ISO 形式)。 | TRUE |
属性セット:
| フィールド | 説明 | 必須フィールド |
|---|---|---|
groupEligibilityExclusion |
location/sku の集計から除外されるグループ。 | FALSE |
送信呼び出しのレスポンスには、インポートのステータスと進行状況を確認するためのカスタムエンドポイントが含まれます。ステータスレスポンスには、読み込みに失敗したレコードが存在する場合、それらの完全な結果ファイルの URI が含まれます。Omnichannel Inventory には、インポートジョブのクエリと削除のためのエンドポイントも用意されています。
入手可能性の有効日:
effectiveDate フィールドは、物理ロケーションで onHand 値が正確であった時点を表します。このフィールドは、予約フルフィルメントフィールド fulfillmentTime と組み合わせて使用され、onHand を物理ロケーションと同期した状態に保ちます。たとえば、ロケーションレコードで effectiveDate が指定されている場合、予約フルフィルメントが実行されると、システムは任意で onHand の値を減算します。予約フルフィルメントの動作の詳細については、Inventory Reservation API を参照してください。
例:
SKU abc、ロケーション 123 に対してインポートが実行され、onHand の値には、OCI でまだ処理されていない予約フルフィルメントが反映されています。
注: ここでは JSON を整形して表示していますが、実際のインポートファイルでは、すべて 1 行で記述する _必要があります_。
{
"recordId":"a26fe1fd-c413-4b74-8570-1ec185ca7192",
"onHand":10,
"sku":"abc",
"effectiveDate":"2021-03-09T00:00:00.000000-07:00"
}
SKU abc、ロケーション 123 に対するインポートの後で予約フルフィルメントリクエストが発生します。
{
"records": [
{
"id": "82251928-8863-488e-840b-2aebd10b57ba",
"location": "123",
"sku": "abc",
"fulfillmentTime":"2021-03-08T00:00:00.000000-07:00"
"quantity": 1
}
]
}
システムは、effectiveDate と fulfillmentTime の値を比較します。fulfillmentTime は effectiveDate より 前 であるため、onHand の値は _減算されません_。予約フルフィルメントが先に発生していた場合は、onHand は減算されます (その前の effectiveDate の値が fulfillmentTime より前であることが前提です)。その後、システムが在庫のインポートを実行すると、onHand の値で以前の値が置き換えられます。
ロケーション在庫インポート結果ファイルレイアウト
結果ファイルは、ステータス行レコードで始まります。
{"status": "COMPLETED_WITHOUT_ERRORS"}
| 結果ステータス | 説明 |
|---|---|
COMPLETED_WITHOUT_ERRORS |
エラーなしでインポートが完了しました。 |
COMPLETED_WITH_PARTIAL_FAILURES |
一部のレコードの読み込みに失敗しました。 |
FAILED |
すべてのレコードの読み込みに失敗しました。 |
ステータス行に続く各行は、エラーレコードを表します。
{"recordId": "2a3e769c-c981-4d96-ba6a-e0b821a5bbbb","locationId":"location1","sku": "sku1", "message": "Unknown"}
| フィールド | 説明 | 必須フィールド |
|---|---|---|
recordId |
インポートファイルで送信された在庫レコードの一意の識別子。 | TRUE |
locationId |
ロケーション識別子。 | TRUE |
sku |
品目の一意の識別子。: \ < > ; % / 、スペース、タブ、改行は使用できません。 | TRUE |
message |
失敗の詳細を示すメッセージ。 | TRUE |
商品セグメンテーションのインポート
これらの API エンドポイントを使用して、商品セグメンテーションデータをインポートします。このデータにより、SKU をロケーショングループから除外できるため、特定の販売チャネルから特定の SKU を除外できます。
product-segmentation imports POST エンドポイントを使用して、商品セグメンテーションデータを Omnichannel Inventory に読み込む処理を開始します。インポートするデータの詳細は、POST リクエストのボディに含まれます。
開始呼び出しのレスポンスボディには、実際のインポート用データストリーム/ファイルを送信するためのリンクが含まれます。システムにアップロードするファイルが 100 MB を超える場合、ファイルを gzip で圧縮する _必要があります_。
ファイルが OCI システムに正常にアップロードされたら、product-segmentation imports status エンドポイントを呼び出して、インポートのステータスを確認できます。このエンドポイントを、ファイルアップロードで使用した importId と組み合わせて使用すると、インポート処理がまだ完了していないかどうかを確認できます。
ファイルがOCIによって正常に処理されると、レスポンスボディには COMPLETED ステータスが含まれます。インポートに関するその他のメトリクスも含まれており、それらは status 呼び出しのドキュメントに記載されています。
また、COMPLETED ステータスには、_fullResults href _ も含まれます。この URI を使用すると、完了したインポート処理の詳細な結果を取得できます。
商品セグメンテーションデータのインポートを実行する場合は、次のエンドポイントをこの順序で使用します。
- imports POST URI を呼び出してインポートを開始します。
https://{shortCode}.api.commercecloud.salesforce.com/inventory/impex/v1/organizations/{organizationId}/product-segmentation/imports - 手順 1 のレスポンスボディに含まれる uploadLink を使用して、提供されたエンドポイントに POST 呼び出しを行い、データストリーム/ファイルを OCI にアップロードします。
https://{shortCode}.api.commercecloud.salesforce.com/inventory/impex/v1/organizations/{organizationId}/product-segmentation/imports/uploadlink/{uploadLinkId} - ファイルが OCI に完全にアップロードされた後、呼び出し開始 (手順 1 ) に対してレスポンスボディで提供された importStatusLink への GET 呼び出しを使用して、データの処理ステータスを確認できます。
https://{shortCode}.api.commercecloud.salesforce.com/inventory/impex/v1/organizations/{organizationId}/product-segmentation/imports/{importId}/status - 手順 3 から返されるレスポンスボディのステータスフィールドが COMPLETED (完了) になると、OCI への商品セグメンテーションデータのインポートが完了します。ステータスレスポンスには、完了したインポート処理の詳細を取得するための URI を含む fullResults href フィールドが含まれます。この情報は、提供された URI に対する GET 呼び出しで取得します。
https://{shortCode}.api.commercecloud.salesforce.com/inventory/impex/v1/organizations/{organizationId}/product-segmentation/exports/{exportId}/file-content
示されたエンドポイントを使用してこの順序で手順を実行することで、商品セグメンテーションレコードを OCI に正常にインポートできます。
商品セグメンテーション除外インポートファイルレイアウト
インポートデータストリームでは、このデータの対象となるグループと、Omnichannel Inventory が除外に対して実行するインポート操作の種類 (たとえば、REPLACE、APPEND、REMOVE) を指定します。ストリームは、改行で区切られた 2 種類の JSON エンティティ (Group Header と SKU Data) で構成されます。
重要: ** Group Header エンティティと SKU Data エンティティは 1 対多の関係 にあります。つまり、各 Group Header の後には、同じグループに対応する 1 つ以上の SKU Data エンティティを続ける必要があります。各 SKU Data エンティティの上に Group Header エンティティを配置することも可能ですが、インポート処理が大幅に遅くなります**。
{"groupId":"G1","mode":"REPLACE"}
{"sku":"sku1"}
{"sku":"sku2"}
{"groupId":"G1","mode":"APPEND"}
{"sku":"sku37"}
除外インポートフィールド定義
Group Header:
| フィールド | 説明 | 必須フィールド |
|---|---|---|
groupId |
除外を設定する対象のグループ。 | TRUE |
mode |
グループに対して実行するシステム操作の種類。グループのすべてのエントリーを置き換える REPLACE、グループに新しいエントリーを追加する APPEND、またはグループ除外から一連の SKU を削除するREMOVE。 |
TRUE |
SKU Data:
| フィールド | 説明 | 必須フィールド |
|---|---|---|
sku |
除外対象となる、グループ内の品目の一意の識別子。: \ < > ; % / 、スペース、タブ、改行は使用できません。 | TRUE |
商品セグメンテーションのエクスポート
エクスポートファイルは、商品セグメンテーションデータを含む完全な JSON レコードの集合であり、1 行につき 1 つの完全なエントリで構成されます。
このエンドポイントを使用して、現在の商品セグメンテーション除外のスナップショットをリクエストします。"*" をグループとして使用することで、グループのリストまたはすべてのグループのスナップショットをリクエストできます。Omnichannel Inventory には、この処理のステータスと進行状況を確認するための別のエンドポイントも用意されています。
完了したエクスポートは、ステータス確認レスポンスで提供されるリンクを使用して取得します。 任意のエクスポートまたはインポートプロセスのステータスを取得する際は、次のレスポンスを利用できます。
| エクスポートステータス | 説明 |
|---|---|
STAGING |
リクエストを作成中です。 |
WAITING |
インポートの場合 - ファイルのアップロードを待機中です。 |
EXPIRED |
リクエストの有効期限が切れています。 |
SUBMITTED |
処理のためにリクエストが送信されました - まだキューには登録されていません。 |
PENDING |
リクエストは処理キューに登録されています - まだ開始されていません。 |
RUNNING |
リクエストは実行中です - まだ完了していません。 |
COMPLETED |
リクエストは完了しました - レスポンスに結果ファイルの場所が含まれます。 |
FAILED |
リクエストは失敗しました - 再試行するには新しいリクエストを再送信します。 |
STOPPED |
リクエストは停止されました - 再試行するには新しいリクエストを再送信します。 |
エクスポートダウンロードファイルのレイアウト
エクスポートファイルは、完全な JSON レコードの集合であり、1 行につき 1 つの完全な要素を含みます。
グループ行
{"groupId":"UnitedStates"}
| グループ識別行 | 説明 |
|---|---|
groupId |
後続の詳細レコードが属するグループ。 |
SKU 行
{"sku":"sku121"}
| グループ識別行 | 説明 |
|---|---|
sku |
その商品セグメンテーション除外グループのメンバーである SKU 識別子。 |
入手可能性のエクスポート
エクスポートファイルは、完全な JSON レコードの集合であり、1 行につき 1 つの完全な要素を含みます。
このエンドポイントを使用して、リクエストボディで指定した条件 (たとえば、単一のグループ、すべてのグループ、単一のロケーション、またはすべてのロケーション) に基づく、現在の在庫の入手可能性のスナップショットをリクエストします。Omnichannel Inventory には、この処理のステータスと進行状況を確認するための別のエンドポイントも用意されています。
完了したエクスポートは、ステータス確認レスポンスで提供されるリンクを使用して取得します。エクスポートされたデータには、そのエクスポート以降の変更を取得するための差分トークンが含まれます。
任意のエクスポートまたはインポートプロセスのステータスを取得する際は、次のレスポンスを利用できます。
| エクスポートステータス | 説明 |
|---|---|
STAGING |
リクエストを作成中です。 |
WAITING |
インポートの場合 - ファイルのアップロードを待機中です。 |
EXPIRED |
リクエストの有効期限が切れています。 |
SUBMITTED |
処理のためにリクエストが送信されました - まだキューには登録されていません。 |
PENDING |
リクエストは処理キューに登録されています - まだ開始されていません。 |
RUNNING |
リクエストは実行中です - まだ完了していません。 |
COMPLETED |
リクエストは完了しました - レスポンスに結果ファイルの場所が含まれます。 |
FAILED |
リクエストは失敗しました - 再試行するには新しいリクエストを再送信します。 |
STOPPED |
リクエストは停止されました - 再試行するには新しいリクエストを再送信します。 |
エクスポートダウンロードファイルのレイアウト
エクスポートファイルは、完全な JSON レコードの集合であり、1 行につき 1 つの完全な要素を含みます。
注: 入手可能性のエクスポートでは、エクスポート対象としてグループまたはロケーションのいずれか一方のみをサポートしており、両方を同時にエクスポートすることはできません。
グループ行
{"groupId":"UnitedStates"}
| グループ識別行 | 説明 |
|---|---|
groupId |
後続の詳細レコードが属するグループ。 |
ロケーション行
{"locationId":"phoenix"}
| グループ識別行 | 説明 |
|---|---|
locationId |
後続の詳細レコードが属するロケーション。 |
品目レコード行 - 1 行に 1 つの完全な JSON エントリ:
{"sku":"123","onHand":10,"reserved":6,"groupReserved":6,"sharedGroupReserved":0,"atf":4,"ato":24,"safetyStockCount":1,"effectiveDate":"2019-07-20T11:04:02Z","futures":[{"quantity":20,"expectedDate":"2019-07-24T21:13:00Z"}]}
| フィールド | 説明 | 必須フィールド |
|---|---|---|
sku |
品目の一意の識別子。: \ < > ; % / 、スペース、タブ、改行は使用できません。 | TRUE |
onHand |
現在の手持在庫数量。 | TRUE |
reserved |
現在の予約済み数量。 | TRUE |
atf |
現在のフルフィルメント可能数量。 | TRUE |
ato |
現在の受注可能数量。 | TRUE |
effectiveDate |
有効日 (ISO 形式)。 | FALSE |
groupReserved |
共有分を含まない、そのグループのグループ予約総数。このフィールドは、エクスポート内の GROUP 行にのみ含まれます。 | FALSE |
sharedGroupReserved |
他のグループに由来するソフト予約数。このフィールドは、エクスポート内の GROUP 行にのみ含まれます。 | FALSE |
safetyStockCount |
安全在庫数。 | TRUE |
futures |
品目の将来数量情報のコレクション (以下で説明)。Inventory Availability API は、futures を futureStock というコレクションで参照しています。この 2 つは同じです。 |
TRUE |
attributeSet |
品目に適用できる在庫属性 (例: groupEligibilityExclusion)。 |
FALSE |
将来数量:
| フィールド | 説明 | 必須フィールド |
|---|---|---|
quantity |
今後入荷予定の数量。 | TRUE |
expectedDate |
将来数量の到着予定日 (ISO 形式)。 | TRUE |
デルタトークン行:
{"deltaToken": "dsfljasdflkjasdfkj2381238"}
この値は、差分を取得する呼び出しで使用されます。このデルタトークンの有効期間は 23.5 時間で、その後は期限切れとなるため、別のエクスポートで新しいトークンを取得する必要があります。詳細については、Inventory Availability API を参照してください。
イベントログのエクスポート
エクスポートファイルは、完全な JSON レコードの集合であり、1 行につき 1 つの完全な要素を含みます。
このエンドポイントを使用して、指定したロケーションおよびグループのセットに含まれる SKU のイベントログをリクエストします。Omnichannel Inventory には、この処理のステータスと進行状況を確認するための別のエンドポイントも用意されています。
完了したエクスポートは、ステータス確認レスポンスで提供されるリンクを使用して取得します。
任意のエクスポートまたはインポートプロセスのステータスを取得する際は、次のレスポンスを利用できます。
| エクスポートステータス | 説明 |
|---|---|
STAGING |
リクエストを作成中です。 |
WAITING |
インポートの場合 - ファイルのアップロードを待機中です。 |
EXPIRED |
リクエストの有効期限が切れています。 |
SUBMITTED |
処理のためにリクエストが送信されました - まだキューには登録されていません。 |
PENDING |
リクエストは処理キューに登録されています - まだ開始されていません。 |
RUNNING |
リクエストは実行中です - まだ完了していません。 |
COMPLETED |
リクエストは完了しました - レスポンスに結果ファイルの場所が含まれます。 |
FAILED |
リクエストは失敗しました - 再試行するには新しいリクエストを再送信します。 |
STOPPED |
リクエストは停止されました - 再試行するには新しいリクエストを再送信します。 |
エクスポートダウンロードファイルのレイアウト
エクスポートファイルは、完全な JSON レコードの集合であり、1 行につき 1 つの完全な要素を含みます。
グループ行
{"groupId":"UnitedStates"}
| グループ識別行 | 説明 |
|---|---|
groupId |
後続の詳細レコードが属するグループ。 |
ロケーション行
{"locationId":"phoenix"}
| グループ識別行 | 説明 |
|---|---|
locationId |
後続の詳細レコードが属するロケーション。 |
品目レコード行 - 1 行に 1 つの完全な JSON エントリ:
{"locationId":"newbraunfels"}{"eventType":"location_import","location":"newbraunfels","sequenceNumber":0,"quantity":10.0,"newReserved":0.0,
"newAto":11.0,"newOnHand":10.0,"newAtf":10.0,"newSoftReserved":0.0,"futureQuantity":1.0,"oldReserved":0.0,
"oldAto":0.0,"oldOnHand":0.0,"oldAtf":0.0,"oldSoftReserved":0.0,"createdTime":"2022-01-18T15:58:40.443Z",
"effectiveTime":"2020-04-08T14:05:22.795243-07:00","safetyStockCount":0.0}
| フィールド | 説明 | 必須フィールド |
|---|---|---|
eventType |
イベントタイプ。 | TRUE |
location |
このイベントに関連付けられたロケーション。 | TRUE |
sequenceNumber |
このイベントに関連付けられた内部シーケンス番号。 | TRUE |
quantity |
品目数量。 | TRUE |
newReserved |
SKU およびロケーションに対する新しい予約数量。 | TRUE |
newAto |
品目の新しい ATO (注文可能数量)。 | TRUE |
newOnHand |
品目の新しい手持在庫数量。 | TRUE |
newAtf |
品目の新しい ATF (フルフィルメント可能数量)。 | TRUE |
newSoftReserved |
品目の新しいソフト予約数量。 | TRUE |
futureQuantity |
品目の将来数量。 | TRUE |
oldReserved |
イベント発生前の、品目の予約数量。 | TRUE |
oldAto |
イベント発生前の、品目の ATO。 | TRUE |
oldOnHand |
イベント発生前の、品目の手持在庫数量。 | TRUE |
oldAtf |
イベント発生前の、品目の ATF。 | TRUE |
oldSoftReserved |
イベント発生前の、ソフト予約数量。 | TRUE |
createdTime |
イベントの作成時刻。 | TRUE |
effectiveTime |
イベントの有効時刻。 | TRUE |
safetyStockCount |
品目の安全在庫数値。 | TRUE |
予約のエクスポート
このエンドポイントを使用して、特定の期間および予約ステータス値のセットに含まれる予約ドキュメントをリクエストします。現在サポートされている予約のステータス値は "open" と "closed" です。Omnichannel Inventory には、エクスポートを開始するためのエンドポイント、エクスポートのステータスと進行状況を確認するためのエンドポイント、および完了後に実際のエクスポートファイルをダウンロードするためのエンドポイントが用意されています。
完了したエクスポートは、ステータス確認レスポンスで提供されるリンクを使用して取得します。
任意のエクスポートまたはインポートプロセスのステータスを取得する際は、次のレスポンスを利用できます。
| エクスポートステータス | 説明 |
|---|---|
STAGING |
リクエストを作成中です。 |
WAITING |
インポートの場合 - ファイルのアップロードを待機中です。 |
EXPIRED |
リクエストの有効期限が切れています。 |
SUBMITTED |
処理のためにリクエストが送信されました - まだキューには登録されていません。 |
PENDING |
リクエストは処理キューに登録されています - まだ開始されていません。 |
RUNNING |
リクエストは実行中です - まだ完了していません。 |
COMPLETED |
リクエストは完了しました - レスポンスに結果ファイルの場所が含まれます。 |
FAILED |
リクエストは失敗しました - 再試行するには新しいリクエストを再送信します。 |
STOPPED |
リクエストは停止されました - 再試行するには新しいリクエストを再送信します。 |
エクスポートダウンロードファイルのレイアウト
エクスポートファイルは、完全な JSON レコードの集合であり、reservationId ごとに 1 つの予約レコードを含みます。
ヘッダー情報
{
"reservationId" : "5baf4a87-1841-4311-9ca9-601e5d32885b",
"externalRefId" : "OCI-1234567",
"reservationTime" : 1648718653000,
"reservationState" : "CLOSED",
"reservationDetails" : []
}
| ヘッダーフィールド情報 | 説明 |
|---|---|
reservationId |
エクスポートされた予約の reservationId。 |
externalRefId |
エクスポートされた予約の外部参照識別子。この値は、外部の注文システム内の値に対応します。 |
reservationTime |
予約作成時にその予約に適用された時刻。 |
reservationState |
予約の現在の状態。現在サポートされている値は "open" と "closed" です。 |
reservationDetails |
対象の予約の詳細を含む配列。 |
予約の詳細
reservationDetails フィールドには、エクスポートされた予約に関連する情報の配列が含まれます。
"reservationDetails" : {
"group": "ACME_US",
"sku" : "white-shirt-40",
"quantity" : 5,
"reservationDetailActions" []
}
| 予約詳細情報 | 説明 |
|---|---|
group or location |
この詳細項目が、グループとロケーションのどちらに関連付けられているか。 |
sku |
この詳細行に関連付けられた SKU 識別子。 |
quantity |
予約ラインアイテムに適用される数量。 |
reservationDetailActions |
この予約内でこのラインアイテムに対して実行されたアクションの配列。 |
予約詳細アクション
reservationDetailActions は、特定の予約ドキュメントに対して実行されたアクションを追跡するエントリの配列です。
"reservationDetailActions" : [
{
"requestId" : "3678-23456-3456-4567-9999-1232",
"externalRefId" : "1234561-4949-2345",
"quantity" : 5,
"action" : Reserverd,
timestamp : "16487200010000"
}
]
| 予約アクション詳細 | 説明 |
|---|---|
requestId |
この予約アクションに関連付けられたリクエスト ID。 |
externalRefId |
エクスポートされたアクションの外部参照識別子。この値は、外部の注文システム内の値に対応します。 |
quantity |
この予約アクションに関連付けられた数量。 |
action |
このラインアイテムに対して実行されたアクション。 |
timestamp |
アクションが実行された時刻。 |
共通レスポンスコード
次のエラーコードは、すべての 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 を使用してください。
NoOp 在庫レコード
次のいずれにも変更がないインポートレコードは、NoOp または NoOperation レコードと見なされます。
- onHand
- SafetyStockCount
- Futures (いずれかの値)
- AttributeSet (いずれかの値)
そのため、NoOp 在庫レコードはスキップされ、イベントログには反映されません。
Let us know so we can improve!