GMS (v1)

국내에서 다른 나라로 GMS 메세지를 전송하는 API입니다.

캐릭터 인코딩은 UTF-8 을 기본으로 합니다.

이 API는 메세지 발송 결과(WebHook)으로 결과를 전달할 수 있습니다.

GMS API (v1) (deprecated on 2023.12.31)

Path variable

Path variable(각 URI 내 괄호({}) 로 묶인 경로 변수)는 아래 내용을 참고하여 호출 시 누락되지 않도록 해주세요.

code	설명
service_id	서비스 유형 id 국내 → 글로벌 : gms-kg 글로벌 → 글로벌 : gms-gg 글로벌 → 국내 : gms-gk

GMS API (v1)

POST https://gi8f5tsosp.apigw.ntruss.com/{service_id}/v1/send

국가 코드에 따라서 SMS 메세지를 발송합니다. 메시지는 international format (예: 41793026727)으로 작성된 유효한 전화 번호로만 전송됩니다. E.164 번호 형식을 사용하는 것이 좋습니다. E.164 번호는 최대 15자리의 길이에 맞춰 국제적으로 표준화되어 있습니다. 주로 전화 번호 앞에 + (더하기 기호)가 붙고, 그 뒤로 국가 코드, 네트워크 코드 및 가입자 번호가 이어집니다. 핸드셋이나 네트워크에 따라 E.164 형식이 아닌 전화 번호도 작동할 수 있습니다.

Headers

Name	Type	Description
Authorization*	string	사용자ID;secret_key
Content-Type*	string	application/json;charset=utf-8

Request Body

Name	Type	Description
messages*	object	메시지 발송 상세 데이터 (최대 10건)
from*	string	SMS 메시지의 발신자 (영문자:3~13, 숫자 3~14) 별도 sender를 사용하지 않는 경우 “ONSMS”로 고정하여 사용
to*	string	수신자 전화번호 international format으로 되어 있어야 합니다. (EX : 41793026727)
messageId*	string	메시지 고유 키 (발송 시 unique 하게 설정 하여 발송)
text*	string	전송 메시지

200: OK 응답 반환 완료

Request Body 예시

{
    "messages": [
        {
            "from": "ONSMS",
            "to": "+8210xxxxxxxx",
            "text": "gms-kg-2 test 01",
            "messageId": "user_key1"
        }
    ]
}

Response Body

키				설명
messages			object array	메시지 수신 데이터
	to		string	메시지 수신자
	smsCount		number	SMS 메시지 수 (한 목적지에 보낸 SMS 메시지 count)
	messageId		string	메시지 고유 키 (전송시 값)
	status		object	메시지 상태
		id	number	status id (메시지 상태 코드 참조)
		groupId	number	status group id (메시지 상태 코드 참조)
		groupName	string	status group name
		description	string	상태 메시지

정상 요청(접수 성공)

{
    "messages": [
        {
            "to": "string",
            "status": {
                "id": "number",
                "groupId": "number",
                "groupName": "string",
                "name": "string",
                "description": "string"
            },
            "smsCount": "number",
            "messageId": "string"
        }
    ]
}

잘못된 요청 또는 에러

{
    "code": "G210", //Gateway 오류 코드 참조
    "desc": "요청 JSON 변환중 오류가 발생했습니다."
}

잘못된 list 내부 요청

{
    "results": [
        {
            "code": "C341",
            "msg_key": "2022060900001",
            "desc": "MsgLengthOver"
        },
        {
            "code": "C341",
            "msg_key": "2022060900002",
            "desc": "MsgLengthOver"
        }
    ]
}

GATEWAY 오류 코드

CODE	설명
G120	사용자 정보 오류
G210	요청 JSON 파싱 오류
G220	요청 JSON 파싱 오류-서비스 키 없음
G250	응답 JSON오류
G260	WEBHOOK JSON 처리 오류
G310	여신 차감 실패
G410	Legacy 서비스 호출 오류
G420	고객 callback 호출 오류
G430	고객 callback URL 없음
G900	Gateway 시스템 오류
G910	Gateway 시스템 오류(요청서비스 조회 실패)
G920	Gateway 시스템 오류(서비스 요청 결과 처리 오류)