고객사 API 연동하기

고객사 API 연동은 CLUe 장치가 인식한 크리덴셜(얼굴, 지문, RF 카드, PIN, CLUe QR, 커스텀 QR 등)을 고객사가 운영하는 외부 API로 전달하고, 그 응답에 따라 출입을 허용하거나 거부하는 출입 방식입니다. 이 방식을 사용하면 출입 권한, 근태, 방문자 관리 등 고객사 고유의 정책을 별도 개발 없이 CLUe 출입 제어에 직접 반영할 수 있습니다.

CLUe는 크리덴셜을 인식해 고객사 API로 전달하는 역할만 수행하며, 실제 출입 허용 여부는 고객사 API의 응답에 따라 결정됩니다.

시작하기 전에

대상

이 문서는 공간 그룹 관리자와 공간 관리자를 대상으로 합니다.

• 공간 그룹 관리자: 고객사(Vendor) API를 등록 및 수정, 삭제하고, 크리덴셜 타입과 API를 매핑하며, 설정을 하위 공간에 적용합니다.

• 공간 관리자: 공간 그룹에서 상속받은 설정을 검토하고, 필요할 때 공간별로 재정의를 적용합니다.

알아두기

이 문서는 HTTPS, HTTP 상태 코드, Webhook(HTTP POST), JSON, JSONPath에 익숙한 IT 관리자를 대상으로 합니다. 고객사 API 스펙(URL, 인증 헤더, 요청/응답 JSON 구조)은 사전에 고객 담당자와 협의하세요.

사전 준비

• 이 메뉴에 접근하려면 대상 공간 그룹(또는 공간)에 관리자로 초대되어야 합니다.

• 고객사의 인증용 Webhook URL(HTTPS 필수, HTTP POST 수신)과 필요한 인증 헤더 값을 미리 확보하세요.

주요 용어

용어	설명
고객사 API 연동(Customer API Integration)	사용자가 장치에 크리덴셜을 제시하면 크리덴셜 데이터를 고객사(Vendor)가 운영하는 외부 API로 전송해 검증하는 출입 방식입니다.
크리덴셜(Credential)	얼굴 / 지문 / RF 카드 / 사용자 PIN / CLUe QR / 커스텀 QR
웹훅 URL	CLUe로부터 인증 요청(HTTP POST, Content-Type: application/json)을 받기 위해 고객사 서버가 개방하는 HTTPS 엔드포인트입니다.
요청 헤더(Request Header)	인증 및 권한 부여를 위해 요청과 함께 전송하는 Key/Value 쌍입니다. (예: Authorization 토큰)
자동 필드	시스템이 요청 본문에 자동으로 채우는 값입니다. 필요한 필드만 선택하세요.
수동 필드	관리자가 요청 본문에 포함하기 위해 직접 입력하는 고정 값입니다.
판정 기준(Judgment Criteria)	고객사 응답을 출입 허용 또는 거부로 해석하는 규칙 집합(statusCode, 성공 결과 Key/Value, 성공/실패 메시지 키)입니다. 화면에는 응답 파싱 섹션으로 표시됩니다.
판정 모드(Judgment Mode)	판정 기준을 구성하는 요소입니다. HTTP 응답 코드만 사용 / 응답 본문 필드만 사용 / 두 가지 조합 중 하나를 선택합니다.

고객사 API 연동

고객사 API 연동은 CLUe 장치가 인식한 크리덴셜 데이터를 고객사가 운영하는 HTTPS API로 전달하고, 그 응답을 기반으로 출입 허용/거부를 판정하는 출입 방식입니다. 이를 통해 출입 권한, 근태, 방문자 관리 등 고객사 고유의 정책을 CLUe 출입 제어에 직접 반영할 수 있습니다.

• 얼굴, 지문, RF 카드, PIN, CLUe QR, 커스텀 QR 등 각 크리덴셜 타입마다 서로 다른 고객사 API를 연결할 수 있습니다.

• 등록을 저장하기 전에 테스트 호출로 연동 동작을 미리 확인할 수 있습니다.

• CLUe는 크리덴셜을 식별해 전달하는 역할만 하며, 실제 허용 또는 거부 결정은 고객사 API의 응답에 따라 결정됩니다.

지원 크리덴셜

• 얼굴

• 지문

• RF 카드

• 사용자 PIN

• CLUe QR

• 커스텀 QR

공간 그룹과 공간의 역할

레벨	역할	담당 업무
공간 그룹	공간 그룹 관리자	고객사 API 등록/수정/삭제, API와 크리덴셜 연결
공간	공간 관리자	상속된 설정 검토, 필요 시 공간별 재정의 적용

적용 규칙

• 공간 그룹 레벨에서 저장: 동일한 설정이 해당 공간 그룹의 모든 하위 공간에 즉시 적용됩니다. 기존에 적용되어 있던 공간별 재정의는 공간 그룹 값으로 덮어쓰기됩니다.

• 공간 레벨에서 저장: 해당 공간에만 적용됩니다. 다른 공간이나 상위 공간 그룹에는 영향을 주지 않습니다.

주요 작업 워크플로우

고객사 API 연동은 크게 두 가지 워크플로우(Workflow)로 구성됩니다. 관리자가 먼저 수행하는 설정 워크플로우와 사용자가 실제로 출입을 시도할 때 진행되는 출입 이벤트 워크플로우입니다.

설정 워크플로우 개요

관리자가 수행하는 단계입니다. 각 단계는 4장부터 자세히 설명합니다.

1. (공간 그룹) 출입 방식을 선택하세요.

   • 고객사 확인 또는 혼합 / 고급 방식

   • 왼쪽 사이드바에서 고객사 API 연동 항목이 활성화됩니다.

2. (공간 그룹) 고객사 API 연동에서 API 등록하세요.

   기본 정보 → 커스텀 헤더 → 자동 필드 → 수동 필드 → 테스트 실행 → 응답 파싱 구성 → 저장

3. (공간 그룹) 등록한 API를 각 크리덴셜에 연결하세요.

   저장하면 동일한 설정이 모든 하위 공간에 자동 적용됩니다.

4. (선택 사항) 공간별 재정의 설정하세요.

   선택한 공간에만 적용됩니다. 기본값은 공간 그룹 설정을 그대로 사용합니다.

출입 이벤트 워크플로우 개요

설정을 마친 후 사용자가 실제로 출입을 시도할 때 처리되는 순서입니다.

1. 사용자가 장치에 크리덴셜을 제시합니다. (얼굴 / 지문 / RF 카드 / PIN / CLUe QR / 커스텀 QR)

2. 장치 → CLUe 서버로 검증 요청을 전송합니다.

3. CLUe 서버 → 고객사 서버로 검증 요청을 전송합니다.

   등록된 Webhook URL, 커스텀 헤더, 자동 필드, 수동 필드 포함

4. CLUe 서버가 고객사 응답을 기반으로 출입 여부를 판정합니다.

   설정한 판정 기준에 따라 허용/거부 결정합니다.

5. 결과를 장치로 반환합니다.

   응답에 메시지가 포함되어 있으면 장치 화면에 표시됩니다.

설정 워크플로우

1단계 — 고객사 API 연동 활성화

1. CLUe 웹 포털에 로그인하세요.

2. 공간 그룹을 선택하세요.

3. 화면 오른쪽 상단의 → 상세 설정을 클릭하세요.

   

4. 화면 왼쪽 사이드바에서 서비스 설정을 클릭하세요.

   초기 상태에서는 출입 방식이 선택 없음으로 설정되어 있습니다. 이 상태에서는 아무 설정도 활성화되지 않습니다.

   

5. 출입 방식에서 고객사 확인을 선택하세요.

6. 확인 대상 섹션이 나타납니다.

   

   확인 대상 섹션에는 지원하는 6개 크리덴셜이 모두 표시됩니다. 이후 각 크리덴셜에 등록한 고객사 API를 연결할 수 있습니다.

7. 왼쪽 사이드바에서 고객사 API 연동이 활성화되면 클릭하세요.

알아두기

• 고객사 API 연동은 출입 방식이 고객사 확인 또는 혼합 / 고급 방식으로 설정되어 있을 때 활성화됩니다.

• 이 단계에서는 저장할 필요가 없습니다. 연결할 API를 등록하려면 #vendorApiregistration을 참고하세요.

2단계 — 고객사 API 등록

API 추가

1. 화면 오른쪽 상단의 API 추가 버튼을 클릭하세요.

   

2. API 추가 패널이 나타나면 필요한 정보를 입력하세요.

   

기본 정보 입력

필드	설명	필수 여부	입력 규칙
커넥터 이름	이 연동을 식별할 이름을 입력하세요.	필수	최대 64자까지 입력할 수 있습니다.
인증 방식	이 API를 사용할 크리덴셜을 선택하세요.	필수	6개 타입 중 하나를 선택하세요.
웹훅 URL	고객사 Webhook URL입니다.	필수	https://로 시작해야 하며 최대 512자입니다. http:// URL은 저장할 수 없습니다.

알아두기

인증 방식은 한 번 설정하면 변경할 수 없습니다. 다른 크리덴셜 타입에 사용하려면 새 API를 등록하세요.

요청 규격

CLUe는 등록된 URL에 HTTP POST, Content-Type: application/json 요청만 전송합니다. 고객사 API는 이 형식의 요청을 받을 수 있어야 하며, GET, PUT 등 다른 메서드만 허용하는 엔드포인트는 사용할 수 없습니다.

응답 규격

고객사 API는 응답 헤더에 Content-Type: application/json을 포함해야 하며, 응답 본문을 JSON 형식으로 반환해야 합니다. HTML 오류 페이지, 일반 텍스트, XML 등 JSON이 아닌 응답은 CLUe가 파싱할 수 없어 테스트와 실제 출입 검증이 모두 실패합니다.

Example response body

{
   "valid": true,
   "message": "Access granted."
}

위 예시에서는 판정 기준의 Key를 $.valid로, Value를 true(BOOLEAN)로 설정해 성공 조건을 정의하고, 성공 메시지 JSONPath를 $.message로 설정해 성공 메시지를 표시할 수 있습니다. 실제 키 이름과 구조는 고객사 API 스펙에 맞춰야 합니다.

등록 제한

크리덴셜 타입당 최대 3개의 API를 등록할 수 있습니다. 즉 얼굴, 지문, RF 카드, PIN, CLUe QR, 커스텀 QR, 6개 타입을 합쳐 공간 그룹당 최대 18개의 API를 등록할 수 있습니다. 이미 3개가 등록된 크리덴셜 타입에는 추가로 등록할 수 없습니다. 각 크리덴셜에 실제로 사용할 API는 #credentialApiAssignment에서 선택합니다.

커스텀 헤더 추가

고객사 API에서 Authentication/Authorization headers를 요구한다면 커스텀 헤더를 추가하세요.

예: Authorization 토큰, API 키

필드	설명
헤더 이름	헤더 이름(예: Authorization)을 입력하세요. 중복된 이름은 허용되지 않습니다.
헤더 값	헤더 값을 입력하세요.

• 커스텀 헤더는 최대 10개까지 추가할 수 있습니다.

• 고객사 API가 공개 엔드포인트이거나 별도 헤더가 필요 없다면 이 섹션은 비워 두세요.

• 행을 삽입하려면 추가 버튼을 클릭하고, 삭제하려면 버튼을 클릭하세요.

고정 헤더는 설정할 수 없음

Content-Type과 Accept는 커스텀 헤더로 추가할 수 없습니다. CLUe가 내부적으로 Content-Type: application/json과 Accept: application/json을 고정 값으로 전송하므로 관리자가 별도로 지정할 필요가 없습니다. 이 이름으로 헤더를 추가하려고 하면 저장되지 않습니다. 고객사 API는 이 두 헤더를 전제로 설계해야 합니다.

자동 필드 선택

자동 필드는 시스템이 요청 본문에 자동으로 채우는 값입니다. 사용할 수 있는 자동 필드는 크리덴셜 타입에 따라 달라집니다. 각 필드의 값 위치는 {{...}} 플레이스홀더로 표시되며, 요청 시점에 실제 장치/사용자 값으로 대체됩니다.

기본 키	플레이스홀더(값 위치)	사용 가능 대상	실제 값
deviceId	{{DEVICE_SERIAL}}	모든 크리덴셜 타입	요청한 장치의 일련번호
userKey	{{USER_KEY}}	얼굴 / 지문 / CLUe QR	CLUe가 관리하는 사용자 식별자
rfCard	{{CARD_NUMBER}}	RF 카드	제시한 카드 번호
uniquePin	{{UNIQUE_PIN}}	사용자 PIN	입력한 PIN 값
qrCode	{{QR_CODE}}	커스텀 QR	QR 페이로드

필드 선택 규칙

• 각 필드 왼쪽의 체크박스로 요청에 포함할지 여부를 결정합니다.

• 모두 선택할 필요는 없습니다. 고객사 API가 판정에 실제로 필요로 하는 값만 선택하세요. 불필요한 데이터를 줄이면 문제 진단이 쉬워집니다.

• 키(필드 이름)는 수정할 수 있습니다. 고객사 API가 요구하는 이름(예: userKey → employeeId)에 맞게 변경하세요. 값 위치의 플레이스홀더는 시스템이 고정하므로 변경할 수 없습니다.

• 각 필드의 데이터 형식(예: STRING)은 필드 오른쪽에 표시됩니다.

알아두기

• 5가지 외에 다른 플레이스홀더는 추가할 수 없습니다. 고객사 API가 추가 값을 요구한다면 #manualField를 참고하여 고정 값을 추가하거나, 고객사와 협의해 장치 일련번호나 사용자 키를 통해 고객사 측에서 파생하도록 처리하세요.

• 자동 필드와 수동 필드를 합쳐 요청 본문에 최대 10개 필드를 포함할 수 있습니다. 자동 필드를 많이 선택할수록 사용할 수 있는 수동 필드 수는 줄어듭니다.

수동 필드 추가

고객사 API가 고정 값을 요청에 포함하도록 요구할 때 수동 필드를 추가하세요.

필드	설명
필드 이름	필드 이름은 고유해야 하며, 자동 필드 이름과도 달라야 합니다.
필드 타입	STRING, NUMBER, BOOLEAN 중 선택하세요.
값	이 필드의 값을 입력하세요. 선택한 타입에 따라 적절한 JSON 데이터 타입으로 변환됩니다. 예: NUMBER: 123, STRING: "123", BOOLEAN: true/false

• 자동 필드와 수동 필드를 합쳐 최대 10개까지 포함할 수 있습니다.

• 추가된 수동 필드가 없으면 등록된 수동 필드가 없습니다. 메시지가 표시됩니다.

• 행을 삽입하려면 추가 버튼을 클릭하고, 삭제하려면 버튼을 클릭하세요.

API 테스트 실행

기본 정보, 커스텀 헤더, 자동 필드, 수동 필드를 완료했다면, 판정 기준(judgment criteria)을 구성하기 전에 먼저 테스트를 실행하세요. 테스트로 얻은 실제 응답(response)은 판정 기준 구성(#responseParsing)에 필요합니다.

API 추가 패널 오른쪽의 API 테스트 콘솔을 사용하세요.

테스트 파라미터

테스트 콘솔에 표시되는 입력 필드는 크리덴셜 타입에 따라 달라집니다. 장치 ID(장치 일련번호)는 모든 타입에서 필수이며, 나머지 입력값은 해당 크리덴셜 타입에서 사용하는 값을 고객사가 관리하는 형식 그대로 입력합니다.

인증 방식	입력할 값	대응하는 플레이스홀더
모든 타입	장치 ID — 9~12자리 숫자, 장치 일련번호	{{DEVICE_SERIAL}}
얼굴 / 지문 / CLUe QR	사용자 Key — 1~64자, CLUe가 관리하는 사용자 식별자	{{USER_KEY}}
RF 카드	고객사가 관리하는 카드 번호	{{CARD_NUMBER}}
사용자 PIN	고객사가 관리하는 사용자 PIN	{{UNIQUE_PIN}}
커스텀 QR	고객사가 관리하는 QR 페이로드	{{QR_CODE}}

테스트 콘솔에 입력한 값은 자동 필드 플레이스홀더를 대체해 실제 요청 본문으로 전송됩니다. 테스트할 때는 고객사 데이터베이스에 실제로 존재하는 값을 입력해 허용과 거부 응답을 모두 확인하세요. 실제 운영 환경에서는 장치가 인식한 값이 자동으로 대입됩니다.

테스트 실행

1. 콘솔 하단의 테스트 실행 버튼을 클릭하세요.

2. 테스트를 실행하는 동안 진행 표시가 나타납니다.

3. 결과를 받으면 요청/응답 내용이 터미널 출력 콘솔 영역에 표시됩니다.

실행 중 패널을 닫거나 이전 단계로 이동하면 테스트가 중단됩니다.

응답을 성공적으로 받으면 다음 단계로 이동해 응답 내용을 기반으로 판정 기준(judgment criteria)을 구성하세요. URL, 헤더, 필드 설정 문제로 응답을 받지 못했다면 해당 입력값을 검토한 후 다시 테스트하세요.

저장하기 전 필수 조건

설정 저장 버튼은 최소 한 번 테스트에 성공해야 활성화됩니다. 여기서 성공이란 고객사 서버로부터 어떤 형태로든 HTTP 응답(4xx, 5xx 포함)을 받은 것을 의미합니다. 네트워크 오류로 응답을 받지 못했다면 저장할 수 없습니다.

테스트 실패 예시 — 응답 본문이 JSON이 아닐 때

고객사 서버가 응답을 반환하더라도 본문이 JSON 형식이 아니거나 응답 헤더의 Content-Type이 application/json이 아니면, 테스트 콘솔에 오류와 함께 실패 로그가 표시되고 설정 저장 버튼은 활성화되지 않습니다.

#responseSpec을 참고하여 고객사 담당자와 함께 API가 다음 두 조건을 모두 충족하는지 확인하세요.

• 응답 헤더에 Content-Type: application/json이 포함되어 있는지

• 응답 본문이 유효한 JSON인지(HTML 오류 페이지, 일반 텍스트, XML 등이 아닌지)

응답 파싱 구성

받은 응답을 기준으로, 이 단계에서 어떤 응답을 출입 허용(성공)으로 해석할지 정의합니다. 설정한 기준에 일치하는 응답은 출입 허용으로, 나머지는 모두 출입 거부로 처리합니다.

판정 모드는 입력한 필드에 따라 자동 결정됩니다. statusCode와 성공 결과 JSONPath 중 최소 하나는 반드시 입력해야 하며, 둘 다 비워두면 저장할 수 없습니다.

#	모드	입력	성공 기준
1	응답 코드 검증	statusCode only	HTTP 상태 코드가 목록의 값 중 하나와 일치하면 성공합니다.
2	응답 본문 검증	성공 결과 JSONPath only	HTTP 응답 코드와 관계없이 본문의 Key = Value 조건을 충족하면 성공합니다. 조건을 충족하면 4xx/5xx 응답이라도 허용됩니다.
3	결합 검증	둘 다	상태 코드가 일치하고 동시에 본문 조건도 충족할 때 성공합니다. 상태 코드가 일치하지 않으면 본문은 평가하지 않습니다.

statusCode (모드 1, 3에서 사용)

• 100~399 범위의 정수만 지정할 수 있습니다. 4xx, 5xx 코드는 성공으로 지정할 수 없습니다.

• 최대 3개까지 지정할 수 있으며, 중복된 값은 허용되지 않습니다.

• 여러 값을 지정하면 그중 하나라도 일치하면 성공(예: 200, 201)으로 처리합니다.

성공 결과 JSONPath (모드 2, 3에서 사용)

• 성공 응답을 식별할 Key, Value, 데이터 형식(BOOLEAN, STRING, NUMBER)을 입력합니다.

• 성공 키 조건은 1개만 설정할 수 있습니다.

• 이 조건에 일치하지 않는 응답은 출입 거부로 처리됩니다.

성공 메시지 JSONPath / 실패 메시지 JSONPath (선택 사항)

• 인증 성공/실패 시 각각 장치 화면에 표시할 문자열을 추출할 키를 지정합니다. 일반적으로 $.message를 사용합니다.

• 지정하지 않아도 저장할 수 있습니다. 비워두면 허용/거부만 판정하고 장치 화면에는 메시지가 표시되지 않습니다.

• 성공과 실패에 서로 다른 키를 지정할 수 있습니다.

• 지정한 키의 값은 반드시 문자열이어야 하며, 장치 화면 크기를 고려해 너무 길지 않아야 합니다.

팁

JSONPath를 직접 입력하기 어렵다면

응답 영역에서 필드를 성공 결과 JSONPath, 성공 메시지 JSONPath, 실패 메시지 JSONPath 입력란에 드래그 앤 드롭하면 JSON 경로가 자동으로 채워집니다. JSONPath를 직접 작성할 필요가 없습니다.

저장

API 추가 패널 하단의 설정 저장 버튼은 모든 필수 항목과 판정 기준이 올바르게 입력되고, API 테스트가 최소 한 번 성공했을 때 활성화됩니다.

• 필수 필드 누락, URL 형식 오류, 지정한 타입으로 변환할 수 없는 수동 필드 값, 판정 기준 미입력, 테스트 미성공(네트워크 오류 포함) 중 하나라도 해당하면 설정 저장 버튼은 비활성화된 상태로 유지됩니다.

• 등록을 완료하려면 설정 저장 버튼을 클릭하세요.

API를 저장하면 패널이 닫히고 새로 등록한 API가 목록에 카드로 표시됩니다. 카드에는 이름, 크리덴셜 타입, 등록된 URL 등의 정보가 표시됩니다.

• API를 수정하려면 카드를 클릭하세요. 수정 패널이 열립니다. 커넥터 이름, 웹훅 URL, 자동 필드, 수동 필드, 응답 파싱을 수정할 수 있습니다. 인증 방식은 수정할 수 없습니다.

• 삭제: 등록한 API를 삭제합니다. 이 API가 크리덴셜에 연결되어 있었다면 해당 연결도 자동으로 해제되며 변경 사항이 즉시 장치에 적용됩니다. 연결이 해제된 크리덴셜은 이후 고객사 검증 없이 장치 자체 인증만으로 동작합니다. 운영 공백이 우려된다면 삭제하기 전에 대체 API를 먼저 등록하고 연결하세요.

  

3단계 — 각 크리덴셜에 API 할당

화면 왼쪽 사이드바에서 서비스 설정 → 서비스 설정을 클릭하세요. 확인 대상 섹션에서 각 크리덴셜에 사용할 API를 지정하세요.

• 각 크리덴셜 옆의 드롭다운을 클릭하면 등록된 API 목록이 표시됩니다. 선택한 크리덴셜과 인증 방식이 일치하는 API만 표시됩니다.

• 얼굴, 지문, RF 카드, PIN, CLUe QR, 커스텀 QR, 각 크리덴셜에 사용할 API를 선택하세요. 크리덴셜마다 서로 다른 API를 지정할 수 있습니다.

• API를 지정하지 않은 크리덴셜은 장치 자체 인증만으로 동작합니다. 해당 크리덴셜에는 고객사 API로 검증 요청이 전송되지 않습니다. 고객사 검증이 필요 없다고 판정한 크리덴셜만 지정하지 않은 채로 두세요.

저장과 적용 규칙

크리덴셜에 등록한 API를 지정하고 수정 버튼을 클릭하면 변경 사항을 하위 공간에 적용할지 묻는 확인 대화상자가 나타납니다.

• 확인: 동일한 설정이 현재 공간 그룹의 모든 하위 공간에 즉시 적용됩니다. 기존의 공간별 재정의는 공간 그룹 값으로 덮어쓰기됩니다.

• 취소: 변경 사항을 저장하지 않습니다.

대부분 공간 그룹 레벨 설정만으로 모든 하위 공간을 동일하게 운영할 수 있습니다. 특정 공간에 다른 API를 재정의하려면 #spaceOverride를 참고하세요.

4단계 — 공간별 재정의 설정(선택 사항)

공간 그룹에서 상속받은 설정과 다르게 특정 공간에만 다른 API를 지정하는 방법을 안내합니다. 특정 공간에만 적용한 설정은 다른 공간이나 상위 공간 그룹에 영향을 주지 않습니다.

1. 공간 그룹 하위의 특정 공간으로 이동하세요.

2. 화면 왼쪽 사이드바에서 설정 → 서비스 설정을 클릭하세요.

   

3. 확인 대상 섹션의 각 크리덴셜 드롭다운에서 이 공간에만 사용할 다른 API를 선택하세요.

4. 변경 사항을 저장하려면 수정 버튼을 클릭하세요.

변경 사항은 현재 공간에만 저장됩니다. 다른 공간에는 적용되지 않습니다.

알아두기

해당 공간에 관리자로 초대된 공간 관리자만 설정 → 서비스 설정에 접근할 수 있습니다.

주의

특정 공간에 API를 지정한 이후 상위 공간 그룹에서 크리덴셜-API 지정을 변경하고 저장하면, 공간별 재정의가 공간 그룹 값으로 덮어쓰기됩니다. 공간 그룹 변경 후에도 공간별 설정을 유지해야 한다면, 공간 그룹 업데이트 이후 특정 공간의 설정 → 서비스 설정에서 다시 지정해야 합니다.

입력 규칙 요약

필드	필수 여부	규칙
커넥터 이름	필수	최대 64자
인증 방식	필수	저장 후 변경 불가
웹훅 URL	필수	https:// 필수 / 최대 512자 / CLUe는 이 URL에 HTTP POST/application/json 요청만 전송
인증 방식 API 개수	-	크리덴셜 타입당 최대 3개의 API 등록 가능
커스텀 헤더	선택 사항	Key/Value 쌍 최대 10개 / 중복 이름 불가(대소문자 구분 없음)
자동 필드	선택 사항	체크한 항목만 요청에 포함 / 키(이름)는 수정 가능 / 값은 시스템이 자동으로 채움
수동 필드	선택 사항	자동 필드와 합쳐 최대 10개 등록 / 중복 이름 불가 / 값은 지정한 타입(STRING/NUMBER/BOOLEAN)에 따라 JSON 데이터로 변환됨
사용자 Key(테스트)	인증 방식에 따라 다름	1~64자
장치 ID(테스트)	필수	9~12자리 숫자만
응답 파싱	-	statusCode 또는 성공 결과 JSONPath 중 최소 하나 필수(둘 다 입력하면 결합 검증 활성화)
statusCode	-	100~399 범위의 정수 / 최대 3개 / 중복 불가
성공 결과 JSONPath	-	1개 항목: Key + Value + 데이터 형식(BOOLEAN/STRING/NUMBER)
성공 메시지 JSONPath/실패 메시지 JSONPath	선택 사항	지정하면 응답 본문에서 추출할 키(값은 문자열이어야 하며 장치 화면 크기 고려 필요), 지정하지 않으면 장치에 메시지가 표시되지 않음
저장 조건	-	테스트에 성공해야만 저장 가능

문제 해결

출입 문제(단계별 진단)

#settingWorkflow를 참고하여 문제 영역을 좁혀 나가세요.

단계	증상	확인 사항
1	특정 크리덴셜이 인식되지 않음	크리덴셜이 장치에 등록되고 활성화되어 있는지 확인하세요.
2	장치-서버 간 통신 실패	네트워크 연결 상태, 장치 등록 상태를 확인하세요.
3	요청이 고객사 서버에 도달하지 않음	등록된 URL(HTTPS), 커스텀 헤더, 방화벽 규칙을 확인하세요.
4	고객사가 응답하지만 모든 시도가 거부됨	판정 기준(판정 모드, 성공 키/값, HTTP 상태 코드)을 확인하세요.
5	허용/거부는 올바르게 동작하지만 메시지가 표시되지 않음	성공 메시지 JSONPath/실패 메시지 JSONPath, 응답 본문의 메시지 문자열을 확인하세요.

설정 저장 버튼 비활성화

설정 저장 버튼을 클릭할 수 없다면 다음 항목을 순서대로 확인하세요.

• 필수 필드: 커넥터 이름, 인증 방식, 웹훅 URL 중 비어 있는 항목이 있는지 확인하세요.

• 웹훅 URL: https://로 시작하는지, 최대 길이(512자)를 초과하지 않는지 확인하세요.

• 수동 필드: 값을 지정한 타입(STRING/NUMBER/BOOLEAN)으로 변환할 수 있는지 확인하세요

  예: NUMBER에 숫자가 아닌 문자를 입력했을 때

• 응답 파싱: statusCode 또는 성공 결과 JSONPath 중 최소 하나를 입력했는지 확인하세요.

  • 성공 결과 JSONPath를 사용한다면 Key, Value, 데이터 형식을 모두 입력했는지 확인하세요.

  • 성공 메시지 JSONPath/실패 메시지 JSONPath는 선택 사항이며 저장에 영향을 주지 않습니다.

• API 테스트: 최소 한 번 테스트에 성공했는지 확인하세요. 테스트 성공 없이는 저장할 수 없습니다.

테스트 실패

테스트 실패는 세 가지 유형으로 나뉩니다.

• #inputValidation
• #requestFailure
• #responseMismatch

(A) 입력값 검증 단계에서 차단됨

입력값이 규칙에 맞지 않아 요청 자체가 전송되지 않습니다.

증상	확인 사항
Webhook URL 형식 오류	웹훅 URL이 https://로 시작하고 512자를 초과하지 않는지 확인하세요.
판정 기준 키 형식 오류	성공 결과 JSONPath/성공 메시지 JSONPath/실패 메시지 JSONPath가 $.로 시작하는 JSONPath 형식(최대 128자)인지 확인하세요.
판정 기준 미지정	statusCode 또는 성공 결과 JSONPath 중 최소 하나를 입력했는지 확인하세요.
성공 상태 코드 범위/개수 오류	각 값이 100~399 범위인지, 3개 이하인지, 중복이 없는지 확인하세요.
필드 키 중복	자동 필드와 수동 필드의 키가 서로 중복 없이 고유한지 확인하세요.
요청 헤더 키 중복	요청 헤더 키가 서로 중복 없이 고유한지(대소문자 구분 없음) 확인하세요.
제한된 헤더 이름 사용	Content-Type 또는 Accept를 커스텀 헤더로 추가했는지(대소문자 구분 없이 시스템 고정 값임) 확인하세요.
필드/헤더 개수 초과	자동 필드 및 수동 필드 필드 최대 10개, 커스텀 헤더 최대 10개인지 확인하세요.
인증 방식 등록 개수 초과	해당 크리덴셜 타입에 이미 3개의 API가 등록되어 있는지 확인하세요.
사용자 Key 형식 오류	테스트 콘솔의 사용자 Key가 허용된 문자(영문, 숫자, -, _, @, .) 범위와 1~64자 길이를 충족하는지 확인하세요.
장치 ID 형식 오류	테스트 콘솔의 장치 ID가 9~12자리 숫자인지 확인하세요.

(B) 요청은 전송됐지만 테스트 실패

테스트 결과가 success = false로 표시되며, 이 상태에서는 저장할 수 없습니다.

증상	확인 사항
연결 실패/네트워크 오류(고객사 서버로부터 응답을 받지 못함)	고객사 서버의 외부 접근 가능 여부, HTTPS 인증서 유효성, 방화벽/포트 설정, 커스텀 헤더(만료된 토큰, 오타)
타임아웃(응답 없음)	고객사 서버의 응답 지연, 네트워크 상태. 테스트는 몇 초 내에 응답이 없으면 실패로 처리함
응답은 받았지만 본문이 JSON이 아님	고객사가 JSON 응답을 반환하는지, 응답 Content-Type이 application/json으로 설정되어 있는지. HTML 오류 페이지, 빈 텍스트 등이 여기에 해당함

(C) 응답은 받았지만 예상한 결과가 아님

success = true와 함께 실제 HTTP 상태 코드가 statusCode에, 고객사의 원본 응답이 터미널 출력에 표시됩니다. 저장 가능하며, 이 단계에서 응답을 기준으로 응답 파싱을 구성해야 합니다.

증상	확인 사항
상태 코드는 받았지만 모든 출입이 거부됨	모드 1, 3: 성공으로 인정하는 상태 코드 목록 확인하세요. 모드 2: 본문의 키/값 조건을 확인하세요. 상태 코드는 무시됩니다.
본문 필드 조건이 일치하지 않음	성공 결과 JSONPath에 입력한 Key, Value, 데이터 형식(BOOLEAN/STRING/NUMBER)을 다시 확인하세요. 응답이 "true"(STRING)인지 true(BOOLEAN)인지 확인하세요. 타입이 일치해야 합니다.
수동 필드가 요청 본문에서 잘못된 형식으로 표시됨	수동 필드 타입(STRING/NUMBER/BOOLEAN)이 실제 입력값과 일치하는지 다시 확인하세요.

알아두기

• 테스트 API는 응답 본문을 파싱하지 않고 그대로 표시하므로, 터미널 출력에 표시된 실제 응답 JSON을 참고해 JSONPath, 키, 값 설정을 맞추세요.

• 장치 쪽에서 실패 원인을 찾아내려면 #accessTroubleshooting를 참고하세요.

이름 중복 문제

자동 필드와 수동 필드의 키 이름은 서로 중복될 수 없습니다. 요청 헤더 키도 서로 중복될 수 없습니다. 자동 필드 키 이름을 변경했다면 수동 필드와 충돌하지 않는지 확인하세요.

장치에 메시지 표시되지 않음

• 응답 본문에 성공 메시지 JSONPath 또는 실패 메시지 JSONPath로 지정한 필드가 실제로 존재하는지 확인하세요.

• 해당 키의 값이 문자열인지 확인하세요. 숫자, 객체, 배열은 표시되지 않습니다.

• 설정한 성공 메시지 JSONPath / 실패 메시지 JSONPath 이름이 실제 응답의 키와 정확히 일치하는지 확인하세요.