Skip to content

청기와랩 블로그

SMS API v1.0.2 마이너 업데이트 (2015.5.8)

SMS API v1.0과 v1.0.1에 마이너한 이슈가 발견 되어 픽스가 이루어 졌습니다.
기존 적용하신 v1.0 및 v1.0.1기반 프로그램의 경우 대부분 문제가 없으므로  수정 하실 필요 없으며, 향후 새로 생성되는 Application ID는 v1.0.2로 생성 됩니다.

v1.0.2에서 개선 내용은 다음과 같습니다.

URI /smscenter/v1.0/sendsms  (sms발송)
버그 내용 receivers: ["", ] 처럼 수신자 목록 아이템은 있으나 유효성 체크 후에 [] 가 되어 수신자가 없는 경우에도 200 OK  가 리턴됨.

예)
200 OK
{"filtered": [""], "reserved": null, "sent": []}  
# 200 OK지만 실제 발송내역이 없으므로 sent항목에 발송ID도 없음
문제점 수신자가 없어 발송ID가 생성되지 않으므로 CREDIT 차감 등의 문제는 없음
다만 리턴값이 200 OK 에서 412 같은 에러 값으로 바뀌어야 올바름
수정 상태 해당 경우 412 PRECONDITION FAILED 에러가 리턴 되도록 수정 및 서버 적용 완료
(자세한 내용은 아래 참조)

예)
412 PRECONDITION FAILED

청기와랩의 이슈 수정을 위한 서버 변경 사항은 다음과 같습니다.
  • 기존에 발급된 예전 버전의 App-ID 들은 기존 대로 동작됨
  • 2015. 5. 8일 부터 신규 발급되는 Application 들은 v1.0.2이 적용된 Application ID가 발급 되도록 함
  • v1.0.2 Application의 경우 수신자목록 (receivers)가 없는 경우 412 에러가 리턴되도록 동작 됨

F.A.Q
Q: 현재 v1.0 및 v1.0.1 Application 을 구현하여 운영중인데 어떻게 해야 하나요?
A: 해당 이슈가 문제 되지 않는 경우 구현하신 프로그램 수정 없이 계속 사용 합니다.
만약 문제를 경험하신 경우 간단하게 v1.0.2 Application ID를 신규 발급 받아 적용 하시면 됩니다.

Q: RESTful API의 URI들이 바뀐 버전 v1.0.2 에 맞추어 바뀌나요?
A: v1.0.2은 v1.0 프로토콜의 마이너 업데이트 이므로 기존 /smscenter/v1.0/XXX 형식의 URI 들은 계속 유지되고 기존 처럼 사용 가능 합니다.

Q: GitHub의 예제들에 수정사항이 생기나요?
A: 아닙니다. 각 기능별 URI 가 바뀌지 않았으므로 코드 변경 없이 계속 사용 가능 합니다.


앞으로도 더욱 노력하는 청기와랩이 되겠습니다.
감사합니다


청기와랩 SMS API 서버 성능 개선 (2015.4.27)

청기와랩 API 서버의 로케이션 변경 및 H/W 업그레이드를 통하여 기존 대비 약 4배가량 네트워크 응답 속도가 개선 되었습니다.

항상 발전하는 청기와랩이 되겠습니다.


SMS API v1.0.1 업그레이드 공지 (2015.1.8)

기존 SMS API v1.0에 버그가 발견 되어 버그 픽스가 이루어 졌습니다.

v1.0의 버그 내용은 다음과 같습니다.

URI  /smscenter/v1.0/result/(Delivery-ID)   (개별 발송 결과 조회)
버그 내용 Response로 받는 JSON 데이타 중 status가 integer type이 아닌 string type으로 오는 경우 발생

정상 Behavior (최초 조회시)
{"status": 0, "destination": "01000000000", "sent_time": "2015-01-07T17:38:20Z"}

오류 Behavior (이후 재 조회시)
{"status": "0", "destination": "01000000000", "sent_time": "2015-01-07T17:38:20Z"}
문제점 값의 type이 일관되지 않음. 0 == "0" 인 특정 언어들 (PHP, Javascript 등) 에서는 문제가 없으나 대부분의 strict type checking을 하는 대부분의 언어로 해당 URI를 사용하는 경우, status 값에 비교 루틴 적용시 문제가 될 수 있음.
수정 상태 수정 및 서버 적용 완료
(자세한 내용은 아래 참조)

청기와랩의 이슈 수정을 위한 서버 변경 사항은 다음과 같습니다.
  • /smscenter/v1.0/result/(Delivery-ID) 은 현재 각 고객사 별로 운영중인 v1.0 Application들에 영향이 없도록 기존 behavior를 유지
    • 위의 오류 케이스가 발생 할 수 있음
    • 그러나 기존에 해당 URI를 사용하지 않거나 문제에 영향 없이 사용 하던 경우 별도의 수정 없이 그대로 계속 사용 가능
  • 2015. 1. 8일 부터 신규 발급되는 Application 들은 v1.0.1이 적용된 Application ID가 발급 되도록 함
  • v1.0.1 Application이 해당 URI 접근 시 수정된 정상 behavior 로 동작 함

F.A.Q
Q: 현재 v1.0 Application 을 구현하여 운영중인데 어떻게 해야 하나요?
A: 문제가 된 개별 발송 결과 조회 URI를 쓰고 있지 않았다면 기존 구현하신 프로그램 수정 없이 계속 사용 합니다.
만약 문제를 경험하신 경우 간단하게 v1.0.1 Application ID를 신규 발급 받아 적용 하시면 해결 됩니다.

Q: RESTful API의 URI들이 바뀐 버전 v1.0.1 에 맞추어 바뀌나요?
A: v1.0.1은 v1.0 프로토콜의 마이너 업데이트 이므로 기존 /smscenter/v1.0/XXX 형식의 URI 들은 계속 유지되고 기존 처럼 사용 가능 합니다. 

Q: GitHub의 예제들에 수정사항이 생기나요?
A: 아닙니다. 각 기능별 URI 가 바뀌지 않았으므로 코드 변경 없이 계속 사용 가능 합니다.


앞으로도 더욱 노력하는 청기와랩이 되겠습니다.
감사합니다




Tutorial 2: GitHub에서 청기와랩 SMS API 예제 실행 해보기

자 이제 Tutorial 1에서 등록한 Application ID를 사용해 볼 시간입니다.

청기와랩의 다양한 예제 코드들은 GitHub 에 오픈소스로 공개되어 있습니다.
먼저  https://github.com/BlueHouseLab/sms-openapi 에 접속 합니다.


청기와랩의 GitHub 페이지 입니다. GitHub 에 익숙 하신 개발자 분들은 평소에 하시던 데로 페이지를 쓰윽 둘러 보시면 무엇을 해야 될지 다 아실거에요. 하지만 지금은 튜토리얼 시간이니까 차근 차근 따라 해보기로 해요. :-)

우측 사이드바에 보시면 Git Repository URL 이 있습니다.
예제 코드는 git 명령어를 이용하여 clone 과정을 거쳐 다운 받으실 수도 있고, ZIP 파일로 다운 받으실 수도 있습니다.

로마에서는 로마법을 따라야 겠죠? GitHub 에서는 Git 를 쓰는게 법이랍니다.
https://github... 로 시작되는 URL을 복사한 다음에 터미널에 다음과 같이 붙어 넣으세요

bluehouselab:home $ git clone https://github.com/BlueHouseLab/sms-openapi.git
Cloning into 'sms-openapi'...
remote: Counting objects: 231, done.
remote: Total 231 (delta 0), reused 0 (delta 0)
Receiving objects: 100% (231/231), 51.72 KiB | 0 bytes/s, done.
Resolving deltas: 100% (120/120), done.
Checking connectivity... done.
bluehouselab:home $

이렇게 하면 sms-openapi 라는 디렉토리에 GitHub 에 등록된 청기와랩의 SMS API 예제를 개발자님의 local machine 에 "clone" 하게 됩니다.

자 이제 sms-openapi 디렉토리에 들어가 볼까요?
bluehouselab:home $ cd sms-openapi/
bluehouselab:sms-openapi $ ls
LICENSE         c++qt5          curl            node.js         python-requests
README.md       c-curl          docs            php             ruby
c#              callback-api    java            python
bluehouselab:sms-openapi $

보시다 싶이 2014년 11월 현재 다음과 같은 예제가 제공 되고 있습니다.
  • C++ (with Qt5)
  • C (with libcurl)
  • Bash (with curl)
  • Node.js
  • Python (httplib, requests)
  • PHP
  • Ruby
  • Java
  • C# (Mono)

웹 개발 환경에서는 PHP, Python, Ruby, Java, C# 을 참조 하시면 됩니다.

Unix 환경 내지는 GUI 프로그램들은 C++, C, Java 등이 유용할 걸로 생각 됩니다. 특히 C++ 예제는 GUI ToolKit 쪽에서 가장 많이 쓰이는 크로스플랫폼 라이브러리인 Qt5를 사용 했으므로 Linux, WIndows, Mac 등 다양한 환경에서 참조하실 수 있습니다. C 예제도 말할 것도 없이 뛰어난 이식성을 자랑 합니다. 

Java, C#, PHP, Ruby, Node.js, Python 예제 들은 해당 언어의 standard module 들을 사용했으므로  별다른 라이브러리 설치 없이 테스트 가능 합니다.

이번 Tutorial 에서는 가장 많이 사용되는 환경인 Linux 에서 가장 쉽게 테스트 해볼 수 있는 BASH 예제를 소개해 볼까 합니다. Mac OS X 을 사용하시는 개발자 분들도 별다른 모듈 설치 필요 없이 바로 테스트 해보실 수 있습니다.

Bash 예제는 쉘스크립트로 SMS 를 보내볼 수 있는데요. curl 이라고 하는 Command line HTTP Client Tool을 사용 합니다. curl 은 현대 리눅스 배포판및 BSD 계열의 Mac OS X 에도 기본으로 들어 있는 명령어 입니다. Windows 개발자 분들도 Cygwin 또는 MSYS 환경에서 쉽게 테스트 해보실 수 있습니다.

자 한번 해볼까요?
먼저 curl 디렉토리에 들어가서 어떤 예제 파일들이 있는지 확인해 봅시다.
bluehouselab:sms-openapi $ cd curl/
bluehouselab:curl $ ls
env.sh     result.sh  sendsms.sh
bluehouselab:curl $

env.sh, result.sh, sendsms.sh 가 있는데요. vi 나 emacs, nano, pico 등의 편집기로 파일을 열어 봅시다.
bluehouselab:curl $ vi env.sh
	

env.sh 에는 Tutorial 1에서 발급 한 Application ID 와 Key 를 입력 합니다.
#!/bin/bash
APPID=example
APIKEY=c5dd7e7dkjp27377l903c42c032b413b
HOST=https://api.bluehouselab.com:443
		

자 이제 sendsms.sh 를 열어 볼까요?
#!/bin/bash
SENDER=01000000000 # FIXME MUST BE CHANGED AS REAL PHONE NUMBER
RECEIVER=01000000000 # FIXME MUST BE CHANGED AS REAL PHONE NUMBER
. env.sh # load env
curl -i -u $APPID:$APIKEY \
     -X POST $HOST/smscenter/v1.0/sendsms \
     -H "Content-Type: application/json;charset=utf-8" \
     -d '{"sender": "'$SENDER'", "receivers": ["'$RECEIVER'"], "content": "나는 유리를 먹을 수 있어요. 그래도 아프지 않아요"}'
			

3번째 4번째 줄인 SENDER와 RECEIVER 값만 실제 테스트 하실 전화번호로 바꾸시면 됩니다.
# 이후로는 주석이니 무시하셔도 됩니다.
중간에 보시면 ". env.sh" 가 있습니다. Bash 에서는 "쩜" 도 명령어 Alias 중 하나인데요. "source" 명령과 동일합니다. env.sh 의 내용을 Load 하는 것이죠. 다른 언어에서 include 나 import 하는것 처럼요.

자 그럼 실행해 볼까요?

bluehouselab:curl $ sh sendsms.sh 
HTTP/1.1 403 FORBIDDEN
Date: Mon, 03 Nov 2014 14:02:50 GMT
Server: Apache/2.2.22 (Ubuntu)
Vary: Accept-Encoding
Transfer-Encoding: chunked
Content-Type: text/html; charset=utf-8
API Key does not match
bluehouselab:curl $
403 Forbidden 에러가 발생 했네요. API Key does not match 라고 친절하게 에러 원인도 HTTP 를 통해 전달 됩니다.

env.sh 에 적혀 있는 APPID와 APIKEY를 변경 하지 않아서 인데요. Tutorial 1의 과정에서 발급 받으신  Application ID와 Key 로 바꾸시면 됩니다.

bluehouselab:curl $ sh sendsms.sh 
HTTP/1.1 200 OK
Date: Mon, 03 Nov 2014 14:09:41 GMT
Server: Apache/2.2.22 (Ubuntu)
Transfer-Encoding: chunked
Content-Type: application/json; charset=utf-8
{"filtered": [], "reserved": null, "sent": [["010XXXXXXXX", "201411XXXXXXXXXXXXXXX"]]}
자 200 OK 가 리턴되었고 JSON 형식의 Data 도 같이 리턴 되었네요.
010XXXXXXXX 번으로 Delivery ID가 201411XXXXXXXXXXXXXXX 인 메시지가 발송 되었다는 뜻입니다.

지금쯤 휴대폰으로 "나는 유리를 먹을 수 있어요. 그래도 아프지 않아요"의 내용이 담긴 SMS가 잘 도착 했을 겁니다.

리턴받을 수 있는 HTTP Status Code 는 http://bluehouselab-sms-openapi.readthedocs.org/ko... 를 참고하세요.

만약 충전된 크레딧 이나 포인트가 부족할 경우 402 Payment Required 을 리턴받게 됩니다. 크레딧 충전이 필요한 상황 이지요. ~(^.^)~

그럼 이제 SMS 가 잘 도착했는지, 프로그래밍으로 확인해 볼까요?
bluehouselab:curl $ sh result.sh 201411XXXXXXXXXXXXXXX
HTTP/1.1 200 OK
Date: Mon, 03 Nov 2014 14:18:27 GMT
Server: Apache/2.2.22 (Ubuntu)
Transfer-Encoding: chunked
Content-Type: application/json; charset=utf-8
{"status": 0, "destination": "010XXXXXXXX", "sent_time": "2014-11-03T14:09:47Z"}
bluehouselab:curl $
result.sh 예제도 env.sh 에 저장된 APP ID와 API Key 값을 읽어 들여 Delivery 성공 여부를 체크하는 스크립트 입니다. 200 OK 와 JSON 데이타가 리턴 되었습니다.

status: 0 은 메시지가 성공적으로 도착했음을 의미 합니다. 받는 사람의 휴대폰이 꺼져 있거나 존재하지 않는 번호 라면 다른 값을 받게 됩니다.  받을 수 있는 모든 status 값들은 http://bluehouselab-sms-openapi.readthedocs.org/ko... 을 참조하세요.

만약 전화번호는 정확 하지만 휴대전화가 꺼져 있다면 -1을 리턴 받습니다. 최대 이틀 까지 -1 상태가 유지될 수 있으며, 휴대폰이 켜지고 문자수신이 완료 되면 0으로 바뀌게 됩니다. 이틀 후까지 전송되지 않는 다면 발송에 사용한 Credit은 Point 로 환급 됩니다.

발송 여부 확인은 청기와랩 홈페이지의 발송 내역 Report 페이지에서 화려한 Graph와 표로 보실 수도 있습니다. 프로그램을 작성하여 확인하기 어려운 상황에서 유용한 정보를 제공해 줍니다.





Tutorial 2를 마치며... 
May the code be with you...


다음 튜토리얼에서는 다른 언어 예제에 대한 더 자세한 비하인드 스토리가 이어 집니다!

sms   smsapi   example   tutorial  


Tutorial 1: Application ID 등록 하기

청기와랩 SMS Open API 를 사용하기 위한 튜토리얼 입니다.

청기와랩의 SMS API를 사용하는 방법은 매우 간단합니다.

  1. 사이트 가입
  2. Application ID 등록 (API Key 발급)
  3. GitHub 에서 예제 다운로드
  4. SMS 응용 프로그램 (또는 웹사이트) 개발
  5. Credit 결제

자 그럼 차근 차근 알아 볼까요?

일단 가장 먼저 청기와랩 사이트에 가입 하세요. 우측 상단의 Login 버튼을 클릭하면 나오는 로그인 다이얼로그에서 서비스 가입 링크를 발견 하실 수 있습니다. 

간단히 Email 과 비밀번호, 이름, 전화번호를 입력하고 이용약관에 동의하시면 가입 완료!

이제 SMS 발송을 위한 API Key를 발급받을 차례입니다.
API Key는 http://www.bluehouselab.com/sms/ 에서 발급 받으실 수 있는데요.

우측 사이드바에 있는 API Key  발급 받기 버튼을 클릭하세요.


가입 후 처음 사용하는 것이므로 '아직 발급된 API Key가 없습니다.'라는 문구와 어플리케이션 등록 버튼이 나옵니다.



어플리케이션 등록 버튼을 클릭하면 아래와 같이 API Key 발급 신청 페이지로 이동합니다.

위 페이지에서 필수 정보(Application ID, 이용목적)를 입력하시고 하단의 등록 버튼을 클릭하시면 발급 신청이 완료됩니다. 주의하실 점은 이용 목적을 꼭 자세히 적으셔야 한다는 점입니다. 목적이 불분명하거나 스팸등의 부적절한 목적으로 의심될 경우 발송 제한에 걸릴 수 있으니 자세히 기술해 주세요.

처음 API Key를 발급받으면 500포인트를 적립해 드립니다. GitHub 에서 예제를 다운 받아 충분히 테스트 해보실 수 있도록 말이죠. 청기와랩의 작은 선물입니다. :-)

GitHub 에서 예제 코드를 다운로드 받는 방법은 Tutorial 2 에서 자세히 다루기로 하고, 청기와랩 SMS API의 크레딧과 포인트의 개념에 대해 알아 볼까요?

'크레딧'이란 청기와랩 OpenAPI에서 사용되는 용어로써 '충전금액을 의미하며, 총 크레딧만큼 서비스를 이용하실 수 있습니다.
'포인트'는 크레딧과 동일하게 SMS 발송 시 사용할 수 있는데, 충전으로 쌓이는 것이 아니라 방금 전 처럼 첫 API Key 발급 기념 보너스 또는 크레딧 결제 금액 별로 추가로 주어지는 방식으로 적립 됩니다. 또한 SMS 발송 실패시에도 포인트로 환급 됩니다.
적립된 '포인트'는 크레딧이 모두 소진 되었을때만 사용 가능 합니다.

첫 API Key 발급 기념으로 주어진 500포인트를 예제 테스트 또는 개발하시는 과정에 모두 다 소진 하셨다면 이제 크레딧을 충전해야 할 차례 입니다. 우측 사이드바의 API Usage & Report 박스에서 '크레딧 충전'을 클릭 하시면 간단하게 Credit 결제를 하실 수 있습니다.



크레딧 충전은 편리한 신용카드, 실시간 계좌이체 두가지 방식으로 가능 합니다.
충전 금액별로 차등 지급되는 포인트 적립으로 더 저렴하게 SMS와 LMS를 발송 하실 수 있습니다.

지금 까지 간단히 청기와랩 SMS API를 사용하기 위한 간략한 절차를 설명 드렸으니 이제 제대로 공부해볼까요? Tutorial 2 에서는 GitHub 에 공개된 청기와랩의 SMS API 예제 코드를 어떻게 사용하는지에 대해 알아보겠습니다.
 
May the code be with you...

sms   smsapi   tutorial  


청기와랩의 서비스