API 레퍼런스

K-OTP 서비스 엔드포인트, 매개변수 및 응답에 대한 완전한 API 레퍼런스입니다.

기본 URL

운영환경: https://api.k-otp.dev/v1
샌드박스: https://api-sandbox.k-otp.dev/v1

인증

모든 API 요청은 Authorization 헤더에 API 키를 포함해야 합니다:

Authorization: Bearer YOUR_API_KEY

OTP 전송

SMS, 이메일 또는 음성 통화를 통해 OTP를 전송합니다.

엔드포인트

POST /send

요청 본문

{
  "to": "+8210123456789",
  "method": "sms",
  "type": "verification",
  "template": "default",
  "ttl": 300,
  "length": 6,
  "metadata": {
    "user_id": "user_123",
    "action": "login"
  }
}

매개변수

매개변수	타입	필수	설명
`to`	string	예	전화번호 (E.164) 또는 이메일 주소
`method`	string	예	전송 방법: `sms`, `email`, `voice`
`type`	string	예	OTP 유형: `verification`, `two_factor`, `password_reset`, `transaction`
`template`	string	아니오	템플릿 이름 (기본값: "default")
`ttl`	integer	아니오	유효 기간(초) (기본값: 300, 최대: 900)
`length`	integer	아니오	OTP 길이 (기본값: 6, 최소: 4, 최대: 8)
`metadata`	object	아니오	사용자 정의 메타데이터 (최대 1KB)

응답

{
  "id": "otp_1234567890abcdef",
  "to": "+8210123456789",
  "method": "sms",
  "type": "verification",
  "status": "sent",
  "created_at": "2024-01-15T10:30:00Z",
  "expires_at": "2024-01-15T10:35:00Z",
  "cost": {
    "amount": 50,
    "currency": "KRW"
  }
}

OTP 검증

사용자가 입력한 OTP 코드를 검증합니다.

엔드포인트

POST /verify

요청 본문

{
  "id": "otp_1234567890abcdef",
  "code": "123456"
}

매개변수

매개변수	타입	필수	설명
`id`	string	예	전송 응답에서 받은 OTP ID
`code`	string	예	사용자가 입력한 OTP 코드

응답

{
  "valid": true,
  "id": "otp_1234567890abcdef",
  "verified_at": "2024-01-15T10:32:00Z",
  "attempts": 1,
  "metadata": {
    "user_id": "user_123",
    "action": "login"
  }
}

상태 확인

OTP의 전송 상태를 확인합니다.

엔드포인트

GET /status/{id}

매개변수

매개변수	타입	필수	설명
`id`	string	예	전송 응답에서 받은 OTP ID

응답

{
  "id": "otp_1234567890abcdef",
  "status": "delivered",
  "to": "+8210123456789",
  "method": "sms",
  "created_at": "2024-01-15T10:30:00Z",
  "delivered_at": "2024-01-15T10:30:15Z",
  "attempts": 0,
  "verified": false,
  "carrier": "SKT",
  "country": "KR"
}

OTP 목록 조회

필터링 옵션과 함께 OTP 목록을 가져옵니다.

엔드포인트

GET /otps

쿼리 매개변수

매개변수	타입	설명
`limit`	integer	결과 수 (최대: 100, 기본값: 20)
`offset`	integer	페이지네이션 오프셋 (기본값: 0)
`method`	string	전송 방법으로 필터링
`status`	string	상태로 필터링
`from`	string	시작 날짜 (ISO 8601)
`to`	string	종료 날짜 (ISO 8601)

응답

{
  "data": [
    {
      "id": "otp_1234567890abcdef",
      "to": "+8210123456789",
      "method": "sms",
      "status": "delivered",
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "limit": 20,
    "offset": 0,
    "total": 150,
    "has_more": true
  }
}

상태 코드

상태	설명
`pending`	OTP가 처리 중입니다
`sent`	OTP가 통신사/제공업체로 전송되었습니다
`delivered`	OTP가 성공적으로 전달되었습니다
`failed`	OTP 전송이 실패했습니다
`expired`	OTP가 만료되었습니다
`verified`	OTP가 성공적으로 검증되었습니다

오류 응답

모든 오류는 다음 형식을 따릅니다:

{
  "error": {
    "code": "INVALID_PHONE",
    "message": "전화번호 형식이 올바르지 않습니다",
    "details": {
      "field": "to",
      "value": "123456"
    }
  }
}

일반적인 오류 코드

코드	HTTP 상태	설명
`INVALID_API_KEY`	401	API 키가 누락되었거나 올바르지 않습니다
`INSUFFICIENT_CREDITS`	402	계정에 크레딧이 부족합니다
`RATE_LIMITED`	429	속도 제한을 초과했습니다
`INVALID_PHONE`	400	전화번호 형식이 올바르지 않습니다
`INVALID_EMAIL`	400	이메일 주소 형식이 올바르지 않습니다
`OTP_NOT_FOUND`	404	OTP ID를 찾을 수 없습니다
`OTP_EXPIRED`	400	OTP가 만료되었습니다
`INVALID_CODE`	400	OTP 코드가 올바르지 않습니다
`MAX_ATTEMPTS`	400	최대 검증 시도 횟수에 도달했습니다

속도 제한

OTP 전송: 전화/이메일당 분당 10회 요청
OTP 검증: OTP당 5회 시도
API 호출: API 키당 분당 1000회 요청

모든 응답에 속도 제한 헤더가 포함됩니다:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1642248600

웹훅

OTP 이벤트에 대한 실시간 알림을 받으려면 웹훅을 구성하세요. 자세한 내용은 웹훅을 참조하세요.

SDK 및 라이브러리

JavaScript/Node.js: npm install @k-otp/sdk
Python: pip install k-otp
PHP: composer require k-otp/sdk
Go: go get github.com/k-otp/go-sdk
Java: Maven/Gradle 사용 가능

API 레퍼런스

On this page