REST 방식을 이용한 메시지 전송 API로 HTTPS 요청을 보낼 수 있는 모든 환경에서 자유롭게 연동하실 수 있습니다. 인증 토큰 사용으로 보안이 강화되었으며, JSON방식 지원으로 고객님의 서비스에 최적화된 메시지 시스템 구현이 가능 합니다.
한번의 연동으로 단건 메시지는 물론 대량 메시지, 국제 메시지, 이미지 첨부 메시지 등 다양한 형태의 메시지 전송이 지원됩니다.
REST API 연동에 대한 자세한 내용은 아래에서 확인하실 수 있으며, 연동 테스트 신청 및 서비스 이용 상담은 아래의 버튼을 눌러주세요.
REST API는 HTTPS 요청을 보낼 수 있는 환경이라면 어디에서든 이용할 수 있습니다.
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 | 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)
[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)
파일 업로드 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)
[Response]
header
- Content-Type: application/json; charset=UTF-8
body
| Name | TYPE | 필수 | Desc |
|---|---|---|---|
| fileKey | Varchar(40) | Y | 파일 키 |
| expired | Char(14) | Y | 파일 만료 시간 |
Response Sample (JSON)
메시지 전송 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
| 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)
[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)
리포트 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
| 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)
[Response]
header
- Content-Type: application/json; charset=UTF-8
body
| Name | TYPE | 필수 | Desc |
|---|---|---|---|
| messageId | Varchar(35) | Y | 메시지 아이디 |
| to | Varchar(16) | Y | 수신번호 |
Response Sample (JSON)
API Response 결과 코드
| 구분 | Http Status |
Error Code |
Error Text | Desc |
|---|---|---|---|---|
| 공통 | 400 | A100 | Authentication failed | 인증 실패 |
| 401 | A110 | Expired token | 만료된 토큰 | |
| 403 | A111 | Invalid token | 토큰 권한 없음 | |
| 400 | A112 | Cannot parse JSON | JSON을 구문 분석 할 수 없음 | |
| 400 | A113 | Cannot mapping JSON | JSON을 매핑 할 수 없음 | |
| 429 | A114 | Rate limit exceeded | Ratelimit(TPS) 초과 | |
| 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 | A310 | Number of filekey exceeded | 첨부 가능한 파일 키 수(3건) 초과 | |
| 400 | A311 | Invalid Transfer Time | 유효하지 않는 전송 시간 | |
| 400 | A351 | Invalid originCID | 유효하지 않은 식별코드 | |
| 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 | M016 | Invalid Transfer Time | 유효하지 않는 전송 시간 | |
| 400 | M017 | Duplicated Message within 24 hour | 24시간 이내 중복 발송 | |
| 400 | M022 | Invalid originCID | 유효하지 않은 식별코드 | |
| 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 수신번호 별 결과 코드
| 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 | 네트워크 에러 |
| R104 | Invalid Transfer Time | 유효하지 않는 전송 시간 |
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 | 첨부파일 사이즈 제한 실패 |
| 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 미래부에서 모든 고객사에 대하여 차단 처리 요청된 번호를 발신번호로 사용하는 경우 |
| INVALID | 3022 | Charset conversion error | 문자 인코딩 에러 |
| INVALID | 3025 | Duplicated Message within 24 | 24시간 이내 중복 발송 |
| INVALID | 3029 | Sent at ad blocking time | 광고 전송 제한 시간 발송 |
| INVALID | 3034 | Invalid MMS Mt File Key | Invalid MMS Mt File Key |
| INVALID | 3035 | Unable to send due to carrier failure setting | 해당 통신사 장애 설정 으로 전송 불가 |
| INVALID | 3036 | Invalid originCID | KISA 최초 발신자 식별코드 오류로 발송 불가 |
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) 기업 → 문자중계사 → 이동통신사
: 문자중계사의 등록번호가 삽입
기술지원 상담
Email support@infobank.net
