予約オープン API

Yokohama API リファレンス

Release

yokohama

ft:locale

ja-JP

ft:publication_title

Yokohama API リファレンス

ft:clusterId

crapiref

bundleId

crapiref

workflow

Creator

予約オープン API

リリースバージョン: Yokohama

更新日 2025年01月30日

所要時間：21分

Appointment Open API は、予約アプリケーションを操作できるようにする電気通信 API です。この API を使用して、予約を行い、利用可能な時間帯を検索します。

Appointment Open API は、Open API TMForum TMF646 Appointment REST API 仕様のServiceNow®実装であり、TM Forum の適合認定を受けています。この実装は、 TMF646 Appointment API REST Specification R16.0.1 に基づいています。

この API には、 ServiceNow Store で利用可能な次のプラグインが必要です。

予約 (com.snc.appointment_booking)
Field Service Management (フィールドサービス管理 (FSM)) (com.snc.work_management)
電気通信のフィールドサービス管理 (com.sn_fsmt)
電気通信オープン API (com.sn_tmf_api)

この API を使用する前に、予約設定とサービス設定を設定する必要があります。さらに、予約が取り込まれているタスクが存在する必要があります。

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

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

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

URL 形式

/api/sn_tmf_api/appointment/searchTimeSlot

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

表 : 1. パスパラメーター
名前	説明
なし

表 : 2. クエリパラメータ
名前	説明
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`。

表 : 3. 要求本文パラメーター
名前	説明
なし

ヘッダー

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

表 : 4. 要求ヘッダー
ヘッダー	説明
承認	応答本文のデータフォーマット。application/json のみをサポートします。

表 : 5. 応答ヘッダー
ヘッダー	説明
なし

ステータスコード

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

表 : 6. ステータスコード
ステータスコード	説明
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:指定された日時に利用できる予約スロットがなくなります。データタイプ：ブーリアン
検索結果	指定された検索タイムスロット内での予約の空き状況の結果。可能な値：正常終了失敗データタイプ：文字列
ステータス	利用可能なタイムスロット検索の完了ステータス。たとえば、done です。データタイプ：文字列
タイムゾーン	指定された予約スロットを予約または更新するときに使用されるタイムゾーン。日付タイプ：文字列形式:米国/東部などの国/都市または地域の形式

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'

Result (結果)：

{
  "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"
}

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

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