변경이력 버전 일자 내용 작성자 최초작성 한은경 v.1.1 문서변경 한은경 v.1.2 문서변경 한은경 v1.3 문서변경 한은경

Size: px

Start display at page:

Download "변경이력 버전 일자 내용 작성자 최초작성 한은경 v.1.1 문서변경 한은경 v.1.2 문서변경 한은경 v1.3 문서변경 한은경"

윤미 영
6 years ago
Views:

1 Messaging Service HTTP API Specification V2.3.5 Last Modified: 15.November,

2 변경이력 버전 일자 내용 작성자 최초작성 한은경 v.1.1 문서변경 한은경 v.1.2 문서변경 한은경 v1.3 문서변경 한은경 v1.4 문서변경 한은경 XML parameters 변경 _ (underbar) by - (bar) 한은경 2. Report Responses and 리턴값추가 Concatenated Message 설명추가 한은경 2. Submit packet charset 필드추가 3. to_country 레포트필드에서삭제 4. Submit필드에서 charset 추가 Response에서 msg_type 필드추가 한은경 2. REPORT Response에서 rescnt 추가 규격서설명보강 한은경 리포트접속정보추가 한은경 MMS title 필드추가 한은경 발신번호사전등록제관련에러코드추가 한은경 Base URL 변경 / HTTPS 프로토콜추가 남궁희 2. 리포트수신 IP 변경 3. 결과코드변경 4. 응답코드추가 ( 여신 / 발신자변작등 ) 5. 결과전송 API status 파라미터제거 Report 포맷변경 남궁희 샘플코드추가 성공일경우 예시항목변경 이정해 As is : <err_code>1000</err_code> To be : <err_code>r000</err_code> Request format 남궁희 payment_code, client_sub_id 필드추가 nodejs 예시항목변경 As is : path: 'sms/xml?id' + encodeuricomponent('infobank_test') To be : path: 'sms/xml?id=' + encodeuricomponent('infobank_test') 남궁희 2 / 14

3 결과코드추가 남궁희 : Charset conversion error ( 동보사용시국가코드 '82' 인경우, 건별인코딩오류처리 ) Request format 절 from 항목설명변경 임정훈 https 프로토콜만유지 http 프로토콜제거 임정훈 결과코드제거 (Callback URL을받을수없는폰 ) 제거 임정훈 3 / 14

4 목차 1. HTTP API 란? 서비스흐름도 전문규격 BASE URL 결과정보수신 REQUEST FORMAT Request 예시 PHP Shell(BASH) Python Ruby nodejs REQUEST RESPONSE FORMAT Request Response 예시 성공일경우 실패일경우 REPORT FORMAT Report 예시 성공일경우 실패일경우 REPORT RESPONSE FORMAT Report Response 예시 응답및결과코드 RESPONSE RETURN CODE REPORT RETURN CODE APPENDEX CONCATENATED MESSAGE CONTACT INFORMATION / 14

1. HTTP API 란? 인포뱅크의메시징서비스를이용하기위해 HTTPS 방식을이용한연동규격을말합니다. 본규격을이용하여국내 / 외메시징서비스를이용할수있으며, 본서비스를이용하시기위해서는담당영업사원으로부터접속정보를제공받으셔야합니다. 2. 서비스흐름도 Wireless Environment 1.

5 1. HTTP API 란? 인포뱅크의메시징서비스를이용하기위해 HTTPS 방식을이용한연동규격을말합니다. 본규격을이용하여국내 / 외메시징서비스를이용할수있으며, 본서비스를이용하시기위해서는담당영업사원으로부터접속정보를제공받으셔야합니다. 2. 서비스흐름도 Wireless Environment 1. Request HTTPS : TCP/IP 통신를이용하며 Client는 HTTPS API 규격에맞춰서메시지전송 2. Response HTTPS : Server는 Client로부터전달받은메시지전송요청응답 3. SEND SMS : Server는통신사에메시지를전송 4. Get Reports : 통신사업자로부터메시지리포트수신 5. Get Reports : 통신사업자가인포뱅크 Server로전송한메시지리포트를 Client로전달 6. Response Reports : 메시지리포트정상수신여부에대한응답을 Server에전달 3. 전문규격 HTTPS METHOD - 전송요청을위해 HTTPS GET/POST 방식을제공하며, 전송응답은 XML 방식을사용합니다. ENCODING - UTF-8 인코딩을기본으로제공합니다. 5 / 14

6 TIMEZONE - 메시지기준시간은한국표준시 KST(UTC+9) 를사용합니다 Base URL HTTPS 결과정보수신 리포트를수신하기위해서는인포뱅크에서제공하는서버 IP에대한접근을허용해야하며, 리포트를수신할고객사측 IP/PORT 에대한정보는 bizplus@infobank.net 로접수해야합니다. 결과송신서버 IP 정보 : / Request format 전세계언어를지원하기위해 UTF-8인코딩을사용합니다. [M] Mandatory : 필수 [O] Optional : 옵션 Parameter M/O TYPE Description from M Char 발신자전화번호 ( 최대길이 16 byte) ex) 한국발송시 ( 국가코드미포함 ) 해외발신시 ( 국가코드포함 ) to_country M Char 국가코드 (1 ~ 3 bytes) ex) 한국발송시, to_country=82 to M Char 수신자전화번호 ( 최대길이 13 byte) ex) 한국발송시, to= title O Char 메시지제목 ( 최대길이 40 byte) - 메시지제목은 UTF-8 과 URL 인코딩필요 - 한국장문발송시에만유효함 message M Char 메시지내용 - 메시지내용은 UTF-8 과 URL 인코딩필요 report_req M Char 레포트수신여부 - 1 : 레포트수신이며, 필수셋팅필요 charset O Char 인코딩설정 (1 : UTF-8, 2 : euc-kr) - 해당값을설정하지않으면 UTF-8 로기본인코딩됨. ex) charset=2 (euc-kr) ref O Char 여분필드, 고객이설정할수있는필드값 ( 최대길이 20 byte. 영. 숫자만가능 ) 6 / 14

7 ttl O Char 메시지유효시간 ( 초단위 ) ex) ttl=86400 (24hour = 60 * 60 * 24) payment_code O Char 정산용부서코드 ( 최대길이 20 byte) client_sub_id O Char Sender ID, 메시지서명을복수로지정하기위한구분자 ( 최대길이 20 byte) 발신번호는숫자형식을지원합니다. 한국으로 90byte를초과하는메시지발송시 LMS( 첨부파일없는 MMS) 형태로자동전환됩니다 Request 예시 PHP <?php $url = ' http_build_query([ 'id' => 'infobank_test', 'pwd' => 'pwinfobank', 'from' => ' ', 'to_country' => '82', 'to' => ' ', 'message' => 'Hello Infobank', 'report_req' => '1' ]); $ch = curl_init($url); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); $response = curl_exec($ch); $xml = simplexml_load_string($response); if ($xml === false) { echo "Failed loading XML: "; } else { //print_r($xml); //echo($xml->to_country); //echo($xml->to); echo("response code : ". $xml->messages->message->err_code); }?> 7 / 14

8 Shell(BASH) #!/bin/bash curl ' \ -d id=infobank_test \ -d pwd=pwinfobank \ -d from= \ -d to_country=82 \ -d to= \ --data-urlencode "message=hello Infobank" \ -d report_req= Python import urllib params = { 'id': 'infobank_test', 'pwd': 'pwinfobank', 'from': ' ', 'to_country': '82', 'to': ' ', 'message': 'Hello Infobank', 'report_req': '1' } url = ' + urllib.urlencode(params) response = urllib.urlopen(url) print response.read() Ruby require "net/http" require "uri" uri = URI.parse(" params = { "id" => "infobank_test", "pwd" => "pwinfobank", "from" => " ", 8 / 14

9 } "to_country" => "82", "to" => " ", "message" => "Hello Infobank", "report_req" => "1" response = Net::HTTP.post_form(uri, params) puts response.body nodejs var https = require('https'); var options = { host: 'rest.supersms.co', path: 'sms/xml?id=' + encodeuricomponent('infobank_test') + '&pwd=' + encodeuricomponent('pwinfobank') + '&from=' + encodeuricomponent(' ') + '&to_country=' + encodeuricomponent('82') + '&to=' + encodeuricomponent(' ') + '&message=' + encodeuricomponent('hello Infobank') + '&report_req=' + encodeuricomponent(1) }; var req = https.request(options); req.end(); var responsedata = ''; req.on('response', function(res){ res.on('data', function(chunk){ responsedata += chunk; }); res.on('end', function(){ console.log(responsedata); }); }); 9 / 14

10 3.4. Request Response format Request 에대한 Response 를통해전송요청에대한성공 / 실패여부를확인할수있으며, 단말기 도착여부는 Report 를통해확인할수있습니다. [M] Mandatory [O] Optional Parameter M/O TYPE Description msgid M Char 발송된메시지에부여되는메시지아이디 to_country M Char 국가코드 (1-3 byte) ex) 한국발송시, <to_country>82</to_country> to M Char 수신자번호 err_code M Char 메시지전송결과코드 messages cnt M Char 메시지건수 msg_type M Char 메시지타입 (1. SMS, 2. MMS) ex) MMS 로메시지발송된경우, <msg_type>2</msg_type> ref O Char 여분필드, 고객이설정할수있는필드값 - Request 에서설정한 ref 값전달 Request Response 예시 성공일경우 <?xml version='1.0' encoding='utf-8'?> <submit_response> <to_country>82</to_country> <to> </to> <messages cnt= 1 > <message> <msgid> </msgid> <err_code>r000</err_code> <msg_type>1</msg_type> </message> </messages> <ref>aa </ref> </submit_response> 실패일경우 <?xml version='1.0' encoding='utf-8'?> 10 / 14

11 <submit_response> <to_country>82</to_country> <to> </to> <messages cnt= 1 > <message> <err_code>r007</err_code> </message> </messages> <ref>aa </ref> </submit_response> err_code 부분은 4. 응답및결과코드 참조 3.5. Report Format Report는 GET방식으로클라이언트가제공한접속정보로결과값을전달합니다. [M] Mandatory [O] Optional Parameter M/O TYPE Description msgid M Char 발송된메시지에부여되는메시지아이디 to M Char 수신자번호 ( 국가코드를제외한수신번호 ) ex) to_country M Char 수신자국가코드 ex) 82 err_code M Char 리포트세부결과코드 network M Char Mobile network MCCMNC. (MCC : 국가코드, MNC : 이통사코드 ) ex) (SKT), (LGU+), (KT) rescnt M Char 실제메시지과금건수 *Concatenated Message 경우, 실제메시지과금된건수 sent_date O Char 단말기도착시간 - 한국표준시기준 : KST(UTC+9), YYYYMMDDHHMMSS ref O Char 여분필드, 클라이언트설정값 - request 에서설정한 ref 값전달 Report 예시 성공일경우?msgid = &to= &to_country=82&ref=AA &network=45008 &rescnt=1&err_code=1000&sent_date= / 14

12 실패일경우 - 단말기미수신시단말기도착시간 (sent_date) 을생략한다.?msgid= &to= &to_country=82&ref=AA &network=45008&resc nt=0&err_code=3001 자세한 err_code & status는 4.2 Report Return Code 참조 3.6. Report Response Format Report를수신을설정한클라이언트는인포뱅크가발송한 Report에대하여 Report Response를전송하여야합니다. Report Response가포맷과맞지않을경우인포뱅크는반복해서 Report를발송합니다. 리포트관련 IP/PORT 정보는 3.2 결과정보수신 참조 [M] Mandatory [O] Optional Parameter M/O TYPE Description msgid M Char 발송된메시지에부여되는메시지아이디 to_country M Char 국가코드 (1-3 byte) ex. 한국발송시, to_country=82 to M Char 수신자번호 Report Response 예시 <?xml version='1.0' encoding='utf-8'?> <report_response> <msgid> </msgid> <to_country>82</to_country> <to> </to> </report_response > 4. 응답및결과코드 4.1. Response Return Code Status code Description SUCCESS R000 성공 FAILURE R001 server busy 12 / 14

13 INVALID R002 인증실패 INVALID R003 수신자번호형식오류 INVALID R004 발신자번호형식오류 INVALID R005 메시지형식오류 INVALID R006 유효하지않은 TTL INVALID R007 유효하지않은파라미터오류 INVALID R008 스팸필터링 INVALID R009 서버 capacity 초과, 재시도요망 INVALID R010 등록되지않은발신번호사용 INVALID R011 발신번호변작방지기준위반발신번호사용 INVALID R012 해당서비스유형전송권한없음 INVALID R013 발송가능건수초과 UNKNOWN R999 알려지지않은에러 4.2. Report Return Code Status code Description SUCCESS 1000 성공 : 단말기에메시지정상도착 FAILURE 2000 전송시간초과 FAILURE 2001 전송실패 ( 무선망단 ) FAILURE 2002 전송실패 ( 무선망 -> 단말기단 ) FAILURE 2003 단말기전원꺼짐 FAILURE 2004 단말기메시지버퍼풀 FAILURE 2005 음영지역 FAILURE 2006 메시지삭제됨 FAILURE 2007 일시적인단말문제 INVALID 3000 전송할수없음 INVALID 3001 가입자없음 INVALID 3002 성인인증실패 INVALID 3003 수신번호형식오류 INVALID 3004 단말기서비스일시정지 INVALID 3005 단말기호처리상태 INVALID 3006 착신거절 INVALID 3008 기타단말기문제 INVALID 3009 메시지형식오류 INVALID 3010 MMS 미지원단말 INVALID 3011 서버오류 13 / 14

14 INVALID 3012 스팸 INVALID 3013 서비스거부 INVALID 3014 기타 INVALID 3015 전송경로없음 INVALID 3016 첨부파일사이즈제한실패 -발신번호변작방지세칙위반 -동보메시지전송시일부건세칙위반 INVALID 3018 휴대폰가입이동통신사를통해발신번호변작방지부가서비스에가입된번호를발신번호로사용하는경우 INVALID 3019 KISA or 미래부에서모든고객사에대하여차단처리요청된번호를발신번호로사용하는경우 INVALID 3022 Charset conversion error - 동보사용시국가코드 '82' 인경우, 건별인코딩오류처리 5. APPENDEX 5.1. Concatenated message 해외에서사용하는 160자이상의메시지를전송하기위한전송방식으로일부국가와통신사에서지원하며실제휴대폰에서는전체메시지가 1건으로보입니다. 한국의 LMS와유사하지만 Standard SMS 1건을기준글자수로하여글자수에따라요금이부과되는차이점이있습니다. 예 ) 160자가 Standard SMS인국가로 350자의메시지를전송할수있으며, 요금은 153자 +153자 +44자 = 350자로 3건의요금이부과됩니다. concatenated SMS 이용시긴문자처리를위한코드가포함되어 153자가 1건으로과금됩니다. 6. Contact Information 본문서와관련된기술문의는아래메일주소로연락주시면됩니다. support@infobank.net 14 / 14

Messaging Service SMPP API Specification V1.0.3 Last Modified: 23.July,

Messaging Service SMPP API Specification V1.0.3 Last Modified: 23.July, 2019 1 변경이력 버전 일자 내용 작성자 1.0.0 2016-05-26 최초작성 남궁희이정해 1.0.1 2016-10-07 submit_sm의 validity_period 절대시간지원추가 남궁희 1.0.2 2017-11-20 에러코드