CHeKT Developers

API 키는 어떻게 발급받나요?

API 키는 다음 단계를 통해 발급받을 수 있습니다:

CHeKT 개발자 포털에 로그인합니다.
대시보드에서 "API 키 관리" 섹션으로 이동합니다.
"새 API 키 생성" 버튼을 클릭합니다.
OAuth 2.0 Client Credentials를 받게 됩니다.

중요: API 키는 한 번만 표시되므로 안전한 곳에 보관하세요.

OAuth 2.0 인증은 어떻게 작동하나요?

CHeKT API는 OAuth 2.0 Client Credentials Grant 방식을 사용합니다:

Client ID와 Client Secret으로 토큰 엔드포인트에 요청합니다.
Access Token을 받게 됩니다.
API 요청 시 Authorization 헤더에 토큰을 포함합니다: Authorization: Bearer {token}
토큰은 일정 시간 후 만료되므로 새로 발급받아야 합니다.

자세한 내용은 인증 문서를 참고하세요.

API 요청 제한(Rate Limit)이 있나요?

네, API 요청 제한이 있습니다:

기본 제한: 분당 100회 요청
시간당 제한: 시간당 5,000회 요청
일일 제한: 일일 100,000회 요청

응답 헤더에서 현재 사용량을 확인할 수 있습니다:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 99
X-RateLimit-Reset: 1234567890

제한을 초과하면 429 Too Many Requests 에러가 반환됩니다.

배치(Batch) API는 어떻게 사용하나요?

배치 API를 사용하면 여러 리소스를 한 번에 생성하거나 수정할 수 있습니다:

배치 엔드포인트에 요청합니다 (예: POST /api/devices/batch)
요청 본문에 배열 형식으로 여러 항목을 포함합니다
각 항목은 개별 API 요청과 동일한 스키마를 따릅니다

예시:

{
  "devices": [
    { "name": "Device 1", "type": "camera" },
    { "name": "Device 2", "type": "sensor" }
  ]
}

제한사항: 한 번에 최대 100개 항목까지 처리할 수 있습니다.

딜러 연결은 어떻게 하나요?

딜러 연결은 다음 단계로 진행됩니다:

POST /partner/v1/dealers/connect 엔드포인트를 호출합니다.
필수 정보를 포함합니다:
- 회사명
- 연락처 정보
- 비즈니스 등록 번호
요청이 승인되면 dealer_id를 받게 됩니다.
이후 해당 dealer_id로 사이트와 디바이스를 관리할 수 있습니다.

참고: 딜러 연결 요청은 승인 프로세스를 거쳐야 합니다.

웹훅(Webhook) 설정 방법이 궁금합니다.

웹훅을 설정하여 실시간 이벤트를 수신할 수 있습니다:

웹훅을 받을 엔드포인트 URL을 준비합니다.
POST /api/webhooks로 웹훅을 등록합니다.
이벤트 타입을 선택합니다 (예: device.created, alarm.triggered).
서명 검증을 위한 시크릿 키를 설정합니다.

보안: 모든 웹훅 요청은 HMAC SHA-256 서명과 함께 전송됩니다.

X-Webhook-Signature: sha256=abcdef123456...

401 Unauthorized 에러가 발생합니다.

401 에러는 인증 문제를 나타냅니다. 다음을 확인하세요:

토큰 만료: Access Token이 만료되었을 수 있습니다. 새로 발급받으세요.
잘못된 토큰: Authorization 헤더 형식이 올바른지 확인하세요: Bearer {token}
API 키 문제: Client ID와 Secret이 올바른지 확인하세요.
권한 부족: 해당 리소스에 접근 권한이 있는지 확인하세요.

문제가 지속되면 기술 지원팀에 문의해주세요.

400 Bad Request 에러의 원인이 무엇인가요?

400 에러는 잘못된 요청을 나타냅니다. 주요 원인:

누락된 필수 필드: 요청 본문에 필수 필드가 없는지 확인하세요.
잘못된 데이터 형식: JSON 형식이 올바른지, 데이터 타입이 일치하는지 확인하세요.
유효성 검증 실패: 이메일, 전화번호 등의 형식이 올바른지 확인하세요.
잘못된 값: enum 값이나 범위가 허용된 값인지 확인하세요.

에러 응답에 포함된 상세 메시지를 확인하면 구체적인 문제를 파악할 수 있습니다.

쿼리 스트링 필터링은 어떻게 사용하나요?

쿼리 스트링을 사용하여 데이터를 필터링할 수 있습니다:

fields: 조회할 필드 지정
filter: 조건부 필터링
sort: 정렬
limit: 결과 수 제한

예시:

GET /api/devices?fields=name,status&filter=status,active,eq&sort=created_at&limit=10

지원되는 필터 연산자: eq, neq, lt, lte, gt, gte, regex

자세한 내용은 쿼리 스트링 문서를 참고하세요.

API 응답 속도가 느립니다. 어떻게 개선할 수 있나요?

API 성능을 개선하는 방법:

필드 선택: fields 파라미터로 필요한 필드만 요청하세요.
페이지네이션: limit과 offset을 사용하여 데이터를 나눠 받으세요.
캐싱: 자주 변경되지 않는 데이터는 클라이언트 측에서 캐싱하세요.
배치 API: 여러 요청을 하나로 묶어서 보내세요.
압축: Accept-Encoding: gzip 헤더를 사용하세요.

지속적인 성능 문제가 있다면 기술 지원팀에 문의해주세요.

FAQ