REST API

Overview

문자메시지 발송 서비스를 REST API를 통하여 연동할 수 있습니다.

 

API Description
SMS API

휴대전화 단말기로 문자메시지를 발송 할 때 사용

SenderID API 발신번호 등록 API

 

 PHP, Java, Python 등 다양한 언어로 구현된 SDK 및 예제를 SDK 에서 확인하세요.

 

인증을 위한 API Key 및 API Secret 코드는 문자메시지 > 환경설정 > API Key 관리 메뉴에서 발급 및 관리가 가능하며 인증방법은 Authentication 을 확인해 주세요.

 

요청에 대한 응답의 상세는 Response 를 확인하세요.

 

REST API 관련 질의 응답 및 정보 공유는 개발자포럼을 이용해주세요.

Authentication 

  sendsentbalance 등 리소스에 접근하기 위해 api_key, timestamp, salt, signature 등의 인증정보를 서버로 전송하여 인증을 거쳐야 합니다. API Key 발급은 API Key 관리 페이지에서 생성 및 삭제 가능합니다.

Mandatory Field Description
Ο api_key 발급받은 API Key 입력
Ο timestamp UNIX TIME(1970년 1월 1일 0시부터 초 단위로 카운트된 정수값) php에서는 time() 함수호출로 값을 리턴 받을 수 있다
O salt 5~30 바이트 사이의 랜덤으로 만들어진 문자열
Ο signature timestamp + salt를 데이터로 api_secret을 키로 한 HMAC 해시코드
  algorithm HMAC 생성 알고리즘, 기본은 md5
  encoding signature값의 인코딩 방식(hex와 base64 지원, 기본은 hex)

timestamp(문자열) + salt(문자열) 를 데이터로, api_secret을 키로 사용하여 HMAC(Hash based message authentication code)을 만듭니다. 서버에서 api_key로 내부DB에서 api_secret을 찾아 클라이언트와 같은 방법으로 signature를 만들어 클라이언트에서 보내온 signature와 비교하여 같으면 인증이 완료됩니다.

api_secret은 signature를 만들 때만 사용하고 서버에 전송하지 않도록 합니다. api_secret이 외부에 노출되지 않도록 주의합니다.

salt를 매번 다른 문자열로 변경하여 항상 signature가 다른 값으로 생성되게 합니다.

15분 안에 전송되는 Request의 signature 값은 항상 달라야 합니다.

또한 timestamp값이 현재시간에서 15분을 벗어나면 서버쪽에서 RequestTimeTooSkewed 오류코드를 리턴합니다.

PHP에서  signature 생성 예제

$api_key = 'NCS529FF432C2480';
$api_secret  = '83ECD4D6D7C53AD5B8552209FB4E24BE';
$timestamp = time();
$salt = uniqid();
$user_id = 'test';
$hmac_data = str($timestamp).$salt;

$signature = hash_hmac('md5', $hmac_data, $api_secret);
// encoding을 base64로 할 경우
// $signature = base64_encode(hash_hmac('md5', $hmac_data, $api_secret, TRUE));

Request

Resource의 행위에 따라 Form Method는 POST와 GET으로 호출됩니다.

Method Description
POST 데이터의 INSERT, UPDATE, DELETE 등의 행위
GET 서버로부터 데이터를 읽어오는 행위(SELECT)

 

API 설명 페이지에서는 각 Resource 이름 앞에 POST 혹은 GET을 붙어 있습니다. ex) POST send, GET sent

서버에 요청할 때는 반드시 Authentication 정보가 함께 넘어가 인증을 통과하도록 합니다.

 

※ Request Parameters 입력시 JSON 포맷의 데이터가 아니라 폼데이터임을 유의해 주세요. Response Body의 데이터가 JSON 형식입니다.

Example Request

Example POST) 문자메시지 발송하기

<form method="post" action="https://api.coolsms.co.kr/1.2/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>

 

Example GET) MO 메시지 가져오기

<form method="get" action="http://api.coolsms.co.kr/mo/1/list">
	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 />
	Start: <input type="text" name="start" value="<?php echo date('Y-m-d H:i:s') ?>" /><br />
	End: <input type="text" name="end" value="<?php echo date('Y-m-d H:i:s') ?>" /><br />
	<input type="submit" value="Submit" />
</form>

 

Response

리턴되는 HTTP STATUS CODE와 ERROR CODE로 오류여부를 확인할 수 있습니다.

200 OK 로 정상적으로 명령을 수행한 경우 HTTP BODY에 json 포맷으로 데이터가 전달되며 오류 발생시 json 포맷에 아래 테이블에서 해당하는 오류의 code가 전달됩니다.

Error Code HTTP Status Code Description
OK 200 OK 성공적으로 수행
InvalidAPIKey 403 Forbidden 유효한 API Key가 아님
SignatureDoesNotMatch 403 Forbidden 생성한 Signature가 일치하지 않음
NotEnoughBalance 402 Payment Required 잔액이 부족함
InvalidMethod 400 Bad Request 해당 리소스에 접근가능한 METHOD(POST / GET)가 아님
InvalidMessageType 400 Bad Request 메시지타입은 SMS, LMS, MMS 중 하나여야 함
NoSuchMessage 404 Not Found 해당 메시지가 없음
UnknownAlgorithm 403 Forbidden 지원하지 않는 해시알고리즘 MD5, SHA-1
InternalError 500 Internal Server Error 서버 내부 오류
InvalidResource 404 Not Found 존재하지 않는 리소스에 접근
RequestTimeTooSkewed 403 Forbidden timestamp 값이 위 아래로 15분을 벗어남
DuplicatedSignature 403 Forbidden 15분 안에 동일한 signature 값
FileSizeTooBig 413 Request Entity Too Large 이미지파일 사이즈 300KB 초과
NoImageInput 400 Bad Request 이미지 미입력
NoMessageInput 400 Bad Request 메시지내용 미입력
RecipientsTooMany 413 Request Entity Too Large 입력된 수신번호가 1000개를 넘음
ImageTypeNotSupported 403 Forbidden 지원하지 않는 이미지 포맷
ImageResolutionSizeTooBig 413 Request Entity Too Large 이미지의 해상도가 너무 큼, 2048 x 2048 이하
MissingRequiredParameter 400 Bad Request 필수입력 파라메터 미입력

 

예외 처리 팁

먼저 HTTP STATUS CODE를 확인하여 200 OK이 아닌 경우 body의 json 데이터를 읽어 Error Code로 오류내용을 파악하고 적절한 예외처리를 해줍니다. API Key가 올바르지 않은 경우 아래와 같이 json 데이터가 body에 리턴됩니다.

{"code":"InvalidAPIKey"}