REST API - 직관적이고 보안이 강화된 Rest API를 통해 여러분의 서비스에 최적화된 메시지 시스템을 설계해 보세요.

기술정보센터

REST API

REST 방식을 이용한 메시지 전송 API로 HTTPS 요청을 보낼 수 있는 모든 환경에서 자유롭게 연동하실 수 있습니다. 인증 토큰 사용으로 보안이 강화되었으며, JSON방식 지원으로 고객님의 서비스에 최적화된 메시지 시스템 구현이 가능 합니다. 한번의 연동으로 단건 메시지는 물론 대량 메시지, 국제 메시지, 이미지 첨부 메시지 등 다양한 형태의 메시지 전송이 지원됩니다.

REST API 연동에 대한 자세한 내용은 아래에서 확인하실 수 있으며, 연동 테스트 신청 및 서비스 이용 상담은 아래의 버튼을 눌러주세요.


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
- 서비스 이용 시 인증에 사용할 토큰을 발급 받기 위한 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 정보

API 상세

전세계 언어를 지원하기 위해 UTF-8 인코딩을 사용합니다.

인증(토큰 발급) 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), 해상도(최대2000*2000), 크기(300kbyte 이하) 제한이 있습니다.
- 요청 시 파일 업로드 수는 1개로 제한하며 분당 최대 30회 업로드 가능합니다.
- 파일명과 크기가 같은 이미지의 경우 1시간에 1건만 등록 할 수 있습니다.
(발급된 키는 만료 시간 전까지 재사용 가능합니다.)
- 만료일까지 파일 키를 사용할 수 있으며 만료일 후 파일은 삭제됩니다.
- 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
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

- 한국 및 해외 휴대폰 번호로 메시지를 전송할 수 있습니다.
- 1개의 메시지를 최대 200개의 수신번호로 발송 가능하며, 수신번호 별 치환 문구 는 5개까지 사용 가능합니다.
- 치환 문구 사용은 text(메시지 내용)에 예약어(%CHANGEWORD1% ~ %CHANGEWORD5%) 문구를 기입하고 수신자 정보로 치환할 수 있습니다.
예) text : %CHANGEWORD1%님의 결제금액 %CHANGEWORD2%원이 입금되었습니다.
- 수신번호 형식은 국제 표준 을 따릅니다.
예) +8210123456478, +8201012345678, 8210123456478, 8201012345678
- 한국으로 장문 메시지를 보낼 경우 메시지 길이가 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(40) 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 여분 필드, 고객이 설정할 수 있는 필드 값
(최대 길이 20byte, 영/숫자만 가능)
ttl Int Y 메시지 유효 시간(초 단위)
ex) ttl=86400 (24hour = 60 * 60 * 24)
paymentCode Varchar(20) N 정산용 부서코드 (최대 길이 20byte)
clientSubId Varchar(20) N Sender ID , 메시지 서명 을 복수로 지정하기 위한 구분자 (최대 길이 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":"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":"20170101A00011034378831433983",
"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일 최대 설정 횟수 전달 실패 시 리포트 전달을 멈추며 리포트 정보는 보관되지 않고 다음날 메시지 발송 분부터 다시 전달 재개합니다. (최대 시도 횟수 : 1000 , 서버 부하에 따라 변경 될 수 있음)
- 고객 설정 값(ref)은 URL인코딩이 적용되어 있으므로 URL디코딩이 필요합니다.

[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) Y 고객 설정 값

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"
}

응답 및 결과 코드

API Response 결과 코드

API Response 결과 코드
구분 Http
Status
Error
Code
Error Text Desc
공통 400 A100 Authentication failed 인증 실패
401 A110 Expired token 만료된 토큰
403 A111 Invalid token 토큰 권한 없음
500 A900 Service check 서비스 점검
500 A999 Unknown error 알려지지 않은 에러
500 M999 Unknown error 알려지지 않은 에러
500 R999 Unknown error 알려지지 않은 에러
인증 401 A200 Invaild authentication information 잘못된 인증정보
403 A210 Blocked account 차단된 계정
403 A211 Blocked account 차단된 계정
403 A212 Number of unsuccessful attempts exceeded 인증 실패 횟수 초과 (10회)
SMS 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 등록되지 않은 발신번호
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 exceeded 1분 이내 업로드 건수 초과(30건)
403 A412 Number of file exceeded 업로드 개수 초과(1개)
400 A413 Wrong request 잘못된 요청
500 A414 Failed to process image file 이미지 파일 처리 실패

API Response 수신번호 별 결과 코드

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 네트워크 에러

Report 전송 결과 코드

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
첨부파일 사이즈 제한 실패
-발신번호 변작 방지 세칙 위반
-동보 메시지 전송 시 일부 건 세칙 위반
INVALID 3018 Unregistered Sender ID
*For messages sent to Korea only
휴대폰 가입 이동통신사를 통해 발신번호 변작 방지 부가 서비스에 가입된 번호를 발신번호로 사용하는 경우
INVALID 3019 Invalid Sender ID format
*For messages sent to Korea only
KISA or 미래부에서 모든 고객사에 대하여 차단 처리 요청된 번호를 발신번호로 사용하는 경우

참고사항

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 별로 원하는 ‘메시지 서명’을 메시지 내용에 삽입하여 전송해 줄 수 있습니다. 본 사항은 영업담당자와 사전 협의가 필요합니다.

Download(REST API)

기술지원 상담

iMessage 메시지개발팀

김인곤/매니저  Email ingony@Infobank.net

Back to top
  • 상담요청하기
  • CONTACT US
  • FAQ
  • 상담 게시판