GMS (v2)

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

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

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

GMS API (v2)

Path variable

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

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

GMS API (v2)

POST https://gi8f5tsosp.apigw.ntruss.com/{service_id}/v2/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	메시지 고유 키
text*	string	전송 메시지
echo_to_webhook	string	사용자가 API PLEX로부터 webhook을 받을 때 함께 받을 string (최대 256 byte)
bulkId	string	요청 고유 키 (하나의 요청에 여러 개의 메세지를 보낸 경우)
smsCount	number	SMS 메세지 수 (한 목적지에 보낸 SMS 메세지 count)

200: OK 응답 반환 완료

Request Body 예시

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

Response Body

응답 http status가 200으로 return되어도 모든 요청의 정상 접수를 의미하지 않습니다.

(발송 건 별 접수 결과 코드(code 필드)로 정상 접수 여부를 확인할 수 있습니다.)

키		타입	설명
results		object array	메시지 수신 데이터
	msg_key	string	메시지 고유 키
	code	string	접수 결과 코드 (API PLEX 응답 코드 참조)
	desc	string	접수 결과 코드 상세

정상 요청(접수 성공)

{
    "results": [
        {
            "code": "C100",
            "msg_key": "user_key_1",
            "desc": "success"
        },
        {
            "code": "C341",
            "msg_key": "4b68ca16-7aa8-4a17-b74c-2b8e4adb13f8",
            "desc": "success"
        }
    ]
}

잘못된 요청 또는 에러

{
    "code": "C401_1",
    "name": "authorization fail - authorization field error",
    "description": "there is no authorization key or value in http header"
}

잘못된 list 내부 요청

{
  "results": [
        {
            "code": "G141",
            "desc": "수신번호 예외",
            "msg_key": "user_key1"
        },
        {
            "code": "C100",
            "desc": "success",
            "msg_key": "user_key2"
        }
    ]
}

API PLEX 응답 코드

code	HTTP status	설명	상세 설명
C100	200	성공
C400_1	400	잘못된 데이터 타입	response body의 description 참조
C400_2	400	잘못된 요청 파라미터	response body의 description 참조
C400_3	400	필수 파라미터 누락	response body의 description 참조
C401_1	401	header의 authorization key 누락
C401_2	401	header의 authorization value 오류	value를 ‘;’로 구분할 수 없음
C401_3	401	header의 authorization value 무효	유효한 authorization 정보를 찾을 수 없음
C404_1	404	데이터를 찾을 수 없음	response body의 description 참조
C500_1	500	서버 내부 에러	response body의 description 참조
G110	200	API UNIQUE ID 예외 (잘못된 URL)
G141	200	수신번호 예외
G142	200	잘못된 echo_to_webhook	256 byte 초과 또는 type error
G150	200	여신 부족
G160	200	1회 발송 최대 수 초과