Spendint API - POST /sn_spend_intg/spendint/catalog

  • リリースバージョン: Zurich
  • 更新日 2025年07月31日
  • 所要時間：14分

    • サプライヤーが複数のカタログを転記して、サプライヤー製品、モデル製品、契約、および価格設定レコードを作成できるようにします。

    カタログ API 統合では、サードパーティのカタログからデータを受け取ったときに、次を実行できます。
    1. 新しいサードパーティカテゴリを作成し、これらのカテゴリをモデルカテゴリにマップします。
      • 可能な場合は、国連標準製品とサービスコード (UNSPSC) を使用してから、カテゴリ名を使用します。
      • UNSPSC が利用できない場合は、カテゴリ名のみを使用します。
    2. サードパーティカテゴリをモデルカテゴリにマッピングした後、メーカー品番 (MPN) を使用して既存の製品モデルを検索します (利用可能な場合)。
      1. MPN の製品モデルが見つかった場合は、変更を加えて製品モデルを更新してから、製品モデルに関連するサプライヤー製品を作成または更新します。
      2. MPN の製品モデルが存在しない場合は、次の手順を実行します。
        1. 製品モデルクラスは、通常、製品のサードパーティカテゴリによって参照されているモデルカテゴリで利用できます。この製品モデルクラスを使用して、製品モデルを作成する必要がある製品モデルテーブル (ハードウェア、ソフトウェア、消耗品など) を取得します。利用可能な製品モデルクラスがない場合は、基本製品モデルテーブルに製品モデルを作成します。
        2. 正しい製品モデルクラスが特定されたら、次のように正しいクラスに新しい製品モデルを作成します。
          • メーカー、公開者、またはプロバイダーは、製品モデルでメーカーにマップする必要があります。
          • API からの製品名は、製品モデルの名前にマップする必要があります。
          • API からの MPN は、モデル番号を更新する必要があります。
          • API からの製品説明は、製品モデルの説明を更新する必要があります。
          • モデルカテゴリは、サードパーティカテゴリレコードで参照されている製品カテゴリで更新する必要があります。
          • 製品カテゴリは、サードパーティカテゴリレコードで参照されている製品カテゴリで更新する必要があります。
          • API での代替製品に値がある場合は、現在の製品モデルと他の製品モデルの間に代替製品レコードを作成します。
          • API での互換製品に値がある場合は、現在の製品モデルと他の製品モデルの間に互換製品レコードを作成します。
          • API からの製品属性は、製品モデルの製品属性関連リストで作成または更新する必要があります。
    3. 製品モデルが利用可能な場合は、サプライヤーの部品番号を使用して、製品モデルに関連するサプライヤー製品を作成または更新します。

    サードパーティモデルマッピング

    次のテーブルを使用して、サードパーティのカテゴリ、モデル、およびユニットのマッピングを実行します。
    • サードパーティカテゴリ：内部の既存のモデルカテゴリにマップする、ShoppingHub 管理者のすべてのサードパーティカテゴリレコードを保存します。
    • サードパーティモデルマッピング：製品モデルとサードパーティモデルカテゴリ間のすべてのマッピング情報を保存します。
    • サードパーティユニット：ShoppingHub 管理者がサプライヤー製品ユニットとマップするための、すべてのサードパーティユニットレコードを保存します。
    • サードパーティユニットマッピング：製品モデルとサードパーティユニット間のすべてのマッピング情報を保存します。
    注:
    サードパーティカテゴリとサードパーティユニットの両方が適切にマッピングされると、サードパーティ統合製品が自動公開されます。

    サプライヤー製品の販売日

    販売終了日を迎えたサプライヤー製品は廃止され、カタログで公開されなくなります。サプライヤー製品フォームの [販売開始日] フィールドと [販売終了日] フィールドは、カタログ API からのサードパーティ統合によって入力されます。

    ステータステーブル

    製品の一括インポート要求のステータスを確認するには、テーブル REST API を使用して ServiceNow データベースへの REST 呼び出しを行います。API からの応答には、一括インポート要求に失敗したレコードがリストされます。一括製品インポート応答の場合は、次のパラメーターを使用してカタログエラーテーブルをクエリします。

    sysparm_query=outbound_error.supplier_id=<supplier_id>^outbound_error.state=20

    顧客 ID、サプライヤー ID、エラータイプ、一意のインポートセット ID、およびステータスの詳細は、親エラーテーブルである [送信ステータス] テーブルで確認できます。

    URL 形式

    /api/sn_spend_intg/spendint/catalog

    サポートされている要求パラメーター

    表 : 1. パスパラメーター
    名前 説明
    なし
    表 : 2. クエリパラメータ
    名前 説明
    mode サードパーティ統合のための非同期モードと同期モードのサポート。

    データタイプ：文字列

    有効な値：
    • 非同期：非同期モード。
    • 同期：同期モード。

    デフォルト：非同期
    表 : 3. 要求本文パラメーター (XML または JSON)
    名前 説明
    customer_id 顧客に対する識別子。

    データタイプ：文字列

    最大長：100
    catalog_id 顧客が購入できるカタログコンテンツの識別子。

    データタイプ：文字列

    最大長：100
    製品 作成または更新する製品を定義するオブジェクトのリスト。各トランザクションには 1000 製品の制限があります。

    データタイプ：アレイ

    "products": [
  {
    "available_units": "String",
    "available_for_country": [Array],
    "bundled_components": [Array],
    "contract_agreement": {Object},
    "delivery_time": "String",
    "images": [Array],
    "manufacturer": "String",
    "mpn": "String",
    "parent_bundle": "String",
    "product_attributes": {Object},
    "product_category_name": "String",
    "product_description": "String",
    "product_name": "String",
    "sku": "String",
    "unit": "String",
    "unspsc": "String",
  }
]
    products.available_units 在庫のある製品に必要です。この値は、この製品で利用可能なユニットの数量を示します。

    データタイプ：文字列

    最大長：40
    products.available_for_country サプライヤー製品を購入できる国コードのリスト。国が指定されていない場合は、どの国のユーザーでも製品を購入できます。

    データタイプ：アレイ

    "available_for_country": ["US","IN","GB"]
    products.bundled_components カタログペイロードの一部として製品バンドルを送信するシナリオでのみ有効で、親バンドルペイロードにのみ適用されます。この値には、子バンドルコンポーネントへの参照が含まれます。子バンドルコンポーネントの MPN と数量のリストは、ここで維持されます。
    注:
    同じ子バンドルコンポーネントがバンドル内に複数回追加される可能性があるため、入力された数量は同じ子バンドルコンポーネント間の差別化要素となります。
    子バンドルコンポーネントとその詳細 (MPN と数量) は、同じサプライヤーにマッピングする必要があります。

    データタイプ：アレイ

    "bundled_components": [
  {
    "mpn": "String",
    "quantity": "String"
  }
]
    products.contract_agreement 製品の契約の詳細。
    注:
    これは、子バンドルコンポーネントには必要ありません。

    データタイプ：オブジェクト

    "contract_agreement": {
  "contract_end_date": "String",
  "contract_number": "String",
  "contract_start_date": "String",
  "negotiated_currency ": "String",
  "negotiated_price": "String"
}
    products.contract_agreement.contract_end_date 契約期間の終了日付。

    データタイプ：文字列

    最大長：40

    形式：YYYY-MM-DD
    products.contract_agreement.contract_number 必須です。製品に関連付けられているアクティブな契約の番号。

    データタイプ：文字列

    最大長：100
    products.contract_agreement.contract_start_date 契約期間の開始日付。

    データタイプ：文字列

    最大長：40

    形式：YYYY-MM-DD
    products.contract_agreement.negotiated_currency 必須です。交渉価格の通貨。

    データタイプ：文字列

    最大長：40
    products.contract_agreement.negotiated_price 必須です。サプライヤーまたはリセラーとの契約を通じて交渉された製品の単価。

    データタイプ：文字列

    最大長：40
    products.delivery_time 製品が顧客に出荷されるまでにかかる推定日数。この値は日数を表し、整数である必要があります。

    データタイプ：文字列

    最大長：40
    products.images サプライヤー製品のイメージ URL を指定する文字列のリスト。

    データタイプ：アレイ
    products.manufacturer 必須です。製品を製造、公開、または提供する会社。これは製品のサプライヤーまたはリセラーではありません。

    データタイプ：文字列

    最大長：100
    products.mpn 必須です。メーカー、発行者、またはプロバイダーによって提供される製品の識別子。
    注:
    SKU 値が利用可能な場合、これはリセラーの親バンドルには必要ありません。

    データタイプ：文字列

    最大長：100
    products.parent_bundle カタログペイロードの一部として製品バンドルを送信するシナリオでのみ有効で、子バンドルコンポーネントペイロードにのみ適用されます。子バンドルコンポーネントの場合、親への参照はここで維持されます。親の MPN と SKU の値もここで設定します。

    データタイプ：文字列

    最大長：100
    products.product_attributes 製品属性を定義するキーと値のペアのリスト。たとえば、"Color": "Space Grey"。製品には複数の属性を使用できます。ただし、API を介して提供する必要があるのは、価格設定または在庫の有無に影響する属性のみです。

    データタイプ：オブジェクト
    products.product_category_name 必須です。unspsc プロパティを設定しない場合に入力する名前。この名前は、製品が属するカテゴリです。このカテゴリ名は、製品を購入するための商取引シナリオで使用できます。たとえば、電源タップ製品はオフィス機器カテゴリに属すことができます。

    データタイプ：文字列

    最大長：100
    products.product_description 商取引エクスペリエンス内で購入者に表示される製品の完全な説明。
    注:
    特に子バンドルコンポーネントがある製品バンドルカタログアイテムについては、サプライヤーができるだけ詳細に説明することをお勧めします。

    データタイプ：文字列

    最大長：65000
    products.product_name 必須です。製品の名前。

    データタイプ：文字列

    最大長：1000
    products.sku 必須です。サプライヤーによって販売された製品を一意に識別するサプライヤーによって生成される番号。

    データタイプ：文字列

    最大長：100
    products.unit 必須です。サプライヤーでの製品販売単位またはレート。たとえば、個数や時間などです。

    データタイプ：文字列

    最大長：40
    products.unspsc 必須です。product_category_name プロパティを設定しない場合に入力する識別子。この識別子は、製品が属するカテゴリの UNSPSC です。たとえば、UNSPSC コード 43210000 は、製品カテゴリ「コンピューター」の識別子です。

    データタイプ：文字列

    最大長：100
    supplier_id 必須です。顧客が注文できるリセラーまたはサプライヤーの識別子。

    データタイプ：文字列

    最大長：100
    third_party_import_id この識別子により、サードパーティは、インポートされたデータのセットを一意に識別する文字列値を渡すことができます。

    データタイプ：文字列

    最大長：100

    ヘッダー

    次のリクエストや応答ヘッダーは、この HTTP アクションにのみ適用されるか、またはこのアクションに別個の方法で適用されます。

    表 : 4. 要求ヘッダー
    ヘッダー 説明
    承認 応答本文のデータフォーマット。サポートされるタイプ：application/json または application/xml。

    デフォルト： application/json
    注:
    Procurement Integration Framework では application/json データ形式のみがサポートされています。
    表 : 5. 応答ヘッダー
    ヘッダー 説明
    なし

    ステータスコード

    この HTTP アクションには、次のステータスコードが適用されます。

    表 : 6. ステータスコード
    ステータスコード 説明
    success 成功。要求が正常に処理されました。
    failure 不成功。要求が処理されました (エラーあり)。

    応答本文のパラメーター (JSON)

    これらの応答本文パラメーターは、同期モードで照会されたときに受信されます。
    名前 説明
    error_response_body SKU、MPN、およびエラーメッセージでリストされたエラーの説明。

    データタイプ：アレイ
    error_response_body.error_message 詳細なエラーメッセージ。

    データタイプ：文字列
    status_code 「success」や「failure」などの応答ステータス。

    データタイプ：文字列

    cURL 要求

    curl "https://instance.service-now.com/api/sn_spend_intg/spendint/catalog" \
--request POST \
--header "Accept:application/json" \
--user 'username':'password'
{"root": [{
  "customer_id": "AB-1234323",
  "catalog_id": "ACME CORP-12347898",
  "supplier_id": "SUP-123456",
  "third_party_import_id": "DELL1234567",
  "products": [
    {
      "product_name": "Apple MacBook Pro 13 Core i7",
      "mpn": "Z0WQ-20004301931",
      "sku": "55788741",
      "manufacturer": "Apple",
      "product_category_name": "Computer",
      "parent_bundle": "920-0045362002",
      "bundled_components": {
        "mpn": "Z0WQ-20004301931",
        "quantity": "4",
       },
      "unspsc": "43211500",
      "product_description": "Apple MacBook Pro 13 Core i7 2.8GHz 16GB 512GB - Touch Bar - Space Gray",
      "product_attributes": {
        "Color": "Space Grey",
        "RAM": "16GB",
        "Screen Size": "13inch"
      },
      "images": ["http://test123.image1.png", "http://test123.image2.jpeg"],
      "unit": "Each",
      "available_units": "4",
      "available_for_country": ["US","IN","GB"],
      "delivery_time": "4",
      "contract_agreement": {
        "contract_number": "34567892",
        "contract_start_date": "YYYY-MM-DD",
        "contract_end_date": "YYYY-MM-DD",
        "negotiated_price": "456",
        "negotiated_currency ": "USD"
      }
    }
  ]
}
]}

    考えられる応答：

    // Success response:
{
    "result": {
        "response": "success"
    }
}

// Error response:
{
    "result": {
        "response": [
            {
                "customer_id": "AB-1234323",
                "supplier_id": "SUP-123456",
                "third_party_import_id": "DELL1234567",
                "status_code": "failure",
                "error_response_body": [
                    {
                        "sku": "55788741",
                        "mpn": "Z0WQ-20004301931",
                        "error_message": "Field Value empty/Formatting issue Negotiated currency \n"
                    }
                ]
            }
        ]
    }
}