외부 ID 매핑 API

  • 릴리스 버전: Australia
  • 업데이트 날짜 2026년 03월 12일
  • 소요 시간: 10분

    • 외부 CCaaS(연락처 센터 서비스형) 플랫폼이 기록에 대한 ServiceNow 라우팅 식별자를 저장하고 검색할 수 있도록 합니다.

    컨택 센터 통합 코어(sn_ct_ctr_it_core) 스토어 애플리케이션의 일부인 이 API를 사용하면 CCaaS 제공자가 CCaaS 외부 ID 매핑 [sn_ct_ctr_it_core_ccaas_external_id_mapping] 테이블에서 외부 ID를 가져오거나 설정할 수 있습니다. 이 API는 sn_ct_ctr_it_core 네임스페이스에 있으며 sn_ct_ctr_it_core.admin 역할이 필요합니다.

    이 API는 다중 공급자 환경을 지원하므로 조직은 각 공급자에 대해 별도의 라우팅 ID 네임스페이스를 유지하면서 여러 CCaaS 플랫폼과 동시에 통합할 수 있습니다.

    CCaaS 플랫폼(예: Genesys Cloud, Five9 또는 Amazon Connect)이 케이스, 작업 또는 상호작용을 외부 에이전트로 라우팅할 때 고유한 라우팅 ID를 생성합니다. 이 API는 이러한 외부 라우팅 ID를 기록에 매핑하는 중앙 집중식 메커니즘을 제공하여 CCaaS 플랫폼과 ServiceNow.

    사용 사례
    외부 라우팅 상관 관계
    CCaaS 플랫폼은 케이스를 외부 에이전트로 라우팅할 때 라우팅 ID를 생성합니다. CCaaS 플랫폼의 향후 이벤트, 콜백 또는 상태 업데이트의 상관 관계를 지정하기 위해 이 ID를 저장해야 합니다.
    이 API는 외부 라우팅 ID를 매핑 테이블에 저장하여 기록 및 생성한 제공자와 연결합니다.
    양방향 추적
    보고, 분석 및 문제 해결을 위해 어떤 외부 라우팅 세션이 어떤 케이스에 해당하는지 추적해야 할 수 있습니다.
    이 API를 사용하면 모든 기록에 대한 외부 라우팅 ID를 검색할 수 있으며, 대시보드와 보고서에서 전체 라우팅 이력을 표시할 수 있습니다.
    통합 유연성
    여러 CCaaS 플랫폼에서는 케이스, 작업, 상호작용 또는 사용자 지정 테이블과 같은 여러 테이블에 대한 라우팅 ID를 저장해야 할 수 있습니다.
    API는 유효한 테이블 이름을 허용하므로 향후 사용 사례에서 확장할 수 있습니다. 엔드포인트는 워크플로우에 따라 독립적으로 호출할 수 있습니다.

    CCaaS 시스템과의 통합에 대한 자세한 내용은 다음 문서를 참조하십시오 Integrating with contact centers.

    외부 ID 매핑 - GET /sn_ct_ctr_it_core/external_id_mapping/table/{tableName}/documentId/{documentId}

    특정 기록에 대한 외부 라우팅 ID 매핑을 조회합니다.

    이 엔드포인트는 매핑 테이블을 쿼리하여 지정된 기록 및 제공자에 대해 저장된 외부 라우팅 ID를 찾습니다. 이 엔드포인트를 사용하여 CCaaS 플랫폼에서 기록에 할당한 외부 라우팅 ID를 검색할 수 있습니다.

    URL 형식

    기본 URL: /api/sn_ct_ctr_it_core/external_id_mapping/table/{tableName}/documentId/{documentId}

    지원되는 요청 매개변수

    표 1. 경로 매개변수
    이름 설명
    tableName 필수 기록이 ServiceNow 포함된 테이블 이름입니다. 유효한 테이블 이름이 될 수 있습니다. 예를 들어 sn_customerservice_case, sn_customerservice_task, 상호작용 또는 사용자 지정 테이블이 있습니다.

    데이터 유형: 문자열
    documentId 필수 외부 ID 매핑을 검색할 기록의 sys_id ServiceNow 입니다.

    데이터 유형: 문자열
    표 2. 쿼리 매개변수
    이름 설명
    없음
    표 3. 요청 본문 매개변수(JSON)
    이름 설명
    안 함

    헤더

    다음 요청 및 응답 헤더는 이 HTTP 작업에만 적용되거나 고유한 방식으로 이 작업에 적용됩니다. REST API에 사용되는 일반 헤더 목록은 지원되는 REST API 헤더를 참조하십시오.

    표 4. 요청 헤더
    머리글 설명
    수용 응답 본문의 데이터 형식입니다. 지원되는 유형은 application/json 또는 application/xml입니다.

    기본값: application/json
    표 5. 응답 헤더
    머리글 설명
    안 함

    상태 코드

    이 HTTP 작업에 적용되는 상태 코드는 다음과 같습니다. REST API에 사용되는 가능한 상태 코드 목록은 REST API HTTP 응답 코드를 참조하십시오.

    표 6. 상태 코드
    상태 코드 설명
    200 성공입니다. 요청이 성공적으로 처리되었습니다.
    400 잘못된 요청입니다. 잘못된 요청 유형 또는 잘못된 형식의 요청이 탐지되었습니다.
    401 권한이 해제되었습니다. 사용자 자격 증명이 잘못되었거나 전달되지 않았습니다.
    403 금지되었습니다. 사용자에게 지정된 기록에 대한 액세스 권한이 없습니다.
    404 찾을 수 없습니다. 요청한 항목을 찾을 수 없습니다.
    500 내부 서버 오류입니다. 요청을 처리하는 동안 예기치 않은 오류가 발생했습니다. 응답에는 오류에 대한 추가 정보가 포함되어 있습니다.

    응답 본문 매개변수(JSON)

    이름 설명
    결과 요청에 대한 정보를 포함하는 결과 객체입니다.

    데이터 유형: 객체

    "result": { 
   "data": "String",
   "message": "String"
}
    결과.데이터 매핑에 대한 데이터입니다.

    데이터 유형: 객체

    "data": { 
  "document_id": "String", 
  "document_table": "String",
  "external_id": "String",
  "external_provider": "String"
}
    result.data.document_id 외부 ID 매핑을 검색할 기록의 sys_id ServiceNow AI Platform 입니다.

    데이터 유형: 문자열
    result.data.document_table 기록이 ServiceNow AI Platform 포함된 테이블 이름입니다.

    데이터 유형: 문자열
    result.data.external_id CCaaS 플랫폼의 외부 라우팅 ID입니다.

    최대 문자: 200

    데이터 유형: 문자열
    result.data.external_provider 외부 제공자 [awa_external_provider] 테이블의 제공자 sys_id입니다.

    데이터 유형: 문자열
    결과.오류.메시지 요청이 실패하면 요청이 실패한 이유를 설명하는 메시지입니다.

    데이터 유형: 문자열
    결과.오류 요청이 실패하면 요청이 실패한 이유를 설명하는 메시지입니다.

    데이터 유형: 문자열
    결과.오류.메시지 요청이 실패하면 요청이 실패한 이유를 설명하는 메시지입니다.

    데이터 유형: 문자열
    결과.메시지 API 요청의 결과를 설명하는 메시지입니다.

    데이터 유형: 문자열
    결과.상태 요청의 성공 또는 실패 상태입니다.
    유효한 값은 다음과 같습니다.
    • 성공
    • 실패

    데이터 유형: 문자열

    이 예에서는 f584a7b23b3d3e10c524c59a04e45a6f 가 sys_id 케이스에 대한 매핑을 쿼리하여 CCaaS 플랫폼에서 할당된 외부 라우팅 ID를 찾습니다.

    curl "https://instance.service-now.com/api/sn_ct_ctr_it_core/external_id_mapping/table/sn_customerservice_case/documentId/f584a7b23b3d3e10c524c59a04e45a6f" \
--request GET \
--header "Accept:application/json" \
--user 'admin':'admin'

    응답 본문:

    {
  "result": {
    "data": {
      "document_table": "sn_customerservice_case",
      "document_id": "f584a7b23b3d3e10c524c59a04e45a6f",
      "external_id": "200",
      "external_provider": "8b592fb64f140210c0338ef0b1ce0b18"
    }
  }
}

    외부 ID 매핑 - PUT /sn_ct_ctr_it_core/external_id_mapping/table/{tableName}/documentId/{documentId}

    기록에 대한 외부 라우팅 ID 매핑을 생성하거나 업데이트합니다 ServiceNow .

    이 엔드포인트는 멱등성이므로 동일한 매개변수로 여러 번 호출하면 중복 매핑이 생성되지 않고 기존 매핑이 업데이트됩니다. 엔드포인트는 테이블 이름, 문서 ID 및 외부 제공자의 조합에 따라 새 매핑을 삽입할지 아니면 기존 매핑을 업데이트할지를 자동으로 결정합니다.

    URL 형식

    기본 URL: /api/sn_ct_ctr_it_core/external_id_mapping/table/{tableName}/documentId/{documentId}

    지원되는 요청 매개변수

    표 7. 경로 매개변수
    이름 설명
    tableName 필수 기록이 ServiceNow 포함된 테이블 이름입니다. 유효한 테이블 이름이 될 수 있습니다. 예를 들어 sn_customerservice_case, sn_customerservice_task, 상호작용 또는 사용자 지정 테이블이 있습니다.

    데이터 유형: 문자열
    documentId 필수 외부 ID 매핑을 검색할 기록의 sys_id ServiceNow 입니다.

    데이터 유형: 문자열
    표 8. 쿼리 매개변수
    이름 설명
    없음
    표 9. 요청 본문 매개변수(JSON)
    이름 설명
    external_id 필수 CCaaS 시스템의 외부 에이전트 ID입니다.

    데이터 유형: 문자열

    최대 길이: 200자
    external_provider 외부 제공자 [awa_external_provider] 테이블의 제공자 기록 sys_id입니다. 이는 외부 ID를 생성한 CCaaS 플랫폼을 식별합니다.

    데이터 유형: 문자열

    헤더

    다음 요청 및 응답 헤더는 이 HTTP 작업에만 적용되거나 고유한 방식으로 이 작업에 적용됩니다. REST API에 사용되는 일반 헤더 목록은 지원되는 REST API 헤더를 참조하십시오.

    표 10. 요청 헤더
    머리글 설명
    수용 응답 본문의 데이터 형식입니다. application/json만 지원합니다.
    콘텐츠-형식 요청 본문의 데이터 형식입니다. application/json만 지원합니다.
    표 11. 응답 헤더
    머리글 설명
    안 함

    상태 코드

    이 HTTP 작업에 적용되는 상태 코드는 다음과 같습니다. REST API에 사용되는 가능한 상태 코드 목록은 REST API HTTP 응답 코드를 참조하십시오.

    표 12. 상태 코드
    상태 코드 설명
    200 성공입니다. 요청이 성공적으로 처리되었습니다.
    201 만든. 외부 ID 매핑이 성공적으로 생성되었습니다. 즉, 새 매핑이 삽입되었습니다.
    400 잘못된 요청입니다. 잘못된 요청 유형 또는 잘못된 형식의 요청이 탐지되었습니다.
    401 권한이 해제되었습니다. 사용자 자격 증명이 잘못되었거나 전달되지 않았습니다.
    403 금지되었습니다.
    가능한 이유:
    • 사용자에게 awa_integration_user 역할이 없습니다.
    • glide.awa.enabled 속성 값이 예가 아닙니다. 고급 작업 할당(com.glide.awa) 플러그인이 설치된 경우 이 속성은 시스템 속성 [sys_property] 테이블에 나열됩니다. 자세한 내용은 고급 작업 할당과 함께 설치되는 구성요소를 참조하십시오.
    404 찾을 수 없습니다. 요청한 항목을 찾을 수 없습니다.
    500 내부 서버 오류입니다. 요청을 처리하는 동안 예기치 않은 오류가 발생했습니다. 응답에는 오류에 대한 추가 정보가 포함되어 있습니다.

    응답 본문 매개변수(JSON)

    이름 설명
    결과 요청에 대한 정보를 포함하는 결과 객체입니다.

    데이터 유형: 객체

    "result": { 
   "data": "String",
   "message": "String"
}
    결과.오류.메시지 요청이 실패하면 요청이 실패한 이유를 설명하는 메시지입니다.

    데이터 유형: 문자열
    결과.오류 요청이 실패하면 요청이 실패한 이유를 설명하는 메시지입니다.

    데이터 유형: 문자열
    결과.오류.메시지 요청이 실패하면 요청이 실패한 이유를 설명하는 메시지입니다.

    데이터 유형: 문자열
    결과.메시지 API 요청의 결과를 설명하는 메시지입니다.

    데이터 유형: 문자열
    결과.상태 요청의 성공 또는 실패 상태입니다.
    유효한 값은 다음과 같습니다.
    • 성공
    • 실패

    데이터 유형: 문자열

    cURL 요청

    이 예에서는 CCaaS 플랫폼의 외부 ID를 저장하는 방법을 보여줍니다(제공자 sys_id 8b592fb64f140210c0338ef0b1ce0b18).

    curl "https://instance.service-now.com/api/sn_ct_ctr_it_core/external_id_mapping/table/sn_customerservice_case/documentId/f584a7b23b3d3e10c524c59a04e45a6f" \
--request PUT \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
    \"external_id\": \"200\",
    \"external_provider\": \"8b592fb64f140210c0338ef0b1ce0b18\"
}" \
--user 'admin':'admin'

    응답 본문:

    {
  "result": {
    "message": "External ID mapping record updated for sn_customerservice_case [f584a7b23b3d3e10c524c59a04e45a6f]",
    "status": "success"
  }
}