SMS

한글기준 45자(90byte) 내외의 단문 메시지를 보낼 수 있는 메시징 API

SMS API

서비스를 이용하시려면 [서비스 콘솔 / 발신번호]에서 발신번호 등록을 수행해야 합니다.

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

사용 전 체크 사항

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

문자메시지는 euc-kr 로 처리되기 때문에 euc-kr 표현 범위를 벗어난 문자는 사용이 불가능합니다.

비밀키(secret_key)는 [서비스 콘솔 / Sub Account]에서 Sub Account 추가 후 [상세조회] 버튼을 클릭하여 확인할 수 있습니다.

Path variable

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

code	설명
service_id	서비스 유형 id sms-standard : 스탠다드 SMS sms-bulk : 대량 SMS sms-finance : 금융 SMS sms-verify : 인증 SMS

SMS 전송 API

POST https://0afupd5dlt.apigw.ntruss.com/{service_id}/v2/send

Headers

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

Request Body

Name	Type	Description
msg_data*	object array	메시지 발송 상세 데이터 (최대 10건)
msg_key	string	사용자가 관리하는 메시지 고유 키 (null 또는 공백일 경우 자동 부여)
sender_number*	string	발신자 전화번호 (등록된 발신번호)
origin_cid	string	최초 발신 사업자 코드 (특수한 유형의 부가 통신 사업자인 경우 사업자 코드 숫자 9자리를 입력) (최대 10 byte)
receiver_number*	string	수신자 휴대폰 번호
msg*	string	전송 메시지 (euc-kr로 문자셋 형 변환 후 90 byte 초과시 실패 처리)
echo_to_webhook	string	사용자가 API PLEX로부터 webhook을 받을 때 함께 받을 string (최대 256 byte)

200: OK 응답 반환 완료

Request Body 예시

{
    "msg_data": [
        {
            "msg_key": "user_key_1",
            "sender_number": "010xxxxxxxx",
            "receiver_number": "010xxxxxxxx",
            "msg": "test message 1"
        },
        {
            "sender_number": "010xxxxxxxx",
            "receiver_number": "010xxxxxxxx",
            "origin_cid": "0123456789",
            "msg": "test message 2",
            "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": "G140",
            "desc": "발신번호 예외",
            "msg_key": "user_key_1"
        },
        {
            "code": "G141",
            "desc": "수신번호 예외",
            "msg_key": "4b68ca16-7aa8-4a17-b74c-2b8e4adb13f8"
        }
    ]
}

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)
G140	200	발신번호 예외
G141	200	수신번호 예외
G142	200	잘못된 echo_to_webhook	256 byte 초과 또는 type error
G150	200	여신 부족
G160	200	1회 발송 최대 수 초과