약속 오픈 API

호주 API 참조

Release

australia

ft:locale

ko-KR

ft:publication_title

호주 API 참조

ft:clusterId

crapiref

bundleId

crapiref

workflow

Creator

약속 오픈 API

릴리스 버전: Australia

업데이트 날짜 2026년 03월 12일

소요 시간: 20분

약속 오픈 API는 약속 예약 애플리케이션과 상호작용할 수 있는 통신 API입니다. 이 API를 사용하여 약속을 예약하고 사용 가능한 시간 슬롯을 검색합니다.

약속 개방형 API는 개방형 API TMForum TMF646 약속 REST API 사양의 구현이며 ServiceNow® TM Forum의 적합성 인증을 받았습니다. 이 구현은 TMF646 약속 API REST 사양 R16.0.1을 기반으로 합니다.

이 API에는 다음에서 사용할 수 있는 다음 플러그인이 필요합니다.ServiceNow Store

약속 예약(com.snc.appointment_booking)
현장 서비스 관리(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	내부 서버 오류입니다. 요청을 처리하는 동안 예기치 않은 오류가 발생했습니다. 응답에는 오류에 대한 추가 정보가 포함되어 있습니다.

응답 본문 매개변수


이름	설명
availableTime슬롯	지정된 요청 시간 블록 내의 약속 슬롯 목록입니다. 데이터 유형: 객체 배열 `'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 . 가능한 값: 예: 더 많은 약속 슬롯을 가져올 수 있습니다. 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"
}

약속 오픈 - POST /api/sn_tmf_api/appointment/appointment

작업 주문에 대한 약속을 예약할 수 있습니다.