Overview
REST API 1.0 에 비해 달라진 점은 아래와 같습니다.
1만건 메시지 전송을 2분에서 20초 이하로 단축.
이 문서는 쿨에스엠에스의 REST API를 통하여 문자전송에서부터 전송된 문자의 상태값을 비롯하여 잔액정보 및 예약취소 등의 작업을 요청하는 방법을 기술하고 있습니다. REST API를 기반으로 PHP, Java, Python, Delphi, C 등 다양한 언어로 구현된 SDK 및 예제를 SDK 에서 확인하세요.
모든 Request 호출에는 API Key를 비롯한 인증정보를 포함하여 서버의 인증을 거쳐야 합니다. 인증에 대한 상세한 내용은 Authentication 을 확인하세요.
인증을 위한 API Key 및 API Secret 코드는 문자메시지 > 환경설정 > API Key 관리 메뉴에서 발급 및 관리가 가능합니다. API Key 관리 문서를 참고하세요.
아래는 Resource Url과 간단한 설명을 테이블로 정리하였습니다. 상세한 설명을 보시려면 해당 Resource Url을 클릭하여 주세요.
※ Request Parameters 입력시 JSON 포맷의 데이터가 아니라 폼데이터임을 유의해 주세요. Response Body의 데이터가 JSON 형식입니다.
요청에 대한 응답의 상세는 Response 를 확인하세요.
REST API 관련 질의 응답 및 정보 공유는 개발자포럼 을 이용해주세요.
Change Log
POST send
문자메시지를 전송 요청합니다. 전송 요청에 대한 Response는 휴대전화까지 전송된 결과가 아닙니다.
Resource URL
https://api.coolsms.co.kr/sms/1.5/send
Parameters
Mandatory가 Ο 인 필드는 반드시 입력하여야 합니다.
srk 는 앱아이디를 말하는 것으로 https://www.coolsms.co.kr/my_app_list 을 참고하세요.
type, to, from, text, subject 등의 필드값을 개별적으로 다른 값으로 발송하고자 할 때 JSON형식으로 extension 포맷을 사용할 수 있습니다.
한번의 Request에 extension을 포함하여 총 받는사람(to) 수는 1000개 까지가 제한이며 1000개가 넘을 경우 오류를 발생시킵니다. (RecipientsTooMany)
한번의 Request의 총 크기는 2MB를 넘을 수 없습니다. (오류코드 미정)
extension 포맷
Copy [
{
"type": "SMS",
"to": "01000000000,01011111111,01022222222",
"text": "Hello A"
},
{
"type": "LMS",
"to": "01000000000,01011111111,01022222222",
"subject": "LMS Subject",
"text": "Hello B"
},
{
"type": "MMS",
"to": "01000000000,01011111111,01022222222",
"subject": "MMS Subject",
"text": "Hello C",
}
] type, country, to, from, datetime, text, subject, delay 가 올 수 있고 입력하지 않는 필드는 상위(기본 필드) 값을 상속 받아 사용됩니다. 단, to는 상속받지 아니하고 필수 입력 사항입니다.
발송형태에 따른 제한사항
이동통신사 내부적으로 완성형한글로 변환되므로 영어 1바이트, 한글 2바이트로 취급됩니다.
Example
Copy <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<?php
$api_key = 'NCS52A57F48C3D32';
$api_secret = '5AC44E03CE8E7212D9D1AD9091FA9966';
$timestamp = time();
$salt = uniqid();
$data = strval($timestamp) . $salt;
$signature = hash_hmac('md5', $data, $api_secret);
?>
<html lang="ko" xml:lang="ko" xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
</head>
<body>
<form method="post" action="https://api.coolsms.co.kr/sms/1.5/send" enctype="multipart/form-data">
API Key: <input type="text" name="api_key" value="<?php echo $api_key ?>" /><br />
Timestame: <input type="text" name="timestamp" value="<?php echo $timestamp ?>" /><br />
Salt: <input type="text" name="salt" value="<?php echo $salt ?>" /><br />
Signature: <input type="text" name="signature" value="<?php echo $signature ?>" /><br />
To: <input type="text" name="to" value="01000000000" /><br />
From: <input type="text" name="from" value="01000000000" /><br />
Subject: <input type="text" name="subject" value="TEST" /><br />
Text: <textarea name="text">HELLO COOLSMS~!</textarea><br />
Type: <select name="type"><option value="SMS">SMS</option><option value="LMS">LMS</option><option value="MMS">MMS</option></select><br />
Image: <input type="file" name="image" /><br />
<input type="submit" value="Submit" />
</form>
</body>
</html> Response
서버는 json 포맷으로 접수결과를 리턴합니다.
Copy {
"group_id": "20120217103829612403761364",
"success_count": 2,
"error_count": 0,
"result_code": "00",
"result_message": "Success"
} result_code 가 00 이면 정상적인 접수이며 이 외의 코드는 http://www.coolsms.co.kr/Legacy_Result_Codes 을 참고하세요. 여기서 리턴되는 Response의 내용은 서버에게 전송을 요청한 것에 대한 정보이지 실제 휴대전화로 전송한 것에 대한 정보가 아닙니다. 예를 들어 요청 건수 중 success_count가 10개라면 서버의 DB에 안전하게 INSERT된 건이 10개라는 의미이며, 나중 sent 리소스를 통해 조회시 이통사를 통해 실제 전송성공된 건수는 8개이고 올바르지 못한 수신번호로 2개로 실패라는 결과가 나올 수 있습니다.
메시지그룹ID(group_id)는 Request된 메시지들의대표하는 아이디값으로 메시지상태 및 예약취소할 때 키값으로 사용될 수 있습니다. 10건의 문자메시지를 발송할 경우 그 10건의 문자메시지를 대표하는 group_id 가 리턴되며 sent 리소스를 통해서 10건에 대한 전송상태를 조회할 수 있습니다.
GET sent
발송된 문자메시지의 목록을 가져옵니다.
Resource Url
https://api.coolsms.co.kr/sms/1.5/sent
Parameters
검색 옵션이 없는 경우 가장 최신의 발송건부터 20일 전까지 내림차순으로 페이지 단위의 목록을 리턴합니다.
Example
Copy <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<?php
$api_key = 'NCS52A57F48C3D32';
$api_secret = '5AC44E03CE8E7212D9D1AD9091FA9966';
$timestamp = time();
$salt = uniqid();
$data = strval($timestamp) . $salt;
$signature = hash_hmac('md5', $data, $api_secret);
?>
<html lang="ko" xml:lang="ko" xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
</head>
<body>
<form method="get" action="https://api.coolsms.co.kr/sms/1.5/sent" enctype="multipart/form-data">
API Key: <input type="text" name="api_key" value="<?php echo $api_key ?>" /><br />
Timestame: <input type="text" name="timestamp" value="<?php echo $timestamp ?>" /><br />
Salt: <input type="text" name="salt" value="<?php echo $salt ?>" /><br />
Signature: <input type="text" name="signature" value="<?php echo $signature ?>" /><br />
List Count : <input type="text" name="count" value="20" /><br />
Page: <input type="text" name="page" value="1" /><br />
<input type="submit" value="Submit" />
</form>
</body>
</html> Response
Response Format은 json을 사용합니다.
Copy {
"total_count":"169",
"list_count":4,
"page":1,
"data":[
{
"type":"SMS",
"accepted_time":"2014-01-07 18:14:54",
"recipient_number":"01000000000",
"group_id":"G52CBC596955F0",
"message_id":"M52CBC59695B31",
"status":"2",
"result_code":"58",
"result_message":"\uc804\uc1a1\uacbd\ub85c \uc5c6\uc74c",
"sent_time":"201401071814",
"text":"Test Message",
"carrier":"SKT",
"scheduled_time":""
},
{
"type":"SMS",
"accepted_time":"2014-01-07 18:14:41",
"recipient_number":"01000000000",
"group_id":"G52CBC5897645A",
"message_id":"M52CBC58976A64",
"status":"2",
"result_code":"58",
"result_message":"\uc804\uc1a1\uacbd\ub85c \uc5c6\uc74c",
"sent_time":"201401071814",
"text":"message\nhere",
"carrier":"KTF",
"scheduled_time":"20160401000000"
},
{
"type":"SMS",
"accepted_time":"2014-01-07 18:11:23",
"recipient_number":"01000000000",
"group_id":"G52CBC4C35B3A8",
"message_id":"M52CBC4C35BA70",
"status":"2",
"result_code":"58",
"result_message":"\uc804\uc1a1\uacbd\ub85c \uc5c6\uc74c",
"sent_time":"201401071811",
"text":"message\nhere",
"carrier":"LGT",
"scheduled_time":""
},
{
"type":"SMS",
"accepted_time":"2014-01-06 12:42:32",
"recipient_number":"01012345678",
"group_id":"G52CA262EC447D",
"message_id":"M52CA262EC49D8",
"status":"2",
"result_code":"00",
"result_message":"\uc815\uc0c1",
"sent_time":"201401061257",
"text":"\ud14c\uc2a4\ud305hi there~",
"carrier":"KTF",
"scheduled_time":""
}
]
} status
result_code 는 http://www.coolsms.co.kr/Legacy_Result_Codes 페이지를 참고 하세요.
POST cancel
예약된 문자메시지를 취소합니다. 예약되지 않았거나, 예약되었으나 이미 발송된 문자메시지는 취소 할 수 없습니다.
Resource URL
https://api.coolsms.co.kr/sms/1.5/cancel
Parameters
mid 혹은 gid 중 하나는 반드시 입력하세요.
GET balance
잔액을 확인합니다.
Resource URL
https://api.coolsms.co.kr/sms/1.5/balance
Parameters
Response
Response Format은 json을 사용합니다.
Copy {
"cash": "23900",
"point": "890"
} GET status
전송채널의 상태를 조회합니다.
Resource Url
https://api.coolsms.co.kr/sms/1.5/status
Parameters
Response
모든 항목의 값은 초단위(seconds)값입니다. sms_average와 mms_average는 각각 SMS채널과 MMS채널의 문자가 접수된 때부터 실제 수신되기까지 걸린 시간으로 계산된 평균값으로 리포트가 오지않은 대기중인 메시지를 합산한 값이므로 다소 높게 나와도 정상입니다. sk, kt, lg 의 경우 수신시각이 분단위로만 제공되어서 약간의 차이가 날 수 있습니다.
Copy [
{
'registdate': '2014-02-25 10:34:01',
'sms_average': '23',
'sms_sk_average': '9',
'sms_kt_average': '10',
'sms_lg_average': '11',
'mms_average': '52',
'mms_sk_average': '20',
'mms_kt_average': '25',
'mms_lg_average': '36'
}
] 