점유인증코드 요청

이 문서는 SMS 또는 Email 로 이용자에게 점유인증코드를 발송하는 API 사용 방법을 설명합니다.
점유인증은 아래 2개의 API 로 제공됩니다.

점유인증코드 요청 (본 문서)
점유인증코드 확인

연동 방법과 개발 흐름은 본인 확인 서비스 가이드를 참고해 주십시오.

점유인증코드 요청 API

인증 대상(휴대폰 번호 또는 이메일 주소)으로 인증코드를 발송합니다. 인증코드 자릿수는 채널에 따라 다릅니다. (SMS 6자리 / Email 4자리)

주의사항

본 API 사용 전 사업 담당자와 사전 협의가 필요합니다.
채널(sms / email) 지원 여부는 게임별로 결정됩니다. 등록되지 않은 채널로 요청하면 70115 를 응답합니다.
인증 유효 시간은 API 호출 시점부터 SMS 3분 / Email 10분 입니다.
동일 게임 · 동일 대상 재발송 제한 (최초 요청 시각 기준)
SMS: 1분 3회 + 1일 20회
Email: 1시간 5회
동일 대상으로 여러 번 요청한 경우, 발송된 인증코드는 유효 시간 만료 전까지 모두 유효합니다.
- 1개 인증코드라도 인증에 성공하면 해당 대상의 모든 인증코드는 만료됩니다.
본 API 는 5초 타임아웃 값을 사용합니다.
HTTP Status 408(Request Timeout), 504(Gateway Timeout) 응답 시 지수 백오프 전략(재시도할 때마다 대기 시간을 지수적으로 증가 - 1, 2, 4, 8 ...)을 통한 재시도 처리를 해 주십시오.

발송 문구 안내

이용자에게 실제 전달되는 SMS 문구와 Email 템플릿은 문서 하단 발송 템플릿 을 참고해 주십시오.
문구와 템플릿은 변경될 수 있습니다.

기본정보

POST /sms-sender/v3.2/occupancy_auth/send_code
Host:
   https://api.gate8.com (SANDBOX)
   https://api.onstove.com (LIVE)
Content-Type: application/json

Request

Header

Name	Type	Required	Default Value	Example	Description
Authorization	String	Y	-	Bearer	플랫폼 API 액세스 토큰(API AccessToken)[인증(토큰·검증) → Server] - 게임(service) 식별은 토큰의 `sid` 에서 도출됩니다. - 공식 홈페이지 등 웹 사용처도 해당 토큰을 발급받아 사용합니다.
Content-Type	String	Y	-	application/json	리소스 media type
caller-id	String	Y	-	STOVE_GAME_ID	API 호출자 정보 - 파트너스에 등록한 Game ID * 게임(service) 식별용이 아닌 모니터링 / 호출자 식별용
caller-detail	String	N	-	f248a284-7e61-4dcf-a111-a394050e9555	UUID(API 호출시 마다 변경, 호출 모니터링용)

Body

Name	Type	Required	Default Value	Example	Description
channel	String	Y	-	sms	인증 채널 - `sms` : 휴대폰(문자) 점유인증 - `email` : 이메일 점유인증
to	String	Y	-	+821012345678	인증 대상 (`channel` 에 따라 형식 결정) - `channel=sms` : 휴대폰 번호 (E.164 형식, `+` 와 국가코드 포함) - 한국 휴대폰 번호의 '0' 오입력 시 자동 보정 (+8201012345678 → +821012345678) - `channel=email` : 이메일 주소 (예: user@example.com)
locale	String	N	en	ko	(`channel=email` 전용) 발송 언어 - `ko` : 국문 / `en` : 영문 - 미지정 시 기본값 `en` - 현재 `ko` / `en` 2개 언어만 지원하며, 그 외 값은 `en` 으로 대체 (지원 언어는 추후 확장) - `channel=sms` 는 번호의 국가코드 기준으로 언어가 자동 결정되어 `locale` 이 무시됨

Response

Body

Name	Type	Required	Default Value	Example	Description
code	Integer	Y	-	0	응답 코드
message	String	Y	-	OK	응답 메시지
value	Object	N	-	-	응답 데이터

Value

Name	Type	Required	Default Value	Example	Description
channel	String	Y	-	email	발송 채널 (요청한 `channel` 반영)
code_length	Integer	Y	-	4	인증코드 자릿수 (`sms` = 6, `email` = 4)
expires_in	Integer	Y	-	600	인증코드 유효 시간(초) (`sms` = 180, `email` = 600)

Sample

Request

// 점유인증코드 요청
curl -L -X POST 'https://api.onstove.com/sms-sender/v3.2/occupancy_auth/send_code' \
-H 'Content-Type: application/json' \
-H "Caller-Id: {{caller-id}}" \
-H 'Caller-Detail: f248a284-7e61-4dcf-a111-a394050e9555' \
-H 'Authorization: Bearer {{API accessToken}}' \
-d '{
    "channel":"email",
    "to":"user@example.com",
    "locale":"ko"
}'

Response

// 성공 - sms
{
    "code": 0,
    "message": "OK",
    "value": {
        "channel": "sms",
        "code_length": 6,
        "expires_in": 180
    }
}

// 성공 - email
{
    "code": 0,
    "message": "OK",
    "value": {
        "channel": "email",
        "code_length": 4,
        "expires_in": 600
    }
}

// 실패 - 파라미터 오류
{
    "code": 70100,
    "message": "invalid parameter"
}

Return Code

API 오류는 서버단에서 확인 및 처리 해 주십시오

프론트는 성공 or 인증실패 만 노출 처리

HTTP Status code	Code	Message	Description	대응 주체
200	0	OK	성공 (발송 요청 접수)	API 호출자 (서버)
200	70100	invalid parameter	입력 파라미터 오류 - 입력 파라미터 확인 및 수정	API 호출자 (서버)
200	70101	too many requests	재발송 제한 초과 - `channel=sms` : 최초 요청 시각으로부터 1분 이내 3회 초과 - `channel=email` : 최초 요청 시각으로부터 1시간 이내 5회 초과 - 이용자에게 일정 시간 경과 후 재시도 안내	end user
200	70105	too many requests	요청 제한 초과(1일), `channel=sms` 전용 - 최초 요청 시각으로부터 24시간 이내 20회 초과 호출한 경우 응답 - 이용자에게 24시간 이후 재시도 안내	end user
200	70107	unsupported country	지원하지 않는 국가 (`channel=sms`) - 지원 국가는 점유인증 지원 국가 참고	end user
200	70108	service not registered	미등록 / 미지원 서비스 (게임 미등록)	플랫폼 담당자
200	70109	policy not registered	미등록 정책	플랫폼 담당자
200	70110	invalid phone number format	전화번호 형식 오류 (`channel=sms`)	API 호출자 (서버)
200	70115	unsupported channel	미지원 / 미운영 channel - 게임이 지원하지 않는 채널 포함	API 호출자 (서버)
200	70116	invalid email format	이메일 형식 오류 (`channel=email`)	API 호출자 (서버)
200	70199	internal server error	내부 서버 오류 - 플랫폼 담당자 문의	플랫폼 담당자
401	40100 40101 40102 40103 40104 40106 40302 50000	-	토큰 공통 오류 - 플랫폼 인증 토큰(API AccessToken) 확인 및 수정	API 호출자 (서버)
408	40800	-	Request Timeout - API 호출 재시도 처리	API 호출자 (서버)
429	42900	-	Too Many Requests - API 호출 재시도 처리	API 호출자 (서버)
504	50400	-	Gateway Timeout - API 호출 재시도 처리	API 호출자 (서버)

점유인증 지원 국가

channel=sms 로 요청할 때 아래 국가로만 발송할 수 있습니다.

No	국가명	국가 번호(ITU)	국가코드(ISO 3166-1 Alpha-2)	비고
1	한국	+82	KR
2	대만	+886	TW
3	홍콩	+852	HK
4	마카오	+853	MO
5	일본	+81	JP
6	태국	+66	TH
7	필리핀	+63	PH
8	싱가포르	+65	SG
9	인도네시아	+62	ID
10	말레이시아	+60	MY	문자에 "RM0" 추가됨 (말레이시아 통신사 요구정책)
11	호주	+61	AU
12	스페인	+34	ES
13	캄보디아	+855	KH
14	엘살바도르	+503	SV
15	나이지리아	+234	NG
16	남아공	+27	ZA
17	미얀마	+95	MM
18	라오스	+856	LA

안내

위 표는 플랫폼이 지원하는 전체 국가 목록입니다.
실제 발송 가능 국가는 게임별로 다르게 등록되므로, 사용할 국가는 사전에 사업 담당자와 협의해 주십시오.
등록되지 않은 국가로 요청하면 70107 을 응답합니다.

발송 템플릿

이용자에게 실제로 전달되는 문구와 메일 형식입니다. 문구와 템플릿은 변경될 수 있습니다.

SMS 문구

유효 시간은 3분이며, 발송 언어는 번호의 국가코드 기준으로 자동 결정됩니다. (한국 = 국문 / 그 외 = 영문)

언어	문구
국문	(게임명) 인증번호 XXXXXX 를 입력해 주세요. 유효시간은 3분입니다.
영문	(GAME) Enter verification code XXXXXX. This code expires in 3 minutes.

Email 템플릿

유효 시간은 10분이며, 발송 언어는 locale 값(ko / en)으로 결정됩니다.

항목	내용
발송자	`STOVE <noreply@smilegate.com>`
제목	국문 : 스토브 인증 메일 안내 영문 : STOVE Verification Email Guide
헤더	STOVE (링크 : https://www.onstove.com)
본문	인증코드 4자리 안내 - 국문 : 아래 인증 번호를 입력하면 인증이 완료됩니다. (유효시간 : 10분) / 인증번호 : XXXX - 영문 : Enter the verification code below to complete verification. (valid: 10 minutes) / Verification number: XXXX
풋터	Smilegate (링크 : https://www.onstove.com) 고객센터 (링크 : https://cs.onstove.com)

이메일 샘플(국문)

이용자가 메일을 받지 못했다고 문의하면 스팸함 확인을 먼저 안내해 주십시오.