단 몇초만의 클라우드

알림톡 서비스 API 규격서

IWINV 알림톡 REST API 규격서 입니다.

알림톡 발송

템플릿

전송 결과

잔액 조회

알림톡 발송

기본정보

HEADERS

Content-Type

AUTH

application/json;charset=UTF-8

base64_encode ( API Key )

알림톡 발송

알림톡의 발송 가능 문자수는 한/영 구분 없이 1,000자까지 발송 가능합니다.

반드시 변수 포함 1,000자 이내로 작성해주셔야 합니다.

발신번호는 '발신번호 관리'에서 등록된 번호여야 합니다.

URL

POST	https://biz.service.iwinv.kr/api/send/

BODY

{

"templateCode": "10030",

"reserve": "Y",

"sendDate": "2021-07-20 05:00:00",

"reSend": "Y",

"resendCallback": "01000000000",

"resendType": "Y",

"resendTitle": "smstitle",

"resendContent": "smscontent",

"list":

[

{

"phone": "01012341234",

"templateParam": ["11","2","3"]

{

"phone": "01012341235",

"templateParam": ["1","2","3"]

{

"phone": "01012341236",

"templateParam": ["1","2","3"]

}

]

}

값	타입	필수	설명	예시
templateCode	String	O	사용 가능한 템플릿 코드	10001
reserve	String	X (기본 N)	예약발송 여부(N:즉시발송, Y:예약발송)	Y , N
sendDate	String	X	발송 시각(예약 발송인 경우 필수, 예약 발송은 현재 시간 15분 이후 한달 이전까지만 가능합니다.)	yyyy-MM-dd HH:mm:ss
reSend	String	X (기본 N)	알림톡 발송 실패 시 대체 문자 전송 기능(Y:대체 발송, N:대체 발송 없음)	Y , N
resendCallback	String	X	발신번호	010-0000-0000 혹은 01000000000
resendType	String	X (기본 Y)	대체 발송 내용 타입 (Y:알림톡 내용, N:직접 입력)	Y , N
resendTitle	String	X	실패 시 LMS 대체 문자 제목	-
resendContent	String	X	실패 시 대체 문자 내용(대체 발송 내용 타입 직접 입력 시 필수)	SMS(90Bytes 이하) / LMS(91~2000 Bytes)
list	Array	O	수신자 리스트(최대 1000명)	-
- phone	Array	O	수신번호	010-0000-0000 혹은 01000000000
- templateParam	Array	X	템플릿 변수(템플릿 내용 중 치환할 항목(변수) 포함 시 필수)	[["항목1","항목2","항목3"],["항목1","항목2","항목3"]]

응답

{

"code": 200,

"message": "메시지가 발송되었습니다",

"success": 3,

"fail": 1

}

값	타입	설명
code	Integer	응답 코드
message	String	응답 코드 결과 메시지
success	Integer	정상적으로 전송 요청된 연락처 개수
fail	Integer	전송 요청되지 않은 연락처 개수

-- 맨 위로 --

템플릿

기본정보

HEADERS

Content-Type

AUTH

application/json;charset=UTF-8

base64_encode ( API Key )

템플릿 리스트

등록된 템플릿 목록을 조회합니다.

URL

POST	https://biz.service.iwinv.kr/api/template/

BODY

{

"pageNum": "1",

"pageSize": "15",

"templateCode": "10030",

"templateName": "test1",

"templateStatus": "R"

}

값	타입	필수	설명	예시
pageNum	Integer	X	페이지 번호(기본:1)	1
pageSize	Integer	X	조회 건수(기본:15, 최대:1000)	10
templateCode	String	X	템플릿 코드	10001
templateName	String	X	템플릿 이름	템플릿 이름
templateStatus	String	X	템플릿 상태 코드(Y:사용가능, I:검수중, R:부결(반려))	Y

응답

{

"code": 200,

"message": "정상적으로 호출하였습니다.",

"totalCount": 2,

"list":

[

{

"templateCode": "10036",

"templateName": "알림",

"templateContent": "#{이름} 고객님 우리 회사와 거래하여주셔서 감사합니다.",

"status": "Y",

"createDate": "2021-06-21 10:01:31",

"buttons":

[

{

"ordering": null,

"name": "iwinv",

"linkType": "WL",

"linkTypeName": "웹링크",

"linkMo": "https://www.iwinv.kr/board/notice/read.html?branch=NEWS&idx=#{idx}",

"linkPc": "https://www.iwinv.kr/board/notice/read.html?branch=NEWS&idx=#{idx}",

"linkIos": null,

"linkAnd": null

}

]

}

]

}

값	타입	설명
code	Integer	응답 코드
message	String	응답 코드 결과 메시지
totalCount	Integer	등록된 템플릿 총 개수
list	JSON	템플릿 리스트
- templateCode	String	템플릿 코드
- templateName	String	등록된 템플릿 명
- templateContent	String	등록된 템플릿 내용
- status	String	상태(Y:사용가능, I:검수중, R:부결(반려))
- createDate	String	사용 가능 일시
- buttons	Array	템플릿 버튼 정보
-- ordering	String	버튼 순서(1~5)
-- name	String	버튼명
-- linkType	String	버튼 타입(WL:웹링크, AL:앱링크, DS:배송조회, BK:봇키워드, MD:메시지전달)
-- linkTypeName	String	버튼 타입명
-- linkMo	String	모바일 웹 링크(WL)
-- linkPc	String	PC 웹 링크(WL)
-- linkIos	String	IOS 앱링크(AL)
-- linkAnd	String	안드로이드 앱링크(AL)

템플릿 생성

알림톡은 미리 지정한 템플릿만 사용 가능합니다.

한/영 구분 없이 띄어쓰기 포함 1,000자까지 발송 가능합니다.

템플릿 검수 기간은 2~3 영업일 소요되며, 신청한 내용에 따라 더 걸릴 수 있습니다.

URL

POST	https://biz.service.iwinv.kr/api/template/add/

BODY

{

"templateName": "템플릿명",

"templateContent": "템플릿 내용",

"buttons":

[

{

"type": "WL",

"name": "웹링크",

"linkMo": "https://www.iwinv.kr/board/notice/read.html?branch=NEWS&idx=#{idx}",

"linkPc": "https://www.iwinv.kr/board/notice/read.html?branch=NEWS&idx=#{idx}"

{

"type": "AL",

"name": "앱링크",

"linkIos": "https://www.iwinv.kr/board/notice/read.html?branch=NEWS&idx=#{idx}",

"linkAnd": "https://www.iwinv.kr/board/notice/read.html?branch=NEWS&idx=#{idx}"

{

"type": "DB",

"name": "배송조회"

{

"type": "BK",

"name": "봇 키워드"

{

"type": "MD",

"name": "메시지 전달"

}

]

}

값	타입	필수	설명	예시
templateName	String	O	템플릿명(최대 15자)	템플릿명
templateContent	String	O	템플릿 내용(최대1000자)	가변 항목은 #{항목} 형태로 최대 10개까지 등록이 가능합니다.
buttons	JSON	X	템플릿 버튼(최대 5개)	-
- type	String	X	버튼 타입	WL:웹링크, AL:앱링크, DB:배송조회, BK:봇 키워드, MD:메시지 전달
- name	String	X	버튼 이름(버튼이 있는 경우 필수, 최대 15자)	-
- linkMo	String	X	모바일 웹 링크(WL 타입일 경우 필수, 최대200자)	http:// 또는 Https://
- linkPc	String	X	PC 웹 링크(WL 타입일 경우 필수, 최대200자)	http:// 또는 Https://
- linkIos	String	X	IOS 앱 링크(AL 타입일 경우 필수, 최대200자)	-
- linkAnd	String	X	Android 앱 링크(AL 타입일 경우 필수, 최대200자)	-

응답

{

"code": 200,

"message": "정상적으로 템플릿을 생성하였습니다."

}

값	타입	설명
code	Integer	응답 코드
message	String	응답 코드 결과 메시지

템플릿 수정

템플릿 상태가 부결인 경우, 템플릿 내용을 수정해서 재 검수 요청을 하실 수 있습니다.

URL

POST	https://biz.service.iwinv.kr/api/template/modify/

BODY

{

"templateCode": "10031",

"templateName": "템플릿명",

"templateContent": "템플릿 내용",

"buttons":

[

{

"type": "WL",

"name": "웹링크",

"linkMo": "https://www.iwinv.kr/board/notice/read.html?branch=NEWS&idx=#{idx}",

"linkPc": "https://www.iwinv.kr/board/notice/read.html?branch=NEWS&idx=#{idx}"

{

"type": "AL",

"name": "앱링크",

"linkIos": "https://www.iwinv.kr/board/notice/read.html?branch=NEWS&idx=#{idx}",

"linkAnd": "https://www.iwinv.kr/board/notice/read.html?branch=NEWS&idx=#{idx}"

{

"type": "DB",

"name": "배송조회"

{

"type": "BK",

"name": "봇 키워드"

{

"type": "MD",

"name": "메시지 전달"

]

}

값	타입	필수	설명	예시
templateCode	String	O	템플릿 코드	-
templateName	String	O	템플릿명(최대15자)	-
templateContent	String	O	템플릿 내용(최대 1000자)	-
buttons	JSON	X	템플릿 버튼(최대 5개)	-
- type	String	X	버튼 타입	WL:웹링크, AL:앱링크, DB:배송조회, BK:봇 키워드, MD:메시지 전달
- name	String	X	버튼 이름(버튼이 있는 경우 필수, 최대 15자)	-
- linkMo	String	X	모바일 웹 링크(WL 타입일 경우 필수, 최대200자)	http:// 또는 Https://
- linkPc	String	X	PC 웹 링크(WL 타입일 경우 필수, 최대200자)	http:// 또는 Https://
- linkIos	String	X	IOS 앱 링크(AL 타입일 경우 필수, 최대200자)	-
- linkAnd	String	X	Android 앱 링크(AL 타입일 경우 필수, 최대200자)	-

응답

{

"code": 200,

"message": "정상적으로 템플릿을 생성하였습니다."

}

값	타입	설명
code	Integer	응답 코드
message	String	응답 코드 결과 메시지

템플릿 삭제

불필요한 템플릿을 삭제해도 완전히 삭제된 것이 아닌 카카오 서버에 데이터가 남아있습니다.

템플릿 삭제 후 삭제된 동일한 템플릿명은 사용이 불가합니다.

URL

POST	https://biz.service.iwinv.kr/api/template/delete/

BODY

{

"templateCode": "10036"

}

값	타입	필수	설명	예시
templateCode	String	O	템플릿 코드	-

응답

{

"code": 200,

"messgae": "선택하신 템플릿이 삭제되었습니다."

}

값	타입	설명
code	Integer	응답 코드
message	String	응답 코드 결과 메시지

-- 맨 위로 --

전송 결과

기본정보

HEADER

Content-Type

AUTH

application/json;charset=UTF-8

base64_encode ( API Key )

전송 내역 조회

조회 시작일을 지정하여 조회하실 수 있습니다.

시작일 입력하지 않은 경우 오늘 기준 7일 전 전송 내역이 조회됩니다.

URL

URL	https://biz.service.iwinv.kr/api/history/

BODY

{

"pageNum": "1",

"pageSize": "15",

"reserve": "N",

"startDate": "2021-04-05",

"endDate": "2021-06-23",

"seqNo": "17",

"phone": "010-0123-0123"

}

값	타입	필수	설명	예시
pageNum	Integer	X	페이지 번호(기본:1)	1
pageSize	Integer	X	조회 건수(기본:15, 최대:1000)	10
reserve	String	X	예약발송 여부(N:즉시발송, Y:예약발송)	Y , N
startDate	String	X	발송 요청 시작일자(yyyy-MM-dd HH:mm:ss)	2021-01-01 13:00:00
endDate	String	X	발송 요청 마감일자(yyyy-MM-dd HH:mm:ss)	2021-01-01 13:00:00
seqNo	Integer	X	메시지 ID	-
phone	String	X	수신번호	010-0000-0000 혹은 01000000000

응답

{

"code": 200,

"totalCount": 1,

"message": "데이터가 조회되었습니다.",

"list":

[

{

"seqNo": 17,

"phone": "01000000000",

"callback": "16884879",

"templateCode": "10034",

"sendMessage": "홍길동 운영 중인 사이트에 문제가 발생하였습니다",

"reserve": "N",

"requestDate": "2021-06-23 15:22:39",

"sendDate": "2021-06-23 15:22:40",

"receiveDate": "2021-06-23 15:22:50",

"statusCode": "OK",

"statusCodeName": "성공",

"resendStatus": null,

"resendStatusName": null,

"buttons": {

"link1": null,

"link2": null,

"link3": null,

"link4": null,

"link5": null

}

]

}

값	타입	설명
code	Integer	응답 코드(200:조회 성공)
totalCount	Integer	전송 메시지 총 개수
message	String	응답 코드 결과 메시지
list	Array	전송 목록
- seqNo	String	메시지 ID
- phone	String	수신번호
- callback	String	발신번호
- templateCode	String	템플릿 코드
- sendMessage	String	전송한 메시지
- reserve	String	예약발송 여부(N:즉시발송, Y:예약발송)
- requestDate	String	요청일
- sendDate	String	전송일
- receiveDate	String	수신일
- statusCode	String	알림톡 발송 요청 상태 코드
- statusCodeName	String	알림톡 발송 요청 상태 코드명
- resendStatus	String	대체 발송 상태 코드
- resendStatusName	String	대체 발송 상태 코드명
- buttons	Array	버튼 내용

예약 문자 취소

예약 취소는 발송 예정시간 15분 이전의 문자만 가능합니다.

URL

URL	https://biz.service.iwinv.kr/api/cancel/

BODY

{

"seqNo": "17"

}

값	타입	필수	설명	예시
seqNo	Array	O	메시지ID	-

응답

{

"code": 200,

"message": "알림톡 예약 발송이 삭제되었습니다."

}

값	타입	설명
code	Integer	응답 코드
message	String	응답 코드 결과 메시지

-- 맨 위로 --

잔액 조회

기본정보

HEADER

Content-Type

AUTH

application/json;charset=UTF-8

base64_encode ( API Key )

잔액 조회

자동 결제(충전)된 요금에서 메시지 발송 후 남은 금액과 메시지 발송 실패 시 반환된 금액의 합계입니다.

URL

URL	https://biz.service.iwinv.kr/api/charge/

응답

{

"code": 200,

"message": "데이터가 조회되었습니다.",

"charge": 10000.0

}

값	타입	설명
code	Integer	응답 코드(200:조회 성공)
message	String	응답 코드 결과 메시지
charge	Float	잔액

-- 맨 위로 --