Messaging Service REST API Specification V1.0.5 Last Modified: 19 March,

Size: px

Start display at page:

Download "Messaging Service REST API Specification V1.0.5 Last Modified: 19 March,"

우재덕 내
5 years ago
Views:

1 Messaging Service REST API Specification V1.0.5 Last Modified: 19 March,

2 변경이력 버전 일자 내용 작성자 최초작성 최호철 동보메시지최대건수 (200건) 내용추가 최호철 서비스점검코드추가 (A900) 임정훈 리포트송신서버정보추가 임정훈 메시지전송 API Request 절 from 항목설명변경 임정훈 리포트 carrier 설명추가, ref 필수여부변경, 샘플내용수정 임정훈 리포트결과송신서버 IP 변경 임정훈 리포트재시도규격변경 임정훈 결과코드제거 (Callback URL을받을수없는폰 ) 제거 rescnt 추가, carrier 타입변경 3.2.2, 인증정보 (Authorization) 설명변경 임정훈 임정훈 2 / 17

3 목차 1. 개요 개발환경구성 전문규격 API 리스트 API 설명 API URL 정보 API 상세 인증 ( 토큰발급 ) API... 5 [Request]... 5 [Response] 파일업로드 API... 6 [Request]... 7 [Response] 메시지전송 API... 8 [Request]... 8 [Response] 리포트 API (PUSH) [Request] [Response] 응답및결과코드 API RESPONSE 결과코드 API RESPONSE 수신번호별결과코드 REPORT 전송결과코드 부록 CONCATENATED SMS SENDER ID 메시지서명 문의 / 17

4 1. 개요 인포뱅크에서제공하는 HTTPS 방식을이용해문자메시지를전송하는메시지전송 API(REST API) 입니다. 본규격을이용하여국내 / 외메시징서비스를이용할수있습니다. 본서비스를이용하기위해서영업담당자로부터접속정보를제공받아야합니다. 2. 개발환경구성 REST API는 HTTPS 요청을보낼수있는환경이라면어디에서든이용할수있습니다. 모바일 /PC 웹환경에서 Javascript를활용다양한환경의웹서버에서의활용 (Java, Ruby, Python 등 ) ios, Android 등다양한모바일환경에서활용 3. 전문규격 HTTPS METHOD - 전송요청을위해 HTTPS GET/POST 방식을제공하며전송응답은 JSON 방식을사용합니다. ENCODING - UTF-8 인코딩을기본으로제공합니다. - 한국으로전송시 UTF-8 인코딩을사용하나 EUC-KR에서제공하지않는글자전송시메시지전송이실패할수있습니다. TIMEZONE - 본 API에대한기준시간은한국표준시 KST(UTC+9) 를사용합니다 API 리스트 API 설명 4 / 17

5 인증 ( 토큰발급 ) API - 서비스이용시인증에사용할토큰을발급받기위한 API입니다. - 발급시만료시간이있으며만료시간 (24시간) 후에는사용이불가하고재발급이필요합니다. - 토큰이외부로노출될경우악용의소지가있으므로유의바랍니다. 파일업로드 API - MMS 1 발송에사용될이미지파일업로드 API입니다. - 파일업로드후발급되는파일키값을사용합니다. - 파일키발급시만료시간이있으며만료시간 (7일) 후에는파일이삭제됩니다. 메시지전송 API - 메시지발송을요청하는 API 입니다. 리포트 API - 메시지전송결과를확인할수있는 API 입니다. * 리포트를수신하기위해서는인포뱅크에서제공하는서버 IP 에대한접근을허용해야합니다. 결과송신서버 IP 정보 : , API URL 정보 인증 ( 토큰발급 ) API 파일업로드 API 메시지전송 API 리포트 API (PUSH) 인포뱅크에등록한 URL 정보 3.2. API 상세 전세계언어를지원하기위해 UTF-8 인코딩을사용합니다 인증 ( 토큰발급 ) API ID와 Password를이용하여, API를호출할수있는토큰 (Access Token) 을발급받을수있습니다. X-IB-Client-Id : 인포뱅크를통해발급받은 ID X-IB-Client-Passwd : 인포뱅크를통해발급받은 Password [Request] 1 Multimedia Messaging Service : 이미지를전송할수있는메시지타입으로한국으로전송하는경우에만사용할수있습니다. 5 / 17

6 method : POST path : /auth/v3/token header - Accept : application/json - X-IB-Client-Id : ID - X-IB-Client-Passwd : Password Request Sample (curl) curl -X POST -H "X-IB-Client-Id:ID" -H "X-IB-Client-Passwd:Password" -H "Accept: application/json" [Response] header - Content-Type: application/json; charset=utf-8 body Name Type 필수 Desc accesstoken Text Y 인증토큰 schema Varchar(10) Y Basic expired Char(14) Y 토큰만료시간 Response Sample (JSON) { "accesstoken":"eyj0exaioijkv1qilcjhbgcioijiuzi1nij9.eyjlehaioje0odi4otkxodksimf1zci6in Jlc3R0ZXN0MSIsIm1tcyI6Ik4iLCJzbXMiOiJZIiwicmVwIjoiTiJ9.LEo0A411Yi0T7YDV7V8FGaD6DXzdl J5TeVf_8d2h3JQ", "schema":"basic", "expired":" " } 파일업로드 API 파일을업로드하여 MMS 전송시사용할파일키를발급합니다. 6 / 17

7 파일은확장자 ( jpg/jpeg), 해상도 ( 최대2000*2000), 크기 (300kbyte 이하 ) 제한 2 이있습니다. 요청시파일업로드수는 1개로제한하며분당최대 30회업로드가능합니다. 파일명과크기가같은이미지의경우 1시간에 1건만등록 3 할수있습니다. - 발급된키는만료시간전까지재사용가능합니다. 만료일까지파일키를사용할수있으며만료일후파일은삭제됩니다. SSL TLS1.2를사용하여업로드합니다. [Request] method : POST path : /sms/v3/file header - Authorization : { 발급받은 schema + + 발급받은 accesstoken} - Content-Type : multipart/form-data; boundary= 구분값 - Accept : application/json Request Sample (curl) curl -X POST -H "Authorization:Basic eyj0exaioijkv1qilcjhbgcioijiuzi1nij9.eyjlehaioje0odi4 " -F filedata=@/data/test.jpg [Response] header - Content-Type: application/json; charset=utf-8 body Name Type 필수 Desc filekey Varchar(40) Y 파일키 expired char(14) Y 파일만료시간 Response Sample (JSON) { 2 국내통신사에서수용할수있는첨부파일이미지사양입니다. 3 동일한파일의불필요한업로드를막고공격을차단하기위한보안정책입니다. 7 / 17

8 } "filekey":"40e52b585d034a15922da1e8f845e244", "expired":" " 메시지전송 API 한국및해외휴대폰번호로메시지를전송할수있습니다. 1개의메시지를최대 200개의수신번호로발송가능하며, 수신번호별치환문구 4 는 5개까지사용가능합니다. 치환문구사용은 text( 메시지내용 ) 에예약어 (%CHANGEWORD1% ~ %CHANGEWORD5%) 문구를기입하고수신자정보로치환할수있습니다. 예 ) text : %CHANGEWORD1% 님의결제금액 %CHANGEWORD2% 원이입급되었습니다. 수신번호형식은국제표준 5 을따릅니다. 예 ) , , , 한국으로장문메시지를보낼경우메시지길이가 90byte를초과하는경우 LMS 6 로발송됩니다. 해외로장문메시지를보낼경우 Concatenated SMS 7 로발송됩니다. MMS는한국만지원하며해외는지원하지않습니다. MMS 전송시 FILE API를통해파일키를생성한후키값을이용하여전송합니다. [Request] method : POST path : /sms/v3/multiple-destinations header - Authorization : { 발급받은 schema + + 발급받은 accesstoken} - Content-Type : application/json - Accept : application/json body Name Type 필수 Desc title Varchar(40) N 메시지제목 ( 최대길이 40byte) 4 전송할메시지내용에서수신번호별로변경할수있는문구를말합니다. 5 [+][ 국가번호 ][ 수신번호 ] 예 ) Long Message Service : 최대 2000byte까지전송할수있는장문메시지로한국에서만사용할수있습니다. 7 긴메시지내용을분할하여발송후휴대폰에서하나의메시지로표출하는방식입니다. (5. 부록참조 ) 8 / 17

9 - 메시지제목은 UTF-8 과 URL 인코딩필요 - 한국장문발송시에만유효함 from Varchar(16) Y 발신번호 ( 최대길이 16byte) ex) 한국발송시 ( 국가코드미포함 ) 해외발신시 ( 국가코드포함 ) text Varchar(4000) Y 메시지내용 filekey Varchar(40) N MMS 발송시파일키 destinations text Y 수신번호그룹 to Varchar(16) Y 수신번호 ( 국제표준 ) ex) 한국발송시 replaceword1 Varchar(20) N 치환문구 1 replaceword2 Varchar(20) N 치환문구 2 replaceword3 Varchar(20) N 치환문구 3 replaceword4 Varchar(20) N 치환문구 4 replaceword5 Varchar(20) N 치환문구 5 ref Varchar(200) N 여분필드, 고객이설정할수있는필드값 ( 최대길이 20byte, 영 / 숫자만가능 ) ttl Int Y 메시지유효시간 ( 초단위 ) ex) ttl=86400 (24hour = 60 * 60 * 24) paymentcode Varchar(20) N 정산용부서코드 ( 최대길이 20byte) clientsubid Varchar(20) N Sender ID 8, 메시지서명 9 을복수로지정하기위한구분자 ( 최대길이 20byte) Request Sample (curl) curl -X POST -H "Authorization:Basic eyj0exaioijkv1qilcjhbgcioijiuzi1nij9.eyjlehaioje0odi4 " -H "Accept: application/json" -H "content-type: application/json" -d '{"title":"title1","from":" ","text":"text1","filekey":"","destinations":[{"to":" ","replaceWord1":"","replaceWord2":"","replaceWord3":"","replaceWord4":"","replaceWord 5":""}],"ref":"ref1","ttl":"100","paymentCode":"1","clientSubId":"1"}' 8 한국의발신번호개념과동일하며숫자뿐만아니라문자열로표현가능한발신번호를포함합니다. 본기능은여러 Sender ID를 1개의 API를이용해해외로발송시각서비스별로 Sender ID를지정할수있도록하는구분자입니다. (5. 부록참조 ) 9 해외로메시지전송시일부국가의경우메시지내용에발신자의서비스명, 회사명을식별할수있는이름을삽입해야하며이를 메시지서명 이라고합니다. (5. 부록참조 ) 9 / 17

10 [Response] header - Content-Type: application/json; charset=utf-8 body Name Type 필수 Desc groupid char(28) Y 메시지그룹아이디 tocount Int Y 수신번호요청건수 destinations text Y 수신번호그룹 messageid Varchar (35) Y 메시지아이디 to Varchar(16) Y 수신번호 status Char(4) Y 처리상태 errortext Varchar(255) N 에러내용 ref Varchar(200) Y 고객설정값 Response Sample (JSON) { } "groupid":" a ", "tocount":"1", "destinations":[{"messageid":" a ", "to":" ", "status":"r000", "errortext":""}], "ref":"ref1" 리포트 API (PUSH) PUSH 방식 - 메시지전송요청을하고, 전송결과를비동기로응답받는방식입니다. 리포트수신을위해인포뱅크에서제공하는서버 IP에대한접근을허용해야하며리포트를수신할고객사측 IP/PORT 에대한정보는영업담당자에게접수해야합니다. 수신받을서버네트워크구간에방화벽허용이필요합니다. 전송 API를통해발송한메시지에대해 message Id 기준으로사용자가제공한접속정보로결과값을전달합니다. 10 / 17

11 인포뱅크가등록된 URL을통해하단규격과같은 Request를보냅니다. 리포트정보를수신하면하단규격과같은 Response를주어야합니다. Response가없거나포맷과맞지않을경우반복해서전달합니다. Response가없을경우 3회재시도후전달을멈추며리포트정보는보관되지않습니다. 1일최대설정횟수전달실패시리포트전달을멈추며리포트정보는보관되지않고다음날메시지발송분부터다시전달재개합니다. ( 최대시도횟수 : 1000, 서버부하에따라변경될수있음 ) 고객설정값 (ref) 은 URL인코딩이적용되어있으므로 URL디코딩이필요합니다. [Request] method : GET path : 인포뱅크에등록한 URL 정보 Accept : application/json URL parameter Name Type 필수 Desc groupid char(28) Y 메시지그룹아이디 messageid Varchar(35) Y 메시지아이디 messagetype Char(1) Y 메시지타입 ( 수신번호가국내일경우해당 ) (0-SMS 2-MMS, 3-LMS) requesttime datetime Y 고객발송요청시간 to Varchar(16) Y 수신번호 from Varchar(16) Y 발신번호 resultcode Char(4) Y 발송결과코드 errortext Varchar(255) N 에러내용 reporttime datetime Y 리포트수신시간 carrier Int(5) N 착신망정보 ( 수신번호가한국일경우해당 ) 10001(SKT) 10002(KT) 10003(LGU+) 10000(ETC) : 일반수신번호 10010(Safety number) : 050 번호 10006(Internet number) : 인터넷, 기타번호 (070 번호 ) rescnt Int(5) Y 실제메시지과금건수 *Concatenated Message 경우, 실제메시지과금된건수 ref Varchar(200) N 고객설정값 11 / 17

12 Request Sample (curl) curl -X GET " 인포뱅크에등록한 URL?groupId= A &messageId= A &messageType=0&requestTime= %3A43%3A23&to=%2B &from= &resultCode=1000&errorText &reporttime= %3a43%3a26&carrier=10002&rescnt=1&ref=ref1" [Response] header - Content-Type: application/json; charset=utf-8 body Name Type 필수 Desc messageid Varchar(35) Y 메시지아이디 to Varchar(16) Y 수신번호 Response Sample (JSON) { } "messageid":" a ", "to":" " 12 / 17

13 4. 응답및결과코드 4.1. API Response 결과코드 구분공통인증 SMS Http Error Status Code Error Text Desc 400 A100 Authentication failed 인증실패 401 A110 Expired token 만료된토큰 403 A111 Invalid token 토큰권한없음 500 A900 Service check 서비스점검 A999 Unknown error 알려지지않은에러 500 M999 Unknown error 알려지지않은에러 500 R999 Unknown error 알려지지않은에러 401 A200 Invaild authentication information 잘못된인증정보 403 A210 Blocked account 차단된계정 403 A211 Blocked account 차단된계정 Number of unsuccessful attempts 403 A212 exceeded 인증실패횟수초과 (10 회 ) 400 A300 No Client ID Client ID 없음 400 A301 Incorrect Sender ID format 발신자번호형식오류 400 A302 Invalid message format 메시지형식오류 400 A303 Invalid TTL 유효하지않은 TTL 400 A304 Invalid REF REF 형식오류 400 A305 Invalid PAYMENTCODE PAYMENTCODE 형식오류 400 A306 Invalid CLIENT SUB ID CLIENT SUB ID 형식오류 400 A307 No recipient 수신번호없음 발송가능한수신번호 400 A308 Number of recipients exceeded 수 (200 건 ) 초과 400 A309 Wrong request 잘못된요청 400 M004 Incorrect Sender ID format 발신자번호형식오류 400 M005 Invalid message format 메시지형식오류 400 M006 Invalid TTL 유효하지않은 TTL 400 M008 Spam filtering 스팸필터링 400 M010 Unregistered Sender ID 등록되지않은발신번호 10 서비스점검이나패치시서버의종료전요청에대한응답코드로해당코드발생시서버종료시점에 connection error 가 발생할수있습니다. 13 / 17

14 파일 400 M011 Violated the Sender ID by Korean low 발신번호변작방지기준위반 (Korea message only) 발신번호 400 M014 Failed to process image file 이미지파일처리실패 400 M015 Invalid image file key 유효하지않은이미지파일키 400 M101 Invalid message format 메시지형식오류 400 A400 Oversize attached file 파일크기초과 400 A401 Overlength the image title 이미지명길이초과 400 A402 Invalid file 사용할수없는파일 400 A403 Image resolution exceeded 이미지해상도초과 403 A410 Duplicated upload within 1 hour 1 시간이내중복업로드 403 A411 Number of upload request within 1 min 1 분이내업로드건수 exceeded 초과 (30 건 ) 403 A412 Number of file exceeded 업로드개수초과 (1 개 ) 400 A413 Wrong request 잘못된요청 500 A414 Failed to process image file 이미지파일처리실패 4.2. API Response 수신번호별결과코드 Status Error text Desc R000 Success 성공 R001 Server busy 일시적서비스장애 R002 Verification failed 인증실패 R003 Incorrect recipients format 수신번호형식오류 R007 Invalid parameter error 유효하지않은파라미터오류 R009 Server capacity exceeded. Please retry 서버 capacity 초과, 재시도요망 R012 No right to send the pertinent service type 해당서비스유형전송권한없음 R013 Exceeded the maximum number of messages that can be sent 발송가능건수초과 R999 Unknown error 알려지지않은에러 R102 Invalid Recipient Phone Number 유효하지않은수신번호 R103 Network error 네트워크에러 14 / 17

15 4.3. Report 전송결과코드 Status Code Result text Desc SUCCESS 1000 Success 성공 : 단말기에메시지정상도착 FAILURE 2000 Timeout 전송시간초과 FAILURE 2001 Failed to send 전송실패 ( 무선망단 ) FAILURE 2002 Failed to send 전송실패 ( 무선망 -> 단말기단 ) FAILURE 2003 The handset is turned off 단말기전원꺼짐 FAILURE 2004 The handset message is full 단말기메시지버퍼풀 FAILURE 2005 Shadow area 음영지역 FAILURE 2006 The message has been deleted 메시지삭제됨 FAILURE 2007 Temporary handset problem 일시적인단말문제 INVALID 3000 Unable to deliver 전송할수없음 INVALID 3001 No subscriber 가입자없음 INVALID 3002 Age verification failed. 성인인증실패 INVALID 3003 Invalid recipients format 수신번호형식오류 INVALID 3004 Handset service suspended temporarily 단말기서비스일시정지 INVALID 3005 Handset call processing state 단말기호처리상태 INVALID 3006 Declining incoming calls 착신거절 INVALID 3008 Other handset problems 기타단말기문제 INVALID 3009 Invalid message format 메시지형식오류 INVALID 3010 Handset doesn t support MMS MMS 미지원단말 INVALID 3011 Server error 서버오류 INVALID 3012 Spam 스팸 INVALID 3013 Service denial 서비스거부 INVALID 3014 Others 기타 INVALID 3015 No transmission path 전송경로없음 INVALID 3016 Oversize attached file Unregistered Sender ID 첨부파일사이즈제한실패 -발신번호변작방지세칙위반 *For messages sent to Korea only -동보메시지 11 전송시일부건세칙위반 휴대폰가입이동통신사를통해발신번호 Unregistered Sender ID INVALID 3018 변작방지부가서비스에가입된번호를 *For messages sent to Korea only 발신번호로사용하는경우 11 동일한내용의메시지를복수의수신자에게동시에전송하는기능을의미합니다. 15 / 17

16 INVALID 3019 Invalid Sender ID format *For messages sent to Korea only KISA or 미래부에서모든고객사에대하여 차단처리요청된번호를발신번호로 사용하는경우 5. 부록 5.1. Concatenated SMS 해외는국가별통신규격에따라 SMS 길이만지원하는경우도있고국내의 LMS와비슷하게긴문자메시지를지원하기도합니다. 이를 Concatenated SMS라고칭하며긴문자 (Concatenated SMS) 를전송하시는경우최대전송가능길이는일반적으로다음과같으며요금은기본 SMS 길이의배수로과금됩니다. 메시지길이가기본메시지길이인 160자 ( 현지어 70자 ) 를초과하는경우 - 알파벳 / 숫자전송시 153자단위로과금 : 153자 * 5건 = 최대 765자 - 현지어전송시 67자단위로과금 : 67자 * 5건 = 최대 335자 알파벳, 숫자, 특수문자, 띄어쓰기모든언어의한글자가 1글자입니다 Sender ID 메시지발신자정보로서단말기에서메시지수신시보내는사람영역에표현되는숫자 / 문자를 Sender ID라고합니다. 해외일부국가 / 통신사의경우 Sender ID로 과같은숫자뿐만아니라 Korea와같은문자열을사용할수있습니다. 타서비스를사칭하거나스팸메시지를차단하기위해기업이나서비스고유의문자열을해외통신사에미리등록하고메시지를전송하도록하는경우가있으며, 대표적인예로인도네시아, 인도, 필리핀, 태국등이있습니다. 상세한정보는영업담당자를통해확인가능하며통상등록에 2주 ~4주정도소요됩니다. 고객이서비스별, 국가별로다양한 Sender ID를구분하여전송하기어려운경우 clientsubid 필드로구분자를보내주시면당사에서각 SubId 별로원하는 Sender ID를전송해줄수있습니다. 본사항은영업담당자와사전협의가필요합니다 메시지서명 해외로메시지를전송하는경우타서비스사칭이나스팸메시지를차단하기위해메시지내용에메시지전송자의서비스명이나회사명을식별할수있는내용을반드시삽입하도록하는경우가있습니다. 이를 메시지서명 이라고하며사전등록이필요합니다. 중국이대표적인국가이며 16 / 17

17 INFO 中国 과같은형태로문자내용맨앞에삽입해야합니다. 고객이서비스별, 국가별로다른메시지내용을전송하기어려운경우 clientsubid 필드로구분자를보내주시면당사에서각 SubId 별로원하는 메시지서명 을메시지내용에삽입하여전송해줄수있습니다. 본사항은영업담당자와사전협의가필요합니다. 6. 문의 본문서와관련된기술문의는아래메일주소로연락주시면됩니다. support@infobank.net 17 / 17

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

변경이력 버전 일자 내용 작성자 최초작성 한은경 v.1.1 문서변경 한은경 v.1.2 문서변경 한은경 v1.3 문서변경 한은경 Messaging Service HTTP API Specification V2.3.5 Last Modified: 15.November, 2017 1 변경이력 버전 일자 내용 작성자 1.0.0 2014-10-16 최초작성 한은경 1.1.0 2014-11-13 v.1.1 문서변경 한은경 1.2.0 2014-11-14 v.1.2 문서변경 한은경 1.3.0 2014-11-19