차근차근/네트워크?

REST API - coolsms

예쁜꽃이피었으면 2014. 8. 1. 09:10

http://www.coolsms.co.kr/REST_API

Overview

이 문서는 쿨에스엠에스의 REST API를 통하여 문자전송에서부터 전송된 문자의 상태값을 비롯하여 잔액정보 및 예약취소 등의 작업을 요청하는 방법을 기술하고 있습니다. REST API를 기반으로 PHP, Java, Python 등 다양한 언어로 구현된 SDK 및 예제를 SDK 에서 확인하세요.

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

아래는 Resource Url과 간단한 설명을 테이블로 정리하였습니다. 상세한 설명을 보시려면 해당 Resource Url을 클릭하여 주세요.

Resource	Description
POST send	문자전송 요청
GET sent	발송된 문자정보 읽어오기
POST cancel	예약문자 취소
GET balance	잔액정보 읽어오기
GET status	전송채널 상태 조회

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

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

Authentication

send, sent, balance 등 리소스에 접근하기 위해 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));

Response

리턴되는 HTTP STATUS CODE와 ERROR CODE로 오류여부를 확인할 수 있으며 200 OK 로 정상적으로 명령을 수행한 경우 body에 json 포맷으로 데이터를 전달합니다.

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	메시지내용 미입력

예외 처리 팁

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

{"code":"InvalidAPIKey"}

POST send

문자메시지를 전송 요청합니다. 전송 요청에 대한 Response는 휴대전화까지 전송된 결과가 아닙니다.

Resource URL

https://api.coolsms.co.kr/1/send

Parameters

Mandatory	Field	Description
Ο	인증정보	인증데이터는 필수입니다. Authentication 참고
	to	수신번호 입력 콤마(,)로 구분된 수신번호 입력가능 예) 01012345678,01023456789,01034567890
	from	발신번호 예) 0212345678
	text	문자내용
	type	SMS(80바이트), LMS(장문 2,000바이트), MMS(장문+이미지) 입력 없으면 SMS가 기본 국가코드가 KR이 아니면 SMS로 강제
	image	지원형식 : 300KB 이하의 JPEG, PNG, GIF 형식의 파일 2048x2048 픽셀이하
	image_encoding	이미지 인코딩 방식 binary(Default), base64
	refname	참조내용(이름)
	country	국가코드 (한국: KR, 일본: JP, 미국: US, 중국: CN) 입력 없으면 KR이 기본 (2014/06/20 부터 82, 86, 1과 같이 국제전화 국가번호 지원)
	datetime	예약시간을 YYYYMMDDHHMISS 포맷으로 입력 (입력 없거나 지난날짜를 입력하면 바로 전송) 예) 20131216090510 (2013년 12월 16일 9시 5분 10초에 발송되도록 예약)
	subject	LMS, MMS 일때 제목 (40바이트)
	charset	한글 인코딩 방식 지정 유니코드 UTF-8 일 경우 utf8 완성형 한글(EUC-KR) 일 경우 euckr 으로 입력 입력 없으면 utf8가 기본
	srk	솔루션 제공 수수료를 정산받을 솔루션 등록키
	mode	test로 입력할 경우 CARRIER 시뮬레이터로 시뮬레이션됨 수신번호를 반드시 01000000000 으로 테스트하세요. 예약필드 datetime는 무시됨 결과값은 60 잔액에서 실제 차감되며 다음날 새벽에 재충전됨
	extension	JSON 포맷의 개별 메시지를 담을 수 있음
	delay	0~20 사이의 값으로 전송지연 시간을 줄 수 있음, 1은 약 1초 (기본값은 0)

Mandatory가 Ο 인 필드는 반드시 입력하여야 합니다.

srk 는 http://www.coolsms.co.kr/provider 을 참고하세요.

type, to, from, datetime, text, subject 등의 필드값을 개별적으로 다른 값으로 발송하고자 할 때 JSON형식으로 extension 포맷을 사용할 수 있습니다.

한번의 Request에 extension을 포함하여 총 받는사람(to) 수는 1000개 까지가 제한이며 1000개가 넘을 경우 오류를 발생시킵니다. (RecipientsTooMany)

한번의 Request의 총 크기는 2MB를 넘을 수 없습니다. (오류코드 미정)

extension 포맷

[
	{
		"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, to, from, datetime, text, subject,delay 가 올 수 있고 입력하지 않는 필드는 상위(기본 필드) 값을 상속 받아 사용됩니다. 단, to는 상속받지 아니하고 필수 입력 사항입니다.

발송형태에 따른 제한사항

이동통신사 내부적으로 완성형한글로 변환되므로 영어 1바이트, 한글 2바이트로 취급됩니다.

구분	제한사항
SMS	90바이트 까지 전송가능 (한글 45자)
LMS	2,000바이트 까지 전송가능 (한글 1,000자)
MMS	2,000바이트 텍스트(한글 1,000자) 1개의 이미지 전송(300KB 이하의 JPEG, PNG, GIF 형식의 파일 2048x2048 픽셀이하)

구분

제한사항

SMS

90바이트 까지 전송가능 (한글 45자)

LMS

2,000바이트 까지 전송가능 (한글 1,000자)

MMS

2,000바이트 텍스트(한글 1,000자)

1개의 이미지 전송(300KB 이하의 JPEG, PNG, GIF 형식의 파일 2048x2048 픽셀이하)

Example

<!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/1/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 포맷으로 접수결과를 리턴합니다.

{
  "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/1/sent

Parameters

Mandatory	Field	Description
Ο	인증정보	인증데이터는 필수입니다. Authentication 참고
	count	기본값 20이며 20개의 목록을 받을 수 있음. 40입력시 40개의 목록이 리턴
	page	1부터 시작하는 페이지값
	s_rcpt	수신번호로 검색
	s_start	검색 시작일시 접수 날짜와 시간으로 검색 YYYY-MM-DD HH:MI:SS 포맷의 날짜와 시간
	s_end	검색 종료일시 접수 날짜와 시간으로 검색 YYYY-MM-DD HH:MI:SS 포맷의 날짜와 시간
	s_status	메시지 상태 값으로 검색
	s_resultcode	전송결과 값으로 검색
	mid	메시지ID
	gid	그룹ID

검색 옵션이 없는 경우 가장 최신의 발송건부터 20일 전까지 내림차순으로 페이지 단위의 목록을 리턴합니다.

Example

<!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/1/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을 사용합니다.

{
  "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":"SKT"
    },
    {
      "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":"SKT"
    },
    {
      "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":"SKT"
    },
    {
      "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":"SKT"
    }
  ]
}

status

Status Code	Description
0	대기중
1	이통사로 전송중
2	이통사로부터 리포트 도착

result_code 는 http://www.coolsms.co.kr/Legacy_Result_Codes 페이지를 참고 하세요.

POST cancel

예약된 문자메시지를 취소합니다. 예약되지 않았거나, 예약되었으나 이미 발송된 문자메시지는 취소 할 수 없습니다.

Resource URL

https://api.coolsms.co.kr/1/cancel

Parameters

Mandatory	Field	Description
Ο	인증정보	인증데이터는 필수입니다. Authentication 참고
	mid	메시지ID
	gid	그룹ID

mid 혹은 gid 중 하나는 반드시 입력하세요.

GET balance

잔액을 확인합니다.

Resource URL

https://api.coolsms.co.kr/1/balance

Parameters

Mandatory	Field	Description
Ο	인증정보	인증데이터는 필수입니다. Authentication 참고

Response

Response Format은 json을 사용합니다.

{
  "cash": "23900",
  "point": "890"
}

GET status

전송채널의 상태를 조회합니다.

Resource Url

https://api.coolsms.co.kr/1/status

Parameters

Mandatory	Field	Description
Ο	인증정보	인증데이터는 필수입니다. Authentication 참고
	count	기본값 1이며 1개의 최신의 레코드를 받을 수 있음, 10입력시 10분 동안의 레코드 목록을 리턴

Response

모든 항목의 값은 초단위(seconds)값입니다. sms_average와 mms_average는 각각 SMS채널과 MMS채널의 문자가 접수된 때부터 실제 수신되기까지 걸린 시간으로 계산된 평균값으로 리포트가 오지않은 대기중인 메시지를 합산한 값이므로 다소 높게 나와도 정상입니다. sk, kt, lg 의 경우 수신시각이 분단위로만 제공되어서 약간의 차이가 날 수 있습니다.

[
  {
    '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'
  }
]

저작자표시 비영리

'차근차근 > 네트워크?' 카테고리의 다른 글

sendmail , 스팸릴레이 대응 (0)	2015.06.01
REST 서비스 템플릿 (0)	2014.08.01
REST API 대충 대충 이런저런 (0)	2014.08.01
SOAP이냐 REST이냐 - 표준이냐 간결함이냐 (0)	2014.08.01
gSOAP windows에서 실행하기 - 망 (0)	2014.07.31

현재글REST API - coolsms

개인 공부를 위한 블로그입니다.

vuejs, 한 번에 끝내는 코딩테스트 369 Java편 초격차 패키지 Online., 백준, docker, 인증문자, 직장인자기계발, Gunicorn, 자바, 직장인인강, 패스트캠퍼스, 10953, ubuntu, Django, 패스트캠퍼스후기, MYSQL, 10952, 패캠챌린지, AWS, 10951, nginx,

Today :
Yesterday :

내 인생에도 예쁜 꽃이 피었으면 좋겠다

REST API - coolsms

Overview

Authentication

PHP에서 signature 생성 예제

Response

예외 처리 팁

POST send

Resource URL

Parameters

extension 포맷

발송형태에 따른 제한사항

Example

Response

GET sent

Resource Url

Parameters

Example

Response

status

POST cancel

Resource URL

Parameters

GET balance

Resource URL

Parameters

Response

GET status

Resource Url

Parameters

Response

'차근차근 > 네트워크?' 카테고리의 다른 글

'차근차근/네트워크?'의 다른글

티스토리툴바

« 2024/04 »
일	월	화	수	목	금	토
	1	2	3	4	5	6
7	8	9	10	11	12	13
14	15	16	17	18	19	20
21	22	23	24	25	26	27
28	29	30

REST API - coolsms

Overview

Authentication

PHP에서 signature 생성 예제

Response

예외 처리 팁

POST send

Resource URL

Parameters

extension 포맷

발송형태에 따른 제한사항

Example

Response

GET sent

Resource Url

Parameters

Example

Response

status

POST cancel

Resource URL

Parameters

GET balance

Resource URL

Parameters

Response

GET status

Resource Url

Parameters

Response

'차근차근 > 네트워크?' 카테고리의 다른 글

'차근차근/네트워크?'의 다른글

관련글

티스토리툴바