점유인증코드 확인

이 문서는 SMS 또는 Email 로 발송된 점유인증코드가 유효한지 확인하는 API 사용 방법을 설명합니다.
점유인증은 아래 2개의 API 로 제공됩니다.

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

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

점유인증코드 확인 API

점유인증코드 요청 API 로 발송한 인증코드를 이용자가 올바르게 입력했는지 확인합니다. 인증에 성공하면 인증 대상을 식별하는 possession_key 를 응답합니다.

주의사항

본 API 사용 전 사업 담당자와 사전 협의가 필요합니다.
인증 유효 시간은 요청 API 호출 시점부터 SMS 3분 / Email 10분 입니다.
동일 대상으로 여러 번 요청한 경우, 발송된 인증코드는 유효 시간 만료 전까지 모두 유효합니다.
- 1개 인증코드라도 인증에 성공하면 해당 대상의 모든 인증코드는 만료됩니다.
오입력 제한 (SMS · Email 공통) : 게임별 동일 대상(휴대폰 번호 / 이메일) 기준으로 인증코드를 5회 잘못 입력하면 해당 대상의 인증코드가 전체 무효화됩니다.
- 1회라도 인증에 성공하면 실패 횟수는 초기화됩니다.
- 인증코드를 재발송(요청 API 재호출)하면 실패 횟수가 초기화됩니다. (새 인증코드에 새 시도 횟수 부여)
- 전체 무효화 이후의 확인 요청은 70104(발급된 인증코드 없음)로 응답되므로, 이용자에게 재발송을 안내해 주십시오.
본 API 는 5초 타임아웃 값을 사용합니다.
HTTP Status 408(Request Timeout), 504(Gateway Timeout) 응답 시 지수 백오프 전략(재시도할 때마다 대기 시간을 지수적으로 증가 - 1, 2, 4, 8 ...)을 통한 재시도 처리를 해 주십시오.

점유인증 코드 확인 API 호출 시, verification_code 값이 비어 있는 경우 API 가 호출되지 않도록 입력 값 검증 로직이 꼭 추가되어야 합니다.

기본정보

POST /sms-sender/v3.2/occupancy_auth/verify_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) * 인증코드를 요청한 대상과 동일한 값 입력
verification_code	String	Y	-	123456	이용자가 입력한 인증코드 (`sms` 6자리 / `email` 4자리 숫자) - SMS 또는 Email 을 통해 전달된 인증코드

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
possession_key	String	Y	-	SxrotG1lF454irWaWn0bIu7W4N/XRFM9	인증 구분 키, 인증코드 확인 성공 시 전달 - 동일 대상(휴대폰 번호 / 이메일)으로 요청하면 동일한 키 값을 응답 - 채널(`sms` / `email`)이 다르면 키 값도 다름

Sample

Request

// 점유인증코드 확인
curl -L -X POST 'https://api.onstove.com/sms-sender/v3.2/occupancy_auth/verify_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":"sms",
    "to":"+821012345678",
    "verification_code":"123456"
}'

Response

// 성공
{
    "code": 0,
    "message": "OK",
    "value": {
        "possession_key": "SxrotG1lF454irWaWn0bIu7W4N/XRFM9"
    }
}

// 실패 - 인증코드 불일치
{
    "code": 70103,
    "message": "verification fail"
}

// 실패 - 발급된 인증코드 없음 (만료 / 미발급 / 5회 오입력으로 무효화)
{
    "code": 70104,
    "message": "no verification code"
}

Return Code

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

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

HTTP Status code	Code	Message	Description	대응 주체
200	0	OK	성공	API 호출자 (서버)
200	70100	invalid parameter	입력 파라미터 오류 - 입력 파라미터 확인 및 수정	API 호출자 (서버)
200	70103	verification fail	인증코드 불일치 - 입력된 인증코드가 저장된 인증코드와 일치하지 않는 경우 응답 - 이용자 인증코드 재입력 처리 (유효 시간 내 재시도 가능, 5회 도달 시 무효화)	end user
200	70104	no verification code	발급된 인증코드 없음, 재발급 필요 - 인증코드 만료 / 미발급, 또는 5회 오입력으로 전체 무효화된 경우 응답 - 이용자에게 인증코드 재발송(재요청) 안내 처리	end user
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 호출자 (서버)
504	50400	-	Gateway Timeout - API 호출 재시도 처리	API 호출자 (서버)

possession_key 사용 시 주의사항

possession_key 는 인증 대상의 중복 여부를 판단하는 용도로 사용할 수 있는 값이며, 사용 여부는 선택사항입니다.
개인정보의 대상이 될 수 있는 값이므로, 개인정보 관리정책에 따라 관리해 주십시오.