REST 방식을 이용한 메시지 전송 API로 HTTPS 요청을 보낼 수 있는 모든 환경에서 자유롭게 연동하실 수 있습니다. 인증 토큰 사용으로 보안이 강화되었으며, JSON방식 지원으로 고객님의 서비스에 최적화된 메시지 시스템 구현이 가능 합니다.
한번의 연동으로 단건 메시지는 물론 대량 메시지, 국제 메시지, 이미지 첨부 메시지 등 다양한 형태의 메시지 전송이 지원됩니다.
REST API 연동에 대한 자세한 내용은 아래에서 확인하실 수 있으며, 연동 테스트 신청 및 서비스 이용 상담은 아래의 버튼을 눌러주세요.
REST API는 HTTPS 요청을 보낼 수 있는 환경이라면 어디에서든 이용할 수 있습니다.
모바일/PC 웹 환경에서 Javascript를 활용
다양한 환경의 웹서버에서의 활용(Java, Ruby, Python 등)
iOS, Android 등 다양한 모바일 환경에서 활용
HTTPS METHOD
전송 요청을 위해 HTTPS GET/POST 방식을 제공하며 전송 응답은 JSON 방식을 사용합니다.
ENCODING
UTF-8 인코딩을 기본으로 제공합니다.
한국으로 전송 시 UTF-8 인코딩을 사용하나 EUC-KR에서 제공하지 않는 글자 전송 시 메시지 전송이 실패할 수 있습니다.
TIMEZONE
본 API에 대한 기준 시간은 한국 표준 시 KST(UTC+9)를 사용합니다.
API 설명
인증(토큰 발급) API
- 서비스 이용 시 인증에 사용할 토큰을 발급 받기 위한 API입니다.
- 발급 시 만료 시간이 있으며 만료 시간(24시간) 후에는 사용이 불가하고 재발급이 필요합니다.
- 토큰이 외부로 노출될 경우 악용의 소지가 있으므로 유의 바랍니다
파일 업로드 API
- MMS 발송에 사용될 이미지 파일 업로드 API입니다.
- 파일 업로드 후 발급되는 파일 키 값을 사용 합니다.
- 파일 키 발급 시 만료 시간이 있으며 만료 시간(7일) 후에는 파일이 삭제됩니다.
메시지 전송 API
- 메시지 발송을 요청하는 API입니다.
리포트 API
- 메시지 전송 결과를 확인할 수 있는 API입니다.
*리포트를 수신 하기 위해서는 인포뱅크에서 제공하는 서버 IP에 대한 접근을 허용해야 합니다.
결과 송신 서버 IP 정보 : 211.233.70.215, 211.233.70.216
API URL 정보
API URL 정보
인증(토큰 발급) API |
https://auth.supersms.co:7000/auth/v3/token |
파일 업로드 API |
https://file.supersms.co:7010/sms/v3/file |
메시지 전송 API |
https://sms.supersms.co:7020/sms/v3/multiple-destinations |
리포트 API (PUSH) |
인포뱅크에 등록한 URL 정보 |
전세계 언어를 지원하기 위해 UTF-8 인코딩을 사용합니다.
TLS 프로토콜 1.2를 사용합니다.
인증(토큰 발급) API
- ID와 Password를 이용하여, API를 호출할 수 있는 토큰(Access Token)을 발급 받을 수 있습니다.
- X-IB-Client-Id : 인포뱅크를 통해 발급받은 ID
- X-IB-Client-Passwd : 인포뱅크를 통해 발급받은 Password
[Request]
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" https://auth.supersms.co:7000/auth/v3/token
[Response]
header
- Content-Type: application/json; charset=UTF-8
body
Response
Name |
TYPE |
필수 |
Desc |
accessToken |
Text |
Y |
인증 토큰 |
Schema |
Varchar(10) |
Y |
Basic |
expired |
Char(14) |
Y |
토큰 만료 시간 |
Response Sample (JSON)
{
"accessToken":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE0ODI4OTkxODksImF1ZCI6InJlc3R0ZXN0MSIsIm1tcyI6Ik4iLCJzbXMiOiJZIiwicmVwIjoiTiJ9.LEo0A411Yi0T7YDV7V8FGaD6DXzdlJ5TeVf_8d2h3JQ",
"schema":"Basic",
"expired":"20161228132629"
}
파일 업로드 API
- 파일을 업로드하여 MMS 전송 시 사용할 파일 키를 발급합니다.
- 파일은 확장자(jpg/jpeg), 해상도(최대2,000*2,000), 크기(300kbyte 이하) 제한이 있습니다.
- 요청 시 파일 업로드 수는 1개로 제한하며 분당 최대 30회 업로드 가능합니다.
- 파일명과 크기가 같은 이미지의 경우 1시간에 1건만 등록 할 수 있습니다.
(발급된 키는 만료 시간 전까지 재사용 가능합니다.)
- 만료일까지 파일 키를 사용할 수 있으며 만료일 후 파일은 삭제됩니다.
[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
https://file.supersms.co:7010/sms/v3/file
[Response]
header
- Content-Type: application/json; charset=UTF-8
body
Response
Name |
TYPE |
필수 |
Desc |
fileKey |
Varchar(40) |
Y |
파일 키 |
expired |
Char(14) |
Y |
파일 만료 시간 |
Response Sample (JSON)
{
"fileKey":"40e52b585d034a15922da1e8f845e244",
"expired":"20161228133909"
}
메시지 전송 API
- 한국 및 해외 휴대폰 번호로 메시지를 전송할 수 있습니다.
- 전송 요청 시 TPS 100내외 속도를 권장합니다.
- 1개의 메시지를 최대 200개의 수신번호로 발송 가능하며, 수신번호 별 치환 문구 는 5개까지 사용 가능합니다.
- 치환 문구 사용은 text(메시지 내용)에 예약어(%CHANGEWORD1% ~ %CHANGEWORD5%) 문구를 기입하고 수신자 정보로 치환할 수 있습니다.
예) text : %CHANGEWORD1%님의 결제금액 %CHANGEWORD2%원이 입금되었습니다.
- 수신번호 형식은 국제 표준 을 따릅니다.
예) +8210123456478, +8201012345678, 8210123456478, 8201012345678
- 수신번호에 ‘-‘ 가 포함 될 경우 ‘-‘ 는 제거 되어 처리되며 Response 또한 제거 되어 전달됩니다.
- 한국으로 장문 메시지를 보낼 경우 메시지 길이가 90byte를 초과하는 경우 LMS 로 발송됩니다.
- 해외로 장문 메시지를 보낼 경우 Concatenated SMS 로 발송됩니다.
- MMS는 한국만 지원하며 해외는 지원하지 않습니다.
- MMS 전송 시 FILE API를 통해 파일 키를 생성 한 후 키 값을 이용하여 전송합니다.
[Request]
method : POST
path : /sms/v3/multiple-destinations
header
- Authorization : {발급받은 schema + “ “ + 발급받은 accessToken}
- Content-Type : application/json
- Accept : application/json
body
Request
Name |
TYPE |
필수 |
Desc |
title |
Varchar(40) |
N |
메시지 제목 (최대 길이40byte)
- 메시지 제목은 UTF-8과 URL 인코딩 필요
- 한국 장문 발송 시에만 유효함 |
from |
Varchar(16) |
Y |
발신번호 (최대 길이16byte)
ex) 한국 발송 시 01029652189 (국가코드 미포함)
해외 발신 시 821029652189 (국가코드 포함)
|
text |
Varchar(4000) |
Y |
메시지 내용 |
fileKey |
Varchar(100) |
N |
MMS 발송 시 파일 키 |
destinations |
text |
Y |
수신번호 그룹 |
to |
Varchar(16) |
Y |
수신번호 (국제표준)
ex) 한국 발송 시 821029652189 |
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 |
여분 필드, 고객이 설정할 수 있는 필드 값
(최대 길이 200byte, 영/숫자만 가능) |
ttl |
Int |
N |
메시지 유효 시간(초 단위)
Default:86400
ex) ttl=86400 (24hour = 60 * 60 * 24) |
paymentCode |
Varchar(20) |
N |
정산용 부서코드 (최대 길이 20byte) |
clientSubId |
Varchar(20) |
N |
Sender ID , 메시지 서명 을 복수로 지정하기 위한 구분자 (최대 길이 20byte) |
originCID |
Varchar(9) |
N |
최초 발신사업자 식별코드 |
Request Sample (cURL)
curl -X POST
-H "Authorization:Basic eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE0ODI4 …"
-H "Accept: application/json"
-H "content-type: application/json"
-d
'{"title":"title1","from":"02000000","text":"text1","fileKey":"","destinations":[{"to":"+821012341234","replaceWord1":"","replaceWord2":"","replaceWord3":"","replaceWord4":"","replaceWord5":""}],"ref":"ref1","ttl":"100","paymentCode":"1","clientSubId":"1"}'
https://sms.supersms.co:7020/sms/v3/multiple-destinations
[Response]
header
- Content-Type: application/json; charset=UTF-8
body
Response
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":"20170101A0001103437883143398",
"toCount":"1",
"destinations":[{"messageId":"20170101A0001103437883143398-0",
"to":"+821012341234",
"status":"R000",
"errorText":""}],
"ref":"ref1"
}
리포트 API (PUSH)
- PUSH 방식 : 메시지 전송 요청을 하고, 전송 결과를 비동기로 응답 받는 방식입니다.
- 리포트 수신을 위해 인포뱅크에서 제공하는 서버 IP에 대한 접근을 허용해야 하며 리포트를 수신할 고객사측IP/PORT 에 대한 정보는 영업담당자에게 접수해야 합니다.
- 수신 받을 서버 네트워크 구간에 방화벽 허용이 필요합니다.
- 전송 API를 통해 발송한 메시지에 대해 message Id 기준으로 사용자가 제공한 접속 정보로 결과값을 전달합니다.
- 인포뱅크가 등록된 URL을 통해 하단 규격과 같은 Request를 보냅니다.
- 리포트 정보를 수신하면 하단 규격과 같은 Response를 주어야 합니다. Response가 없거나 포맷과 맞지 않을 경우 반복해서 전달합니다.
- Response가 없을 경우 3회 재 시도 후 전달을 멈추며 리포트 정보는 보관되지 않습니다.
- 1일 최대 설정 횟수 전달 실패 시 리포트 전달을 멈추며 리포트 정보는 보관되지 않고 다음날 메시지 발송 분부터 다시 전달 재개합니다. (최대 시도 횟수 : 1,000 , 서버 부하에 따라 변경 될 수 있음)
- 고객 설정 값(ref)은 URL인코딩이 적용되어 있으므로 URL디코딩이 필요합니다.
- 설정한 계정에 한하여 국제메시지는 DLR 정보를 수신 받을 수 있습니다. 설정을 원하는 경우 영업담당자에게 접수해야 합니다.
- 리포트 종류 ‘0: 최종결과’로 과금 여부가 결정되며, 리포트 종류 ‘3: DLR정보’는 과금과 무관한 단순 참고용 정보 입니다.
[Request]
method : GET
ppath : 인포뱅크에 등록한 URL 정보
Accept : application/json
URL parameter
Request
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 |
고객 설정 값 |
resultType |
Char(1) |
N |
리포트 종류(0: 최종결과, 3: DLR정보) |
Request Sample (cURL)
curl -X GET "인포뱅크에 등록한 URL?groupId=20170728094323718A0217797718&messageId=20170728094323718A0217797718-0
&messageType=0&requestTime=2017-07-28+09%3A43%3A23&to=%2B821094890890&from=0316281614
&resultCode=1000&errorText&reportTime=2017-07-28+09%3A43%3A26&carrier=10002&resCnt=1&ref=ref1"
[Response]
header
- Content-Type: application/json; charset=UTF-8
body
Response
Name |
TYPE |
필수 |
Desc |
messageId |
Varchar(35) |
Y |
메시지 아이디 |
to |
Varchar(16) |
Y |
수신번호 |
Response Sample (JSON)
{
"messageId":"20170101A0001103437883143398-0",
"to":"+821012341234"
}
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로 15882460과 같은 숫자 뿐만 아니라 Korea와 같은 문자열을 사용할 수 있습니다.
타 서비스를 사칭하거나 스팸 메시지를 차단하기 위해 기업이나 서비스 고유의 문자열을 해외 통신사에 미리 등록하고 메시지를 전송하도록 하는 경우가 있으며, 대표적인 예로 인도네시아, 인도, 필리핀, 태국 등이 있습니다. 상세한 정보는 영업 담당자를 통해 확인 가능하며 통상 등록에 2주~4주 정도 소요됩니다.
고객이 서비스 별, 국가 별로 다양한 Sender ID를 구분하여 전송하기 어려운 경우 clientSubId 필드로 구분자를 보내 주시면 당사에서 각 SubId 별로 원하는 Sender ID를 전송해 줄 수 있습니다.
본 사항은 영업담당자와 사전 협의가 필요합니다.
메시지 서명
해외로 메시지를 전송하는 경우 타 서비스 사칭이나 스팸 메시지를 차단하기 위해 메시지 내용에 메시지 전송자의 서비스명이나 회사명을 식별할 수 있는 내용을 반드시 삽입하도록 하는 경우가 있습니다. 이를 ‘메시지 서명’이라고 하며 사전 등록이 필요합니다. 중국이 대표적인 국가이며 【INFO中国】과 같은 형태로 문자 내용 맨 앞에 삽입해야 합니다.
고객이 서비스 별, 국가 별로 다른 메시지 내용을 전송하기 어려운 경우 clientSubId 필드로 구분자를 보내 주시면 당사에서 각 SubId 별로 원하는 ‘메시지 서명’을 메시지 내용에 삽입하여 전송해 줄 수 있습니다. 본 사항은 영업담당자와 사전 협의가 필요합니다.
최초 발신사업자 식별코드(originCID)
인터넷 문자 전송 시 최초 발신사업자를 특정하기 위해 삽입하는 식별코드이며, 특수한 유형의 부가통신사업자 등록번호(9자리 숫자)를 사용합니다.
최초 발신사업자가 재판매사업자이면 최초 재판매사업자 등록번호가 수록되고, 재판매사업자를 통하지 않고 문자중계사로 발송할 경우 문자중계사의 등록번호가 수록됩니다.
예1) 기업 → 재판매사업자1 → 재판매사업자 2 → 문자중계사 → 이동통신사
: 재판매사업자1의 등록번호가 삽입
예2) 기업 → 문자중계사 → 이동통신사
: 문자중계사의 등록번호가 삽입
기술지원 상담