予約オープン API

  • リリースバージョン: Yokohama
  • 更新日 2025年01月30日
  • 所要時間：51分

    • Appointment Open API は、予約アプリケーションとやり取りできるようにする電気通信 API です。この API を使用して、予約を行い、利用可能なタイムスロットを検索します。

    予約オープン API は、Open API TMForum TMF646 予約 REST API 仕様のServiceNow®実装であり、TM フォーラムによって適合性認定を受けています。この実装は、 TMF646 予約 API REST 仕様 R16.0.1 に基づいています。

    TMF 準拠ロゴ
    この API には、 ServiceNow Store で利用可能な次のプラグインが必要です。
    • 予約 (com.snc.appointment_booking)
    • フィールドサービス管理 (com.snc.work_management)
    • Field Service Management for Telecommunications (com.sn_fsmt)
    • 通信オープン API (com.sn_tmf_api)

    この API を使用する前に、予約の設定とサービスの設定を行う必要があります。また、予約対象のタスクが存在する必要があります。

    この API は、 sn_tmf_api 名前空間内で提供されます。呼び出し元ユーザーには sn_tmf_api.appointment_integrator ロールが必要です。

    予約のオープン:DELETE /api/sn_tmf_api/appointment/appointment/{id}

    指定された ID の予約レコードを削除します。

    URL 形式

    デフォルト URL: /api/sn_tmf_api/appointment/appointment/{id}

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

    表 : 1. パスパラメーター
    名前 説明
    ID 削除する予約レコードのSys_id。

    データタイプ：文字列

    テーブル:予約 [sn_apptmnt_booking_appointment_booking]
    表 : 2. クエリパラメーター
    名前 説明
    なし
    表 : 3. 要求本文パラメーター (XML または JSON)
    名前 説明
    なし

    ヘッダー

    次の要求ヘッダーと応答ヘッダーは、この HTTP アクションにのみ適用されるか、別の方法でこのアクションに適用されます。REST API で使用される一般的なヘッダーのリストについては、「 サポートされている REST API ヘッダー」を参照してください。

    表 : 4. 要求ヘッダー
    ヘッダー 説明
    受容 応答本文のデータ形式。application/jsonのみをサポートしています。
    表 : 5. 応答ヘッダー
    ヘッダー 説明
    Content-Type 要求本文のデータ形式。application/jsonのみをサポートしています。

    ステータスコード

    この HTTP アクションには、次のステータスコードが適用されます。REST API で使用される可能性のあるステータスコードのリストについては、「 REST API HTTP 応答コード」を参照してください。

    表 : 6. ステータスコード
    ステータスコード 説明
    200 成功。要求が正常に処理されました。
    400 要求が正しくありません。不正な要求タイプまたは不正な形式の要求が検出されました。
    404 見つかりません。要求されたアイテムが見つかりませんでした。

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

    名前 説明
    メッセージ 削除が正常に行われたことを確認する応答メッセージ。

    成功:「予約 (<id>) が正常にキャンセルされました。」

    エラー：
    • 「予約のキャンセルに失敗しました。」:システムで ID が見つからず、ステータスコード 404 が返されます。
    • 「予約のキャンセルに失敗しました。」:予約は既にキャンセル済みまたは完了ステータスであるか、削除できません。ステータスコード 404 が返されます。
    • 「予約 (<id>) は [キャンセル期限] を超えているため、キャンセルできません。」:予約は、予約サービス構成で設定されている [キャンセル期限] を既に超過しています。ステータスコード 400 を返します。

    データタイプ：文字列

    cURL 要求

    次の例では、特定の ID の予約を削除します。

    curl "http://instance.servicenow.com/api/sn_tmf_api/appointment/appointment/68cc0a5a9314521060320dd548373" \ 
--request GET\ 
--user 'username':'password'

    応答本文:

    "The appointment (68cc0a5a9314521060320dd548373cbd) is successfully cancelled."

    予約のオープン:GET /api/sn_tmf_api/appointment/appointment

    予約レコードのリストを取得します。

    URL 形式

    デフォルト URL: /api/sn_tmf_api/appointment/appointment

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

    表 : 7. パスパラメーター
    名前 説明
    なし
    表 : 8. クエリパラメーター
    名前 説明
    category カテゴリsys_idで予約をフィルタリングします。

    データタイプ：文字列

    テーブル：場所 (cmn_location)

    デフォルト:カテゴリsys_idが指定されていない場合、すべての予約が返されます。
    relatedEntity 作業指示書に関連付けられた関連エンティティの詳細。

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

    "relatedEntity": {
  "id": "String"
}
    relatedEntity.id 必須。関連エンティティのSys_id。

    データタイプ：文字列

    テーブル:workOrder [wm_order]

    デフォルト:sys_idが指定されていない場合はすべてを返します。
    関連パーティー 予約に関連付けられた関係者のsys_idで予約をフィルタリングします。

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

    "relatedParty": {
  "id": "String",
  "name": "String"
}

    デフォルト: relatedParty が指定されていない場合、すべての予約が返されます。
    relatedParty.id 関係者のSys_id。

    データタイプ：文字列

    テーブル： ユーザー [sys_user]
    relatedParty.name 関係者の名前。

    データタイプ：文字列
    relatedPlace サービスまたは修理の実施がスケジュールされている場所で予約をフィルタリングします。

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

    "relatedPlace": {
  "id": "String"
}

    デフォルト: relatedPlace が指定されていない場合、すべての予約が返されます。
    relatedPlace.id 関連する場所のSys_id。

    データタイプ：文字列

    テーブル：場所 (cmn_location)
    validFor 予約が有効な日付範囲で予約をフィルタリングします。

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

    "validFor":
{
  "endDateTime": "String",
  "startDateTime": "String"
}

    デフォルト: validFor が指定されていない場合、すべての予約が返されます。
    validFor.endDateTime 予約の終了日時。指定された終了日時の予約のみが応答に返されます。

    データタイプ：文字列

    形式:YYYY-MM-DD 00:00:00。例:2025-01-31 09:35:43。

    テーブル：場所 (cmn_location)
    validFor.startDateTime 予約の開始日時。指定された開始日時の予約のみが応答に返されます。

    データタイプ：文字列

    形式:YYYY-MM-DD 00:00:00。例:2025-01-31 09:35:43。

    テーブル：場所 (cmn_location)
    表 : 9. 要求本文パラメーター (XML または JSON)
    名前 説明
    なし

    ヘッダー

    次の要求ヘッダーと応答ヘッダーは、この HTTP アクションにのみ適用されるか、別の方法でこのアクションに適用されます。REST API で使用される一般的なヘッダーのリストについては、「 サポートされている REST API ヘッダー」を参照してください。

    表 : 10. 要求ヘッダー
    ヘッダー 説明
    受容 応答本文のデータ形式。サポートされているタイプ: application/json または application/xml。

    デフォルト： application/json
    表 : 11. 応答ヘッダー
    ヘッダー 説明
    Content-Type 要求本文のデータ形式。application/jsonのみをサポートしています。

    ステータスコード

    この HTTP アクションには、次のステータスコードが適用されます。REST API で使用される可能性のあるステータスコードのリストについては、「 REST API HTTP 応答コード」を参照してください。

    表 : 12. ステータスコード
    ステータスコード 説明
    200 成功。要求が正常に処理されました。
    400 要求が正しくありません。不正な要求タイプまたは不正な形式の要求が検出されました。
    404 見つかりません。要求されたアイテムが見つかりませんでした。

    応答本文のパラメーター (JSON または XML)

    名前 説明
    category 予約サービス構成用に構成されたレコードプロデューサーのSys_id。

    データタイプ：文字列

    保存場所:予約サービス設定 [sn_apptmnt_booking_service_config] テーブルの [カタログアイテム] フィールド。
    creationDate 予約が作成された日時。

    データタイプ：文字列

    形式:YYYY-MM-DD 00:00:00。例:2025-01-31 09:35:43。
    href 予約レコードへのハイパーリンク。別の Appointment Open API 要求でこのリンクを使用して、予約を再スケジュールまたは削除します。

    データタイプ：文字列
    ID 予約のSys_id。

    データタイプ：文字列

    保存場所:予約サービス設定 [sn_apptmnt_booking_service_config] テーブル
    前回の更新 予約が最後に更新された日時。

    データタイプ：文字列

    形式:YYYY-MM-DD 00:00:00。例:2025-01-31 09:35:43。
    relatedEntity 予約の関連エンティティに関する詳細。

    データタイプ:オブジェクトのアレイ

    "relatedEntity": [
 {
  "@referredType": "String",
  "id": "String",
  "role": "String"
  }
]
    relatedEntity.@referredType アイテムまたはサービスのタイプ。

    データタイプ：文字列

    保存場所:workOrder [wm_order] テーブル
    relatedEntity.id 関連エンティティのSys_id。

    データタイプ：文字列

    保存場所:workOrder [wm_order] テーブル
    relatedEntity.role ロール:関連エンティティの説明。

    可能な値:作業指示

    データタイプ：文字列

    保存場所:workOrder [wm_order] テーブル
    関連パーティー 予約の連絡先のリスト。各連絡先はアレイ内のオブジェクトです。

    データタイプ:オブジェクトのアレイ

    "relatedParty": [
 {
  "@referredType": "String",
  "id": "String",
  "name": " String",
  "role": "String"
 }
]
    relatedParty.@referredType 顧客のタイプ。

    データタイプ：文字列

    保存場所:連絡先 [customer_contact] テーブル
    relatedParty.id 作業指示書に関連付けられた顧客連絡先のSys_id。

    データタイプ：文字列

    保存場所:連絡先 [customer_contact] テーブル
    relatedParty.name 顧客の連絡先の名前。

    データタイプ：文字列

    保存場所:連絡先 [customer_contact] テーブル
    relatedParty.role 顧客連絡先のロール。
    可能な値：
    • customer:連絡先には顧客ロールがあります。
    • 技術者:連絡先には技術者ロールがあります。

    データタイプ：文字列

    保存場所:連絡先 [customer_contact] テーブル
    relatedPlace 関連付けられた予約の場所の詳細。

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

    "relatedPlace": {
  "@referredType": "String",
  "id": "String",
  "name": "String",
  "role": "String"
}
    relatedPlace.@referredType 予約の地理的住所。

    可能な値:GeographicLocation。

    データタイプ：文字列

    保存場所:場所 [cmn_location] テーブル
    relatedPlace.id 場所のSys_id。

    データタイプ：文字列

    保存場所:場所 [cmn_location] テーブル
    relatedPlace.name 連絡先に関連する場所の名前。例:100 South Charles Street, Baltimore, MD。

    データタイプ：文字列

    保存場所:場所 [cmn_location] テーブル
    relatedPlace.role 介入住所としての予約場所のロール。

    可能な値:InterventionAddress

    データタイプ：文字列

    保存場所:場所 [cmn_location] テーブル
    validFor 予約が有効な日付範囲。

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

    "validFor": {
 "endDateTime": "String"
 "startDateTime": "String"
}
    validFor.endDateTime 予約の終了日時。

    データタイプ：文字列

    形式:YYYY-MM-DD 00:00:00。例:2025-01-31 09:35:43。
    validFor.startDateTime 予約の開始日時。

    データタイプ：文字列

    形式:YYYY-MM-DD 00:00:00。例:2025-01-31 09:35:43。

    cURL 要求

    次の例は、GET appointment メソッドを使用して予約のリストを返す方法を示しています。

    curl "http://instance.servicenow.com/api/sn_tmf_api/appointment/appointment" \ 
--request GET\ 
--user 'username':'password'

    応答本文には、予約サービス設定で構成された 2 つの異なる予約の詳細が含まれています。

    [
  {
    "id": "201071ad4f80d210f8992fec52ce0ba9",
    "href": "api/sn_tmf_api/appointment/appointment/201071ad4f80d210f8992fec52ce0ba9",
    "validFor": {
      "startDateTime": "2024-08-16 17:00:00",
      "endDateTime": "2024-08-16 19:00:00"
    },
    "category": "4a34a64d4f4c1210f8992fec52ce0b63",
    "relatedParty": [
      {
        "id": "eaf68911c35420105252716b7d40ddde",
        "name": " null",
        "role": "customer",
        "@referredType": "Individual"
      }
    ],
    "relatedPlace": {
      "id": "25ab9c4d0a0a0bb300f7dabdc0ca7c1c",
      "name": "100 South Charles Street, Baltimore,MD",
      "role": "interventionAddress",
      "@referredType": "Individual"
    },
    "relatedEntity": [
      {
        "id": "b440a5694f40d210f8992fec52ce0ba3",
        "role": "work order",
        "@referredType": "WorkOrder"
      }
    ],
    "creationDate": "2024-08-16 00:39:22",
    "lastUpdate": "2024-08-16 00:39:22"
  },
  {
    "id": "25c012c07f5c5610f8994fa63c866523",
    "href": "api/sn_tmf_api/appointment/appointment/25c012c07f5c5610f8994fa63c866523",
    "validFor": {
      "startDateTime": "2024-08-26 17:00:00",
      "endDateTime": "2024-08-26 19:00:00"
    },
    "category": "4a34a64d4f4c1210f8992fec52ce0b63",
    "relatedParty": [
      {
        "id": "eaf68911c35420105252716b7d40ddde",
        "name": " null",
        "role": "customer",
        "@referredType": "Individual"
      }
    ],
    "relatedPlace": {
      "id": "f48b21850a0a0ba7004182b18099696d",
      "name": "11251 Rancho Carmel Drive, San Diego,CA",
      "role": "interventionAddress",
      "@referredType": "Individual"
    },
    "relatedEntity": [
      {
        "id": "c0b09a047f109610f8994fa63c8665b4",
        "role": "work order",
        "@referredType": "WorkOrder"
      }
    ],
    "creationDate": "2024-08-23 22:18:43",
    "lastUpdate": "2024-08-23 22:18:43"
  }
]

    予約のオープン:GET /api/sn_tmf_api/appointment/appointment/{id}

    指定された ID に関連付けられた予約レコードを取得します。

    URL 形式

    デフォルト URL: /api/sn_tmf_api/appointment/appointment/{id}

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

    表 : 13. パスパラメーター
    名前 説明
    ID 取得する予約のSys_id。

    データタイプ：文字列

    テーブル:予約 [sn_apptmnt_booking_appointment_booking]
    表 : 14. クエリパラメーター
    名前 説明
    category カテゴリsys_idで予約をフィルタリングします。

    データタイプ：文字列

    テーブル：場所 (cmn_location)

    デフォルト:カテゴリsys_idが指定されていない場合、すべての予約が返されます。
    relatedEntity 作業指示書に関連付けられた関連エンティティの詳細。

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

    "relatedEntity": {
  "id": "String"
}
    relatedEntity.id 必須。関連エンティティのSys_id。

    データタイプ：文字列

    テーブル:workOrder [wm_order]

    デフォルト:sys_idが指定されていない場合はすべてを返します。
    関連パーティー 予約に関連付けられた関係者のsys_idで予約をフィルタリングします。

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

    "relatedParty": {
  "id": "String",
  "name": "String"
}

    デフォルト: relatedParty が指定されていない場合、すべての予約が返されます。
    relatedParty.id 関係者のSys_id。

    データタイプ：文字列

    テーブル： ユーザー [sys_user]
    relatedParty.name 関係者の名前。

    データタイプ：文字列
    relatedPlace サービスまたは修理の実施がスケジュールされている場所で予約をフィルタリングします。

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

    "relatedPlace": {
  "id": "String"
}

    デフォルト: relatedPlace が指定されていない場合、すべての予約が返されます。
    relatedPlace.id 関連する場所のSys_id。

    データタイプ：文字列

    テーブル：場所 (cmn_location)
    validFor 予約が有効な日付範囲で予約をフィルタリングします。

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

    "validFor":
{
  "endDateTime": "String",
  "startDateTime": "String"
}

    デフォルト: validFor が指定されていない場合、すべての予約が返されます。
    validFor.endDateTime 予約の終了日時。指定された終了日時の予約のみが応答に返されます。

    データタイプ：文字列

    形式:YYYY-MM-DD 00:00:00。例:2025-01-31 09:35:43。

    テーブル：場所 (cmn_location)
    validFor.startDateTime 予約の開始日時。指定された開始日時の予約のみが応答に返されます。

    データタイプ：文字列

    形式:YYYY-MM-DD 00:00:00。例:2025-01-31 09:35:43。

    テーブル：場所 (cmn_location)
    表 : 15. 要求本文パラメーター (XML または JSON)
    名前 説明
    なし

    ヘッダー

    次の要求ヘッダーと応答ヘッダーは、この HTTP アクションにのみ適用されるか、別の方法でこのアクションに適用されます。REST API で使用される一般的なヘッダーのリストについては、「 サポートされている REST API ヘッダー」を参照してください。

    表 : 16. 要求ヘッダー
    ヘッダー 説明
    受容 応答本文のデータ形式。application/jsonのみをサポートしています。
    表 : 17. 応答ヘッダー
    ヘッダー 説明
    Content-Type 要求本文のデータ形式。application/jsonのみをサポートしています。

    ステータスコード

    この HTTP アクションには、次のステータスコードが適用されます。REST API で使用される可能性のあるステータスコードのリストについては、「 REST API HTTP 応答コード」を参照してください。

    表 : 18. ステータスコード
    ステータスコード 説明
    200 成功。要求が正常に処理されました。
    400 要求が正しくありません。不正な要求タイプまたは不正な形式の要求が検出されました。
    404 見つかりません。要求されたアイテムが見つかりませんでした。

    応答本文のパラメーター

    名前 説明
    category 予約サービス構成用に構成されたレコードプロデューサーのSys_id。

    データタイプ：文字列

    保存場所:予約サービス設定 [sn_apptmnt_booking_service_config] テーブルの [カタログアイテム] フィールド。
    creationDate 予約が作成された日時。

    データタイプ：文字列

    形式:YYYY-MM-DD 00:00:00。例:2025-01-31 09:35:43。
    href 予約レコードへのハイパーリンク。別の Appointment Open API 要求でこのリンクを使用して、予約を再スケジュールまたは削除します。

    データタイプ：文字列
    ID 予約のSys_id。

    データタイプ：文字列

    保存場所:予約サービス設定 [sn_apptmnt_booking_service_config] テーブル
    前回の更新 予約が最後に更新された日時。

    データタイプ：文字列

    形式:YYYY-MM-DD 00:00:00。例:2025-01-31 09:35:43。
    relatedEntity 予約の関連エンティティに関する詳細。

    データタイプ:オブジェクトのアレイ

    "relatedEntity": [
 {
  "@referredType": "String",
  "id": "String",
  "role": "String"
  }
]
    relatedEntity.@referredType アイテムまたはサービスのタイプ。

    データタイプ：文字列

    保存場所:workOrder [wm_order] テーブル
    relatedEntity.id 関連エンティティのSys_id。

    データタイプ：文字列

    保存場所:workOrder [wm_order] テーブル
    relatedEntity.role ロール:関連エンティティの説明。

    可能な値:作業指示

    データタイプ：文字列

    保存場所:workOrder [wm_order] テーブル
    関連パーティー 予約の連絡先のリスト。各連絡先はアレイ内のオブジェクトです。

    データタイプ:オブジェクトのアレイ

    "relatedParty": [
 {
  "@referredType": "String",
  "id": "String",
  "name": " String",
  "role": "String"
 }
]
    relatedParty.@referredType 顧客のタイプ。

    データタイプ：文字列

    保存場所:連絡先 [customer_contact] テーブル
    relatedParty.id 作業指示書に関連付けられた顧客連絡先のSys_id。

    データタイプ：文字列

    保存場所:連絡先 [customer_contact] テーブル
    relatedParty.name 顧客の連絡先の名前。

    データタイプ：文字列

    保存場所:連絡先 [customer_contact] テーブル
    relatedParty.role 顧客連絡先のロール。
    可能な値：
    • customer:連絡先には顧客ロールがあります。
    • 技術者:連絡先には技術者ロールがあります。

    データタイプ：文字列

    保存場所:連絡先 [customer_contact] テーブル
    relatedPlace 関連付けられた予約の場所の詳細。

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

    "relatedPlace": {
  "@referredType": "String",
  "id": "String",
  "name": "String",
  "role": "String"
}
    relatedPlace.@referredType 予約の地理的住所。

    可能な値:GeographicLocation。

    データタイプ：文字列

    保存場所:場所 [cmn_location] テーブル
    relatedPlace.id 場所のSys_id。

    データタイプ：文字列

    保存場所:場所 [cmn_location] テーブル
    relatedPlace.name 連絡先に関連する場所の名前。例:100 South Charles Street, Baltimore, MD。

    データタイプ：文字列

    保存場所:場所 [cmn_location] テーブル
    relatedPlace.role 介入住所としての予約場所のロール。

    可能な値:InterventionAddress

    データタイプ：文字列

    保存場所:場所 [cmn_location] テーブル
    validFor 予約が有効な日付範囲。

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

    "validFor": {
 "endDateTime": "String"
 "startDateTime": "String"
}
    validFor.endDateTime 予約の終了日時。

    データタイプ：文字列

    形式:YYYY-MM-DD 00:00:00。例:2025-01-31 09:35:43。
    validFor.startDateTime 予約の開始日時。

    データタイプ：文字列

    形式:YYYY-MM-DD 00:00:00。例:2025-01-31 09:35:43。

    cURL 要求

    次の例は、指定された予約レコード ID に従って予約の詳細を返します。

    curl "http://instance.servicenow.com/api/sn_tmf_api/appointment/appointment/201071ad4f80d210f8992fec52ce0ba9" \ 
--request GET\ 
--user 'username':'password'

    応答本文:

    [
  {
    "id": "201071ad4f80d210f8992fec52ce0ba9",
    "href": "api/sn_tmf_api/appointment/appointment/201071ad4f80d210f8992fec52ce0ba9",
    "validFor": {
      "startDateTime": "2024-08-16 17:00:00",
      "endDateTime": "2024-08-16 19:00:00"
    },
    "category": "4a34a64d4f4c1210f8992fec52ce0b63",
    "relatedParty": [
      {
        "id": "eaf68911c35420105252716b7d40ddde",
        "name": " null",
        "role": "customer",
        "@referredType": "Individual"
      }
    ],
    "relatedPlace": {
      "id": "25ab9c4d0a0a0bb300f7dabdc0ca7c1c",
      "name": "100 South Charles Street, Baltimore,MD",
      "role": "interventionAddress",
      "@referredType": "Individual"
    },
    "relatedEntity": [
      {
        "id": "b440a5694f40d210f8992fec52ce0ba3",
        "role": "work order",
        "@referredType": "WorkOrder"
      }
    ],
    "creationDate": "2024-08-16 00:39:22",
    "lastUpdate": "2024-08-16 00:39:22"
  }
]

    予約のオープン:GET /api/sn_tmf_api/appointment/searchTimeSlot

    予約サービス設定で設定されたタイムスロットを、その可用性と共に返します。

    URL 形式

    /api/sn_tmf_api/appointment/searchTimeSlot

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

    表 : 19. パスパラメーター
    名前 説明
    なし
    表 : 20. クエリパラメーター
    名前 説明
    catalog_id 必須。予約サービス構成で構成されたレコードプロデューサーのSys_id。

    データタイプ：文字列

    テーブル:レコードプロデューサー [sc_cat_item_producer]
    end_date 必須。予約を検索する期間の終了日時。

    データタイプ：文字列

    形式:YYYY-MM-DD 00:00:00。例: 2025-01-31 12:00:00。
    場所 予約の場所のSys_id。

    テーブル：場所 (cmn_location)

    データタイプ：文字列

    デフォルト:指定されていない場合は、すべての場所が返されます。
    opened_for 必須。予約対象のユーザーのSys_id。

    テーブル:連絡先 [customer_contact]

    データタイプ：文字列
    start_date 必須。予約を検索する期間の開始日時。

    データタイプ：文字列

    形式:YYYY-MM-DD 00:00:00。例: 2025-01-31 09:00:00。
    表 : 21. 要求本文のパラメーター
    名前 説明
    なし

    ヘッダー

    次の要求ヘッダーと応答ヘッダーは、この HTTP アクションにのみ適用されるか、別の方法でこのアクションに適用されます。REST API で使用される一般的なヘッダーのリストについては、「 サポートされている REST API ヘッダー」を参照してください。

    表 : 22. 要求ヘッダー
    ヘッダー 説明
    受容 応答本文のデータ形式。application/jsonのみをサポートしています。
    表 : 23. 応答ヘッダー
    ヘッダー 説明
    なし

    ステータスコード

    この HTTP アクションには、次のステータスコードが適用されます。REST API で使用される可能性のあるステータスコードのリストについては、「 REST API HTTP 応答コード」を参照してください。

    表 : 24. ステータスコード
    ステータスコード 説明
    200 成功。要求が正常に処理されました。
    400 要求が正しくありません。不正な要求タイプまたは不正な形式の要求が検出されました。
    500 内部サーバーエラー要求の処理中に予期しないエラーが発生しました。応答には、エラーに関する追加情報が含まれています。

    応答本文のパラメーター

    名前 説明
    availableTimeSlot 指定された要求時間ブロック内の予約スロットのリスト。

    データタイプ:オブジェクトのアレイ

    'availableTimeSlot': [
 { 
  "available": Boolean,
  "end_date": "String",
  "end_date_display": "String",
  "end_dateUTC": "String",
  "start_date": "String",
  "start_date_display": "String",
  "start_dateUTC": "String"
 }
]
    availableTimeSlot.available 関連付けられたタイムスロットが利用可能かどうかを示すフラグ。
    可能な値：
    • true:タイムスロットが利用可能です。
    • false:タイムスロットは利用できません。

    データタイプ：ブール
    availableTimeSlot.end_date 関連付けられた予約の終了日時。タイムゾーンは、 timeZone パラメーターの値に基づきます。

    データタイプ：文字列

    形式:YYYY-MM-DD 00:00:00。例:2025-01-31 09:35:43。
    availableTimeSlot.end_date_display 関連付けられた予約の終了日時を表示します。タイムゾーンは、 timeZone パラメーターの値に基づきます。

    データタイプ：文字列

    形式:YYYY-MM-DD 00:00:00。例:2025-01-31 09:35:43。
    availableTimeSlot.end_dateUTC 関連付けられた予約の終了日時。

    データタイプ：文字列

    形式:UTC
    availableTimeSlot.start_date 関連付けられた予約の開始日時。timeZoneパラメーターの値を反映します。

    データタイプ：文字列

    形式:YYYY-MM-DD 00:00:00。例:2025-01-31 09:35:43。
    availableTimeSlot.start_date_display 関連付けられた予約の開始日時を表示します。timeZoneパラメーターの値を反映します。

    データタイプ：文字列

    形式:YYYY-MM-DD 00:00:00。例:2025-01-31 09:35:43。
    availableTimeSlot.start_dateUTC 関連付けられた予約の開始日時。

    データタイプ：文字列

    形式:UTC
    hasMore 制限を返した後にフェッチする予約スロットが他にあるかどうかを示すフラグ。この制限は、予約プロパティ sn_apptmnt_booking.max_appointments_returned で指定されます (デフォルト:100)。このプロパティの詳細については、「 Appointment booking components 」を参照してください。
    可能な値：
    • true:さらに予約スロットをフェッチできます。
    • false:利用可能な予約スロットはありません。

    データタイプ：ブール
    noApptAvailable 指定された日時に利用可能な予約スロットが他にあるかどうかを示すフラグ。
    有効な値：
    • true:指定された日時にさらに予約スロットが利用可能です。
    • false:指定された日時に利用可能な予約スロットはありません。

    データタイプ：ブール
    検索結果 指定された検索タイムスロット内の予約可能な結果。
    可能な値：
    • 成功
    • 失敗

    データタイプ：文字列
    ステータス 利用可能なタイムスロットの検索の完了ステータス。たとえば、「完了」などです。

    データタイプ：文字列
    タイムゾーン 指定された予約スロットの予約または更新時に使用されるタイムゾーン。

    日付タイプ:文字列

    形式:国/都市または地域の形式 (米国/東部など)

    cURL 要求

    次のコード例は、このエンドポイントを呼び出す方法を示しています。

    curl --location --request GET 'https://instance.service-now.com/api/sn_tmf_api/appointment/searchTimeSlot?
start_date=2024-07-10 09:00:00&end_date=2024-07-20 23:00:00&catalog_id=ada50a93f0220210f8776517d8c8e776&
opened_for=51670151c35420105252716b7d40ddfe&location=f48b21850a0a0ba7004182b18099696d ' \
--user 'username':'password'

    結果：

    {
  "searchResult": "success",
  "status": "done",
  "availableTimeSlot": [
    {
      "start_date": "2024-07-10 09:00:00",
      "end_date": "2024-07-10 12:00:00",
      "start_date_display": "09:00",
      "end_date_display": "12:00",
      "start_dateUTC": "2024-07-10 16:00:00",
      "end_dateUTC": "2024-07-10 19:00:00",
      "available": false
    },
    {
      "start_date": "2024-07-11 13:00:00",
      "end_date": "2024-07-11 16:00:00",
      "start_date_display": "13:00",
      "end_date_display": "16:00",
      "start_dateUTC": "2024-07-11 20:00:00",
      "end_dateUTC": "2024-07-11 23:00:00",
      "available": true
    },
    {
      "start_date": "2024-07-12 09:00:00",
      "end_date": "2024-07-12 12:00:00",
      "start_date_display": "09:00",
      "end_date_display": "12:00",
      "start_dateUTC": "2024-07-12 16:00:00",
      "end_dateUTC": "2024-07-12 19:00:00",
      "available": true
    },
    {
      "start_date": "2024-07-12 13:00:00",
      "end_date": "2024-07-12 16:00:00",
      "start_date_display": "13:00",
      "end_date_display": "16:00",
      "start_dateUTC": "2024-07-12 20:00:00",
      "end_dateUTC": "2024-07-12 23:00:00",
      "available": true
    },
    {
      "start_date": "2024-07-19 13:00:00",
      "end_date": "2024-07-19 16:00:00",
      "start_date_display": "13:00",
      "end_date_display": "16:00",
      "start_dateUTC": "2024-07-19 20:00:00",
      "end_dateUTC": "2024-07-19 23:00:00",
      "available": true
    }
  ],
  "hasMore": false,
  "noApptAvailable": false,
  "timeZone": "US/Arizona"
}

    予約オープン:PATCH /api/sn_tmf_api/appointment/appointment/{id}

    作業指示書の指定された ID で予約を再スケジュールします。

    URL 形式

    デフォルト URL: PATCH /api/sn_tmf_api/appointment/appointment/{id}

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

    表 : 25. パスパラメーター
    名前 説明
    ID スケジュールを変更する予約のSys_id。

    データタイプ：文字列

    テーブル:予約 [sn_apptmnt_booking_appointment_booking]
    表 : 26. クエリパラメーター
    名前 説明
    なし
    表 : 27. 要求本文パラメーター (JSON)
    名前 説明
    注意 予約をキャンセルする場合は、ここに作業メモを追加できます。作業指示書の作業メモと予約のメッセージを更新します。

    データタイプ:オブジェクトのアレイ

    "note": [ 
 {
  "author": "String", 
  "date": "String", 
  "text": "String"
 }
]

    保存場所:予約 [sn_apptmnt_booking_appointment_booking] テーブル
    note.author メモを作成した人の名前。

    データタイプ：文字列
    note.date メモが公開された日時。

    データタイプ：文字列

    形式:YYYY-MM-DD 00:00:00。例:2018-02-04T11:00:18.071Z。
    note.text 予約に添付されている作業指示書についての説明テキスト。たとえば、作業指示の進捗状況の更新などです。

    データタイプ：文字列
    ステータス 予約のステータス。

    有効な値：

    • cancelled:予約の再スケジュールがキャンセルされます。
    • completed:再スケジュールされた予約が完了しました。
    • 確認済み:予約の再スケジュールが承認され、予約されています。
    • 新規:予約の再スケジュール要求が最近作成されました。
    • pending:予約の再スケジュールが保留中です。
    • ready:予約のスケジュール変更が要求されます。

    データタイプ：文字列
    validFor 予約が有効な日付範囲で予約をフィルタリングします。

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

    "validFor":
{
  "endDateTime": "String",
  "startDateTime": "String"
}

    デフォルト: validFor が指定されていない場合、すべての予約が返されます。
    validFor.endDateTime 予約の終了日時。指定された終了日時の予約のみが応答に返されます。

    データタイプ：文字列

    形式:YYYY-MM-DD 00:00:00。例:2025-01-31 09:35:43。

    テーブル：場所 (cmn_location)
    validFor.startDateTime 予約の開始日時。指定された開始日時の予約のみが応答に返されます。

    データタイプ：文字列

    形式:YYYY-MM-DD 00:00:00。例:2025-01-31 09:35:43。

    テーブル：場所 (cmn_location)

    ヘッダー

    次の要求ヘッダーと応答ヘッダーは、この HTTP アクションにのみ適用されるか、別の方法でこのアクションに適用されます。REST API で使用される一般的なヘッダーのリストについては、「 サポートされている REST API ヘッダー」を参照してください。

    表 : 28. 要求ヘッダー
    ヘッダー 説明
    受容 応答本文のデータ形式。application/jsonのみをサポートしています。
    表 : 29. 応答ヘッダー
    ヘッダー 説明
    Content-Type 要求本文のデータ形式。application/jsonのみをサポートしています。

    ステータスコード

    この HTTP アクションには、次のステータスコードが適用されます。REST API で使用される可能性のあるステータスコードのリストについては、「 REST API HTTP 応答コード」を参照してください。

    表 : 30. ステータスコード
    ステータスコード 説明
    200 成功。要求が正常に処理されました。
    500 内部サーバーエラー要求の処理中に予期しないエラーが発生しました。応答には、エラーに関する追加情報が含まれています。

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

    名前 説明
    creationDate 予約が作成された日時。

    データタイプ：文字列

    形式:YYYY-MM-DD 00:00:00。例:2025-01-31 09:35:43。
    href 予約の一意の参照リンク。このリンクを別の要求で使用して、予約を取得できます。

    データタイプ：文字列
    ID 再スケジュールされた予約のSys_id。

    データタイプ：文字列

    保存場所:予約 [sn_apptmnt_booking_appointment_booking] テーブル
    前回の更新 予約が最後に更新された日時。

    データタイプ：文字列

    形式:YYYY-MM-DD 00:00:00。例:2025-01-31 09:35:43。
    理由 予約を更新する目的。

    可能な値：

    • 「予約が再スケジュールされました。」:PATCH メソッドを使用して予約がスケジュール変更されました。
    • 「予約 (ID) が正常にキャンセルされました。」:PATCH メソッドを使用して予約がキャンセルされました。

    データタイプ：文字列
    関連パーティー 関連付けられた予約の顧客詳細。

    データタイプ:オブジェクトのアレイ

    "relatedParty": [
  {
  "@referredType": "String",
  "id": "String",
  "name": "String",
  "role": "String"
  }
]
    relatedParty.id 顧客連絡先のSys_id。

    データタイプ：文字列

    保存場所:連絡先 [customer_contact] テーブル
    relatedParty.name 顧客の連絡先の名前。

    データタイプ：文字列
    relatedPlace.@referredType 顧客のタイプ。

    データタイプ：文字列

    可能な値のみ:個別
    relatedParty.role 連絡先のロール。

    データタイプ：文字列

    可能な値:連絡先のみ
    成功 要求が成功したかどうかを示すフラグ。
    可能な値：
    • true:予約は正常に変更されました。
    • false:予約を再スケジュールできませんでした。

    データタイプ：ブール

    cURL 要求

    次の例は、PATCH メソッドを使用して、指定された ID で予約を再スケジュールする方法を示しています。

    curl -X POST 'https://instance.service-now.com/api/sn_tmf_api/appointment/appointment/68cc0a5a9314521060320dd548373cbd ' \ 
-H "Accept: application/json" \ 
-H "Content-Type: application/json" \ 
-u "username":"password" \ 
-data {
  "validFor": { 
      "startDateTime": "2024-07-30 00:0:00", 
      "endDateTime": "2024-08-30 00:00:00" 
              }
  "note": {
      "date": "85388c25b71011104eed4643ae11a993",
      "author": "Sarah Johnson",
      "text": "customer"
    }
  "state": "active"
   }
  ]
}

    応答本文には、予約が再スケジュールされたことを示す成功メッセージが表示されます。

    {
  "relatedParty": [
    {
      "id": "85388c25b71011104eed4643ae11a993",
      "name": "Sarah Johnson",
      "role": "customer",
      "@referredType": "Individual"
    }
  ],
  "success": true,
  "reason": "Appointment rescheduled!",
  "id": "68cc0a5a9314521060320dd548373cbd",
  "href": "api/sn_tmf_api/appointment/appointment/68cc0a5a9314521060320dd548373cbd",
  "creationDate": "2024-08-30 20:56:54",
  "lastUpdate": "2024-08-30 20:56:54"
}

    予約のオープン:POST /api/sn_tmf_api/appointment/appointment

    作業指示書の予約を行うことができます。

    URL 形式

    /api/sn_tmf_api/appointment/appointment

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

    表 : 31. パスパラメーター
    名前 説明
    なし
    表 : 32. クエリパラメーター
    名前 説明
    なし
    表 : 33. 要求本文のパラメーター
    名前 説明
    category 必須。予約サービス構成用に構成されたレコードプロデューサーのSys_id。

    データタイプ：文字列

    テーブル:予約サービス設定 [sn_apptmnt_booking_service_config] テーブルの [カタログアイテム] フィールド内。
    relatedEntity 必須。予約に関連付けられた影響を受ける作業指示のリスト。

    データタイプ:オブジェクトのアレイ

    "relatedEntity": [
  {
    "@referredType": "String"
    "id": "String",
  }
]
    relatedEntity.@referredType 必須。アイテムまたはサービスのタイプ。

    有効な値:作業指示のみ

    データタイプ：文字列

    テーブル:作業指示 [wm_order]
    relatedEntity.id 必須。関連エンティティのSys_id。

    データタイプ：文字列

    テーブル:workOrder [wm_order]

    デフォルト:sys_idが指定されていない場合はすべてを返します。
    relatedEntity.role 必須。ロール:関連エンティティの説明。

    有効な値のみ:作業指示

    データタイプ：文字列

    テーブル:作業指示 [wm_order]
    関連パーティー 必須。予約の連絡先のリスト。各連絡先はアレイ内のオブジェクトです。要求には、顧客アカウント情報を含むアイテムが少なくとも 1 つリストされている必要があります。

    データタイプ:オブジェクトのアレイ

    "relatedParty": [ 
 {
  "@referredType": "String",
  "id": "String",
  "name": "String",
  "role": "String"
 }
]
    relatedParty.@referredType 顧客のタイプ。

    有効な値:個々

    データタイプ：文字列
    relatedParty.id 必須。作業指示書に関連付けられた連絡先のSys_idまたはexternal_id。

    データタイプ：文字列

    テーブル:連絡先 [customer_contact]
    relatedParty.name 連絡先の名前。

    データタイプ：文字列

    テーブル:連絡先 [customer_contact]
    relatedParty.role 必須。連絡先のロール。
    可能な値：
    • customer:連絡先には顧客ロールがあります。
    • 技術者:連絡先には技術者ロールがあります。

    データタイプ：文字列

    テーブル:連絡先 [customer_contact]
    relatedPlace 必須。予約に関連する場所のリスト。

    データタイプ:オブジェクトのアレイ

    "relatedPlace": [
 {
  "@referredType": "String",
  "id": "String",
  "name": "String",
  "role": "String"
 }
]
    relatedPlace.@referredType 必須。場所のタイプ。たとえば、市区町村です。

    データタイプ：文字列

    テーブル:場所 [cmn_location]
    relatedPlace.id 必須。関連する場所のSys_id。

    データタイプ：文字列

    テーブル:場所 [cmn_location]
    relatedPlace.name 連絡先に関連する場所の名前。例:251 Reddy St, Darwin, CA 93522。

    データタイプ：文字列

    テーブル:場所 [cmn_location]
    relatedPlace.role 必須。場所ロールの説明。たとえば、作業指示などです。

    データタイプ：文字列
    タイムゾーン 必須。指定された予約スロットを予約するときに使用するタイムゾーン。

    日付タイプ:文字列

    形式:国/都市または地域の形式 (米国/東部など)
    validFor 必須。予約が有効な日付範囲。

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

    "validFor": {
  "endDateTime": "String",
  "startDateTime": "String"
}
    validFor.endDateTime 必須。タイムスロットの終了日時。

    データタイプ：文字列

    形式:YYYY-MM-DD 00:00:00。例:2025-01-31 09:35:43。
    validFor.startDateTime 必須。タイムスロットの開始日時。

    データタイプ：文字列

    形式:YYYY-MM-DD 00:00:00。例:2025-01-31 09:35:43。

    ヘッダー

    次の要求ヘッダーと応答ヘッダーは、この HTTP アクションにのみ適用されるか、別の方法でこのアクションに適用されます。REST API で使用される一般的なヘッダーのリストについては、「 サポートされている REST API ヘッダー」を参照してください。

    表 : 34. 要求ヘッダー
    ヘッダー 説明
    受容 応答本文のデータ形式。application/jsonのみをサポートしています。
    表 : 35. 応答ヘッダー
    ヘッダー 説明
    Content-Type 要求本文のデータ形式。application/jsonのみをサポートしています。

    ステータスコード

    この HTTP アクションには、次のステータスコードが適用されます。REST API で使用される可能性のあるステータスコードのリストについては、「 REST API HTTP 応答コード」を参照してください。

    表 : 36. ステータスコード
    ステータスコード 説明
    200 成功。要求が正常に処理されました。
    500 内部サーバーエラー要求の処理中に予期しないエラーが発生しました。応答には、エラーに関する追加情報が含まれています。

    応答本文のパラメーター

    名前 説明
    category 予約サービス構成用に構成されたレコードプロデューサーのSys_id。

    データタイプ：文字列

    保存場所:予約サービス設定 [sn_apptmnt_booking_service_config] テーブルの [カタログアイテム] フィールド。
    creationDate 予約が作成された日時。

    データタイプ：文字列

    形式:YYYY-MM-DD 00:00:00。例:2025-01-31 09:35:43。
    href 予約レコードへのハイパーリンク。別の Appointment Open API 要求でこのリンクを使用して、予約を再スケジュールまたは削除します。

    データタイプ：文字列
    ID 予約のSys_id。

    データタイプ：文字列

    保存場所:予約サービス設定 [sn_apptmnt_booking_service_config] テーブル
    前回の更新 予約が最後に更新された日時。

    データタイプ：文字列

    形式:YYYY-MM-DD 00:00:00。例:2025-01-31 09:35:43。
    relatedEntity 予約の関連エンティティに関する詳細。

    データタイプ:オブジェクトのアレイ

    "relatedEntity": [
 {
  "@referredType": "String",
  "id": "String",
  "role": "String"
  }
]
    relatedEntity.@referredType アイテムまたはサービスのタイプ。

    データタイプ：文字列

    保存場所:workOrder [wm_order] テーブル
    relatedEntity.id 関連エンティティのSys_id。

    データタイプ：文字列

    保存場所:workOrder [wm_order] テーブル
    relatedEntity.role ロール:関連エンティティの説明。

    可能な値:作業指示

    データタイプ：文字列

    保存場所:workOrder [wm_order] テーブル
    関連パーティー 予約の連絡先のリスト。各連絡先はアレイ内のオブジェクトです。

    データタイプ:オブジェクトのアレイ

    "relatedParty": [
 {
  "@referredType": "String",
  "id": "String",
  "name": " String",
  "role": "String"
 }
]
    relatedParty.@referredType 顧客のタイプ。

    データタイプ：文字列

    保存場所:連絡先 [customer_contact] テーブル
    relatedParty.id 作業指示書に関連付けられた顧客連絡先のSys_id。

    データタイプ：文字列

    保存場所:連絡先 [customer_contact] テーブル
    relatedParty.name 顧客の連絡先の名前。

    データタイプ：文字列

    保存場所:連絡先 [customer_contact] テーブル
    relatedParty.role 顧客連絡先のロール。
    可能な値：
    • customer:連絡先には顧客ロールがあります。
    • 技術者:連絡先には技術者ロールがあります。

    データタイプ：文字列

    保存場所:連絡先 [customer_contact] テーブル
    relatedPlace 関連付けられた予約の場所の詳細。

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

    "relatedPlace": {
  "@referredType": "String",
  "id": "String",
  "name": "String",
  "role": "String"
}
    relatedPlace.@referredType 予約の地理的住所。

    可能な値:GeographicLocation。

    データタイプ：文字列

    保存場所:場所 [cmn_location] テーブル
    relatedPlace.id 場所のSys_id。

    データタイプ：文字列

    保存場所:場所 [cmn_location] テーブル
    relatedPlace.name 連絡先に関連する場所の名前。例:100 South Charles Street, Baltimore, MD。

    データタイプ：文字列

    保存場所:場所 [cmn_location] テーブル
    relatedPlace.role 介入住所としての予約場所のロール。

    可能な値:InterventionAddress

    データタイプ：文字列

    保存場所:場所 [cmn_location] テーブル
    成功 要求が成功したかどうかを示すフラグ。
    可能な値：
    • true:要求は成功しました。
    • false:要求は失敗しました。

    データタイプ：ブール
    タイムゾーン 指定された予約スロットの予約または更新時に使用されるタイムゾーン。

    日付タイプ:文字列

    形式:国/都市または地域の形式 (米国/東部など)
    validFor 予約が有効な日付範囲。

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

    "validFor": {
 "endDateTime": "String"
 "startDateTime": "String"
}
    validFor.endDateTime 予約の終了日時。

    データタイプ：文字列

    形式:YYYY-MM-DD 00:00:00。例:2025-01-31 09:35:43。
    validFor.startDateTime 予約の開始日時。

    データタイプ：文字列

    形式:YYYY-MM-DD 00:00:00。例:2025-01-31 09:35:43。

    cURL 要求

    次の例は、新しい予約を作成する方法を示しています。

    curl "https://instance.servicenow.com/api/sn_tmf_api/appointment/appointment" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
  \"validFor\": {
    \"startDateTime\": \"2024-08-19 09:00:00\",
    \"endDateTime\": \"2024-08-19 11:00:00\"
  },
  \"category\": \"e4c1116b3b810300ce8a4d72f3efc40f\",
  \"relatedParty\": [
    {
      \"id\": \"eaf68911c35420105252716b7d40ddde\",
      \"name\": \"Sally Thomas\",
      \"role\": \"customer\",
      \"@referredType\": \"Individual\"
    }
  ],
  \"relatedPlace\": {
    \"id\": \"25ab9c4d0a0a0bb300f7dabdc0ca7c1c\",
    \"name\": \"100 South Charles Street, Baltimore,MD\",
    \"role\": \"interventionAddress\",
    \"@referredType\": \"GeographicAddress\"
  },
  \"relatedEntity\": [
    {
      \"id\": \"48dbfbf9201f0250f877303e8a020dcd\",
      \"role\": \"work order\",
      \"@referredType\": \"WorkOrder\"
    }
  ],
  \"timeZone\": \"US/Arizona\"
}" \
--user 'username':'password'

    応答：

    {
  "validFor": {
    "startDateTime": "2024-07-19 09:00:00",
    "endDateTime": "2024-07-19 11:00:00"
  },
  "category": "e4c1116b3b810300ce8a4d72f3efc40f",
  "relatedParty": [
    {
      "id": "eaf68911c35420105252716b7d40ddde",
      "name": "Sally Thomas",
      "role": "customer",
      "@referredType": "Individual"
    }
  ],
  "relatedPlace": {
    "id": "25ab9c4d0a0a0bb300f7dabdc0ca7c1c",
    "name": "100 South Charles Street, Baltimore,MD",
    "role": "interventionAddress",
    "@referredType": "GeographicAddress"
  },
  "relatedEntity": [
    {
      "id": "48dbfbf9201f0250f877303e8a020dcd",
      "role": "work order",
      "@referredType": "WorkOrder"
    }
  ],
  "timeZone": "US/Arizona",
  "success": true,
  "id": "feacb7f9201f0250f877303e8a020d38",
  "href": "api/sn_tmf_api/appointment/appointment/feacb7f9201f0250f877303e8a020d38",
  "creationDate": "2024-07-10 22:45:01",
  "lastUpdate": "2024-07-10 22:45:01"
}