채널과 SMS 대체 발송
인증번호는 카카오 알림톡으로 발송되며, SMS 대체 발송은 기본으로 켜져 있고 요청마다 끌 수 있습니다. 템플릿과 과금도 함께 설명합니다.
K-OTP는 인증번호를 카카오 알림톡으로 보냅니다. 알림톡이 전달되지 않으면 같은 인증번호를 SMS로 자동 대체 발송합니다. 이 SMS 대체 발송은 기본으로 켜져 있으며, 요청마다 smsFallback: false로 끌 수 있습니다.
대부분은 요청에서 channel을 생략하면 됩니다. 메시지 본문은 등록된 템플릿을 사용합니다. 채널과 템플릿을 참고하세요.
채널이 정해지는 방식
| 요청 | 발송 |
|---|---|
channel 생략(또는 "alimtalk") | 알림톡, 끄지 않았다면 SMS 대체 발송 포함 |
channel: "sms" | 400 BAD_REQUEST(CHANNEL_NOT_SUPPORTED)로 거절, 발송하지 않음 |
승인된 카카오톡 템플릿이 있는 템플릿만 발급할 수 있습니다. 네 가지 템플릿이 모두 승인되어 있습니다.
templateId | 채널 |
|---|---|
otp_default_kr (기본) | 알림톡(SMS 대체 발송 포함) |
otp_login_kr | 알림톡(SMS 대체 발송 포함) |
otp_signup_kr | 알림톡(SMS 대체 발송 포함) |
otp_payment_kr | 알림톡(SMS 대체 발송 포함) |
GET /v1/templates는 템플릿마다 channelSupport를 돌려주며, alimtalk가 포함된 템플릿만 발급할 수 있습니다. 그렇지 않은 템플릿으로 발급하면 400 BAD_REQUEST(TEMPLATE_NOT_AVAILABLE)로 거절되며, K-OTP는 SMS로 직접 발송하지 않습니다. 대체 발송으로 전달된 경우 발송 기록과 응답에는 여전히 전달 채널이 sms로 표시됩니다.
메시지에 앱의 서비스명을 표시하려면 메시지 템플릿과 서비스명을 참고하세요.
알림톡
승인된 카카오톡 비즈니스 템플릿으로 발송됩니다. 카카오톡으로 도착하므로 보통 SMS보다 빨리 확인됩니다.
SMS 대체 발송 (기본 켜짐)
알림톡 발송에 실패하면(예: 수신자가 카카오톡을 쓰지 않거나 메시지가 반려된 경우) K-OTP가 같은 인증번호를 SMS로 자동 발송합니다. API를 다시 호출할 필요가 없고 issueId도 그대로이므로 검증 방법은 달라지지 않습니다.
SMS 대체 발송 끄기 (API 1.8.0)
POST /v1/issue에 smsFallback: false를 넣으면 알림톡으로만 발송합니다.
smsFallback | 동작 |
|---|---|
생략 또는 true | 알림톡 + SMS 대체 발송(기본값) |
false | 알림톡만: 알림톡이 실패해도 SMS를 보내지 않음 |
curl -X POST "https://api.k-otp.dev/v1/issue" \
-H "Authorization: Bearer $KOTP_SECRET_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 5b0f8f2e-3c1d-4d7a-9a2b-6f1e0c9d8a71" \
-d '{"phoneNumber":"01012345678","purpose":"login","smsFallback":false}'알아 둘 점:
- 대체 발송을 끄면 알림톡이 도달하지 못한 수신자는 인증번호를 받지 못합니다. 발송사가 실패를 알려 오면
deliveryStatus가failed가 됩니다(발급 수명주기 참고). - 가격은 같습니다. 끄든 켜든 발송 1건에 1 크레딧입니다(과금 참고). 대체 발송을 끈 상태에서 발송사가 거절한 알림톡 요청은 예약이 해제되고, 접수된 요청은 차감되며, 이후 발송사가 전달 실패를 확정하면 차감된 크레딧이 돌아옵니다(차감 흐름 참고).
smsFallback도 요청의 일부이므로, 같은 멱등 키로 재시도할 때는 같은 값을 보내세요.- SDK에서는
@k-otp/sdk1.2.0과 0.1.0 서버 SDK부터smsFallback을 보낼 수 있습니다. 그보다 오래된@k-otp/sdk라면 위처럼 REST API로 보내세요.
과금
OTP 발송 1건은 1 크레딧입니다.
- 알림톡: 알림톡으로 전달되든 SMS 대체 발송으로 전달되든 1 크레딧이며, 대체 발송에 추가 차감은 없습니다.
smsFallback: false인 알림톡: 똑같이 1 크레딧입니다.
크레딧은 발급 시 예약되고, 메시징 발송사가 발송을 접수하면 차감되며, 발송사가 거절하면 해제됩니다. 접수 후 발송사가 전달 실패를 확정하거나 추적 기간 안에 전달 결과가 오지 않으면 차감된 크레딧이 돌아옵니다. 차감 흐름을 참고하세요.
발송 상태
GET /v1/status는 검증 상태와 발송 상태를 하나의 overallStatus로 합쳐 보여 주므로, 고객 지원 팀이 인증번호가 대기·발송·도달·검증 중 어느 단계인지 확인할 수 있습니다.