API 매뉴얼
문자메시지 발송 전 준비사항
1. 발신번호 사전등록 동의서 / 발신번호 운영 담당자 등록 신청서
2. 운영 담당자 재직증명서
3. 통신서비스 이용증명원 (가입된 통신사에서 발급 가능)
4. 사업자 등록증 혹은 법인 등록증
A. 법인: 사업자등록증, 법인 등기부등본
B. 개인: 사업자등록증, 대표자 신분증 사본
API 계정 신청
1. API 사용 신청: (API 사용 신청 바로가기)
2. 신청 정보 확인 및 승인 (VIATOK 관리자)
3. API 계정 추가 신청: (API 계정 추가 바로가기)
4. 생성된 API 계정에 카카오톡 발신 프로필 혹은 문자메시지 발신 번호 등록: (발신번호 등록 바로가기)
5. API 연동 및 사용
API 명세서
[Request 공통]
URL | https://www.viatok.co.kr/kakao/v1_2/{METHOD} |
---|---|
HTTP Method | POST |
Post Type | JSON |
Content Type | application/json; charset=utf-8 |
Request / Response Type | JSON |
HTTP Referer | 계정 신청 당시 등록한 접속 도메인 (cURL, Socket 등 접속 시 명시 필요) |
API 인증 값 | 비아톡 로그인 ID, API ID, API 암호 키 |
* VIATOK 계정 정보 확인: (VIATOK 계정 정보 확인 바로가기) * API 계정 정보 확인: (API 계정 정보 확인 바로가기) |
[Request Header]
Referer | 비아톡 API 계정 생성 시 등록된 "접속 도메인" |
---|---|
api_site_id | 비아톡 로그인 ID |
api_api_id | 생성된 API ID |
api_api_pw | 생성된 API 암호 KEY |
* VIATOK 계정 정보 확인: (VIATOK 계정 정보 확인 바로가기) * API 계정 정보 확인: (API 계정 정보 확인 바로가기) |
[Request Body]
1. 단일 행 전송 함수: JSON 객체 형식으로 전송
2. 다중 행 전송 함수: JSON 객체 배열 형식으로 전송
[Response Body]
{
status: 200, ** 응답 HTTP Status code와 동일
code: "success", ** 6. 별첨 상태 코드 값
message: "정상 처리", ** 6. 별첨 상태 메시지 값
requested: {
url: "https://www.viatok.co.kr/kakao/v1_2/{함수명}", ** 요청 URL
method: "POST", ** 요청 타입
header.data: {
api_site_id: "{비아톡 ID}", ** VIATOK ID
api_api_id: "{API 접속 계정 ID}" ** VIATOK ID 혹은 API ID
** API 암호 접속 키(Passphrase)는 회신하지 않음.
},
body.data: [
** 요청 본문 (JSON): 각 기능 별 Request Parameter 반환 (검증)
]
},
response: {
** 응답 본문 (JSON): 각 기능 별 Response Parameter
** 처리 에러 시 에러메시지 해당 영역에 기재되어 반환
}
}
API 계정 기능
API 계정 신청 및 정보 확인 URL: https://www.viatok.co.kr/api_guide/add.php
[Request URL]
https://www.viatok.co.kr/kakao/v1_2/SEND_MESSAGE_ALARM
[Description]
Ver. 1.0.0의 SEND_MESSAGE_KAKAO, SEND_MESSAGE_FRIEND, MESSAGE_SEND 통합
* 구형 함수 사용 필요할 경우 https://www.viatok.co.kr/kakao/{함수명} URL로 요청
* 구형 함수는 버그 수정 외 업데이트 예정 없으므로 최신버전 함수 사용 권장
[Request Parameters (JSON Array)]Post Data (*: 필수 항목)
변수명 | 자료형 | 설명 |
---|---|---|
* TYPE | CHAR(3) | 발송 타입 |
* USER_KEY | VARCHAR(20) | 고객사 발급 Key (중복 불허) |
* RECEIVE | 전화번호 배열 형식 | 수신자 전화번호 |
* SEND_MSG | VARCHAR(80, 1000, 2000) | 전송 본문 |
문자 메시지 공통 변수 | ||
MESSAGE_RESERVE | (연월일시분초, 기호없이) | 예약 발송 시간 |
* MESSAGE_CALLBACK | 전화번호형식 | 발신전화번호 |
[Request Payload Example (JSON Array)]
[
{ ** SMS
USER_KEY: "sms_210910_151010_0002",
TYPE: "SMS",
RECEIVE: ["010-0000-0000"],
SEND_MSG: "안녕하세요.\nSMS 발신 테스트 입니다.",
MESSAGE_RESERVE: "210911120000", ** 예약발송일시
MESSAGE_CALLBACK: "010-0000-0000"
}, { ** LMS
USER_KEY: "lms_210910_151010_0002",
TYPE: "LMS",
RECEIVE: ["010-0000-0000"],
SEND_MSG: "안녕하세요.\nLMS 발신 테스트 입니다.",
MESSAGE_CALLBACK: "010-0000-0000"
}
]
[Response (JSON Array) ]
USER_KEY | 고객 입력 Key (중복 등록 불가) |
---|---|
VIATOK_KEY | VIATOK 발급 Key |
TYPE | 전송 타입 |
FLAG | 성공 및 실패 여부 |
MESSAGE | 성공 및 실패 사유 (Array) |
TRANSFER |
전환 발송 여부KAKAO_FAIL_TRANSFER 값과 상관 없이 전환 여부 응답 * KAKAO_FAIL_TRANSFER = N이면 무조건 N으로 응답 * KAKAO_FAIL_TRANSFER = Y이며 전환 발송 안한 경우 N으로 응답 * KAKAO_FAIL_TRANSFER = Y에 전환 발송 시도한 경우 Y로 응답 |
TRANSFER_KEY | 전환 발송 Key * 전환 발송 성공 시 발송 Key 응답 |
전환 발송 관련 응답값 안내
정상 발송 시 * 발송 성공(전환 발송 상관하지 않음), 발송 실패(전환 발송 안함) | |
---|---|
FLAG | SUCC / FAIL / ERRO (성공, 실패, 에러) |
TYPE | Request의 TYPE |
VIATOK_KEY | Request의 TYPE에 해당하는 응답 Key |
TRANSFER_KEY | (공백) |
TRANSFER | N |
전환 발송 성공 시 * 발송 실패, 전환 발송 성공 | |
FLAG | TRAN (전환 발송) |
TYPE | Request의 KAKAO_FAIL_TYPE |
VIATOK_KEY | Request의 KAKAO_FAIL_TYPE에 해당하는 응답 Key |
TRANSFER_KEY | Request의 TYPE에 해당하는 응답 Key |
TRANSFER | Y |
전환 발송 실패 시 * 발송 실패, 전환 발송 실패 | |
FLAG | FAIL (전환 발송 실패) |
TYPE | Request의 TYPE |
VIATOK_KEY | Request의 TYPE에 해당하는 응답 Key |
TRANSFER_KEY | Request의 KAKAO_FAIL_TYPE에 해당하는 응답 Key |
TRANSFER | Y |
[Request Payload Example (JSON Array)]
response: [
{
USER_KEY: "sms_210910_151010_0002",
VIATOK_KEY: "{VIATOK 발급 Key}",
FLAG: "SUCC",
TYPE: "SMS",
TRANSFER: "N",
TRANSFER_KEY: "",
MESSAGE: ["요청이 정상적으로 완료 되었습니다."]
}, {
USER_KEY: "lms_210910_151010_0002",
VIATOK_KEY: "{VIATOK 발급 Key}",
FLAG: "SUCC",
TYPE: "LMS",
TRANSFER: "N",
TRANSFER_KEY: "",
MESSAGE: ["요청이 정상적으로 완료 되었습니다."]
}
]
전송 내역
[Request URL]
https://www.viatok.co.kr/kakao/v1_2/LOOKUP
[Request Parameters (JSON)]Post Data (*: 필수 항목)
변수명 | 자료형 | 설명 |
---|---|---|
DATE_START | VARCHAR(19), YYYY-MM-DD HH:mm:SS |
검색 시작 일시 (기본 1달 전) |
DATE_END | 검색 종료 일시 (기본 현재) | |
SEARCH_TYPE | CHAR(3) | 전송 타입 |
SEARCH_MESSAGE | VARCHAR(100) | 전송 본문 |
SEARCH_RECEIVER | VARCHAR(16) | 수신자 전화번호 |
SEARCH_USER_KEY | VARCHAR(100) | 전송 키 |
SEARCH_RESULT | VARCHAR(5), “TRUE”, “FALSE”, “” |
전송 결과 |
PAGE | INT | 현재 페이지 number |
PER_PAGE | INT | 페이지당 표출 count |
* 검색시작일시 ~ 검색종료일시는 최장 1년 범위까지 요청 가능 |
[Request Payload Example (JSON)]
{
DATE_START: "2022-01-01 00:00:00", ** 검색 시작 일시
DATE_END: "2022-01-31 23:59:59", ** 검색 종료 일시
SEARCH_TYPE: "SMS", ** 전송 타입
SEARCH_MESSAGE: "메세지 본문내용", ** 본문 내용 (일부)
SEARCH_RECEIVER: "010-0000-0000", ** 수신자 전화번호
SEARCH_USER_KEY: "sms_test", ** 전송 키(일부)
SEARCH_RESULT: "TRUE", ** 전송 결과
PAGE: 1, ** 현재 페이지 번호 1 ~
PER_PAGE: 100, ** 페이지당 조회할 개수
}
[Response Parameters (JSON)]
COUNT_FULL | 전체 조회 개수 |
---|---|
COUNT_SEARCH | 현재 조회 개수 |
PAGE_END | 전체 페이지 수 |
PAGE_NOW | 현재 페이지 번호 |
DATA (JSON Array) | 조회된 데이터 상세 내용 (Array) |
DATA 하위 속성 | |
USER_KEY | 전송 키 |
REQ_TYPE | 요청 전송 타입 |
REAL_TYPE | 실제 처리된 전송 타입 |
REQUESTED_DATE | 요청 일시 |
RESULT_FLAG | 처리 결과 |
MESSAGE | 전송 본문 |
RECEIVER | 수신자 전화번호 |
[Response Payload Example (JSON Array)]
response: {
COUNT_FULL: 22, ** 조건에 맞는 전체 결과 개수
COUNT_SEARCH: 10, ** 현재 페이지 내용 개수
PAGE_END: 3, ** 총 페이지 수
PAGE_NOW: 1, ** 현재 페이지 번호
DATA: [ ** 전송 내용 Array
{ ** 전송 내용 Array row
USER_KEY: "sms_test_send_1234", ** 전송 시 입력된 Key
REQ_TYPE: "SMS", ** 요청 전송 방식
REAL_TYPE: "SMS", ** 실제 전송 방식 (전환 발송 시 변경)
REQUESTED_DATE: "2022-01-05 12:34:56", ** 요청 시간
RESULT_FLAG: "SUCC",
** 전송 결과 SUCC(성공) / FAIL(실패) / TRAN(전환 발송, 성공)
MESSAGE: "전송된 메세지 본문내용 입니다.", ** 전송 본문
RECEIVER: "01000000000" ** 수신자 전화번호, - 없음
}, …
]
}
VIATOK 계정 기능
VIATOK 사용 신청 및 정보 확인 URL: https://www.viatok.co.kr/api_guide/reg.php
포인트 조회
[Request URL]
https://www.viatok.co.kr/kakao/v1_2/GET_POINT_INFO
[Request Parameters]
없음
[Response Parameters (JSON)]
REMAIN_POINT | 잔여 포인트 |
---|---|
ALT_POINT | 알림톡 1건당 비용 |
FRT_POINT | 친구톡 1건당 비용 |
SMS_POINT | SMS 1건당 비용 |
LMS_POINT | LMS 1건당 비용 |
MMS_POINT | MMS 1건당 비용 (홈페이지 전용) |
MSG_COUNT_PER_DAY | 문자메시지 1일 전송 제한 횟수 (0: 무제한) |
TALK_COUNT_PER_DAY | 카카오톡 1일 전송 제한 횟수 (0: 무제한) |
[Response Payload Example (JSON)]
response: {
REMAIN_POINT: "{잔여 포인트}",
ALT_POINT: "{알림톡 1건당 비용}",
FRT_POINT: "{친구톡 1건당 비용}",
SMS_POINT: "{SMS 1건당 비용}",
LMS_POINT: "{LMS 1건당 비용}",
MMS_POINT: "{MMS 1건당 비용}",
MSG_COUNT_PER_DAY: "{문자메시지 1일 발송 제한 횟수}",
TALK_COUNT_PER_DAY: "{카카오톡 1일 발송 제한 횟수}"
}
API 계정 목록 조회
[Request URL]
https://www.viatok.co.kr/kakao/v1_2/VIATOK_GET_ACCOUNT_LIST
[Request Parameters (JSON)]
SEARCH_API_ID | API ID로 검색 |
---|---|
SEARCH_ALLOW_IP | 등록 도메인으로 검색 |
SEARCH_USER_STATUS | API 계정 상태로 검색 (0: 신청 중, 1: 정상, 2: 사용 정지, 99: 삭제 대기) |
[Request Payload Example (JSON)]
{
SEARCH_API_ID: "{API ID, 생략 가능}",
SEARCH_ALLOW_IP: "{등록 도메인, 생략 가능}",
SEARCH_USER_STATUS: "{계정 상태, 생략 가능}",
}
[Response Parameters (JSON Array)]
API_ID | API 계정 ID |
---|---|
ALLOW_IP | API 접속 도메인 |
USER_STATUS | API 계정 상태 |
USE_KAKAO | 카카오톡 발신 프로필이 계정에 등록되어 있는지 여부 |
USE_MESSAGE | 발신 번호가 계정에 등록되어 있는지 여부 |
[Response Payload Example (JSON Array)]
response: [
{
API_ID: "{계정 ID}",
ALLOW_IP: "{접속 도메인}",
USER_STATUS: "{계정 상태}",
USE_KAKAO: "{카카오톡 발신 가능 여부}",
USE_MESSAGE: "{문자메시지 발신 가능 여부}"
},
** 생성된 API 계정 중 입력한 조건에 부합하는 만큼 반복
]
API 포인트 사용 내역 조회
[Request URL]
https://www.viatok.co.kr/kakao/v1_2/USE_LOG_POINT
[Request Parameters (JSON)]
ORDERING | 표출 정/역순 구분 |
---|---|
PAGE | 페이지 번호 |
PER_PAGE | 페이지당 노출 개수 |
POINT_IO_TYPE | 충전 및 사용 검색 구분 * I: 충전, O: 사용 |
DATE_START | 검색 시작일 |
DATE_END | 검색 종료일 |
[Request Payload Example (JSON)]
{
ORDERING: "{표출 정/역순 구분}",
PAGE: "{페이지 번호}",
PER_PAGE: "{페이지당 노출 개수, 생략 가능}",
POINT_IO_TYPE: "{충전 / 사용 구분, 생략 가능}",
DATE_START: "{검색 시작일, 생략 가능}",
DATE_END: "{검색 종료일, 생략 가능}",
}
[Response Parameters (JSON)]
POINT_IO_TYPE | 포인트 사용 및 충전 구분 |
---|---|
POINT_CHANGE | 포인트 변경 양 (차감된 포인트 or 충전된 포인트) |
DATETIME | 변동 시간 |
TITLE | 변동 사유 |
ORDER_NO | VIATOK 발급 키 값 |
[Response Payload Example (JSON)]
response: {
POINT_IO_TYPE: "{충전/사용 구분}",
POINT_CHANGE: "{변동 포인트 양(충전량 혹은 소모량)}",
DATETIME: "{변동 발생 일시}",
TITLE: "{변동 사유}",
ORDER_NO: "{VIATOK 발급 키 값}"
}
자주 하는 질문
HTTP Referer
* 참고 URL: https://datatracker.ietf.org/doc/html/rfc7231#section-5.5.2
VIATOK API Request시 Header에 Referer값이 정의되어 있어야 합니다.
원래 Referer값은 하이퍼링크를 통해서 방문시 이전 URL을 담는 헤더값이지만,
VIATOK API에서는 고객의 접속 HOST값으로 판단합니다.
요청하시는 방식 혹은 언어에 따라 Referer값이 자동으로 포함되어 요청되거나 누락될 수도 있습니다.
Referer값이 누락되거나 등록된 값(접속 도메인)과 상이하게 요청이 오는 경우
API 서버는 HTTP 403 Forbidden (fail_auth_fail_002)를 반환합니다.
VIATOK API에서 Referer와 비교하는 값은 API 계정 신청 시 등록하신 "접속 도메인" 값입니다. (IP형식도 허용, www.는 생략 가능)
* https://www.viatok.co.kr/api_guide/add.php
* https://www.viatok.co.kr/api_guide/reg.php
JSON, JSON Array
요청 및 응답 처리 시, 각 함수의 Request Parameter 및 Response Parameter에 명시된 JSON, JSON Array 구분을 확인해 주세요.
JSON(객체 형식)
Key - Value 형식으로 이루어진 JSON Object * 중괄호로 감싸진 JSON 데이터
** 단일 행 (JSON) 예시
{
KEY: "{String Value}",
KEY2: Integer Value
}
JSON Array(객체 배열 형식)
한 개 이상의 JSON Object로 구성된 배열(Array) * 대괄호로 감싸진 JSON 데이터
** 다중 행 (JSON Array) 예시
[
{
KEY: "{String Value}",
KEY2: Integer Value
}, {
KEY3: "{String Value}",
KEY4: Integer Value
}
]
카카오톡 발송 전 준비사항
1. 카카오톡 플러스친구 생성 및 비즈니스 승인 완료
A. 카카오톡채널 관리자 센터: https://center-pf.kakao.com
B. 비즈니스: https://center-pf.kakao.com/{프로필아이디}/settings/verification
C. 관리자: https://center-pf.kakao.com/{프로필아이디}/settings/managers
D. 프로필아이디: 카카오社에서 부여하는 채널 별 난수 값
2. 플러스친구에 관리자로 등록된 전화번호로 토큰 발급 요청
API 계정 신청
1. API 사용 신청: (API 사용 신청 바로가기)
2. 신청 정보 확인 및 승인 (VIATOK 관리자)
3. API 계정 추가 신청: (API 계정 추가 바로가기)
4. 생성된 API 계정에 카카오톡 발신 프로필 혹은 문자메시지 발신 번호 등록: (카카오톡 발신 프로필 바로가기)
5. API 연동 및 사용
API 명세서
[Request 공통]
URL | https://www.viatok.co.kr/kakao/v1_2/{METHOD} |
---|---|
HTTP Method | POST |
Post Type | JSON |
Content Type | application/json; charset=utf-8 |
Request / Response Type | JSON |
HTTP Referer | 계정 신청 당시 등록한 접속 도메인 (cURL, Socket 등 접속 시 명시 필요) |
API 인증 값 | 비아톡 로그인 ID, API ID, API 암호 키 |
* VIATOK 계정 정보 확인: (VIATOK 계정 정보 확인 바로가기) * API 계정 정보 확인: (API 계정 정보 확인 바로가기) |
[Request Header]
Referer | 비아톡 API 계정 생성 시 등록된 "접속 도메인" |
---|---|
api_site_id | 비아톡 로그인 ID |
api_api_id | 생성된 API ID |
api_api_pw | 생성된 API 암호 KEY |
* VIATOK 계정 정보 확인: (VIATOK 계정 정보 확인 바로가기) * API 계정 정보 확인: (API 계정 정보 확인 바로가기) |
[Request Body]
1. 단일 행 전송 함수: JSON 객체 형식으로 전송
2. 다중 행 전송 함수: JSON 객체 배열 형식으로 전송
3. 함수 별 요청 Body 내용은 문서 하단 함수별로 작성
[Response Body]
{
status: 200, ** 응답 HTTP Status code와 동일
code: "success", ** 6. 별첨 상태 코드 값
message: "정상 처리", ** 6. 별첨 상태 메시지 값
requested: {
url: "https://www.viatok.co.kr/kakao/v1_2/{함수명}", ** 요청 URL
method: "POST", ** 요청 타입
header.data: {
api_site_id: "{비아톡 ID}", ** VIATOK ID
api_api_id: "{API 접속 계정 ID}" ** VIATOK ID 혹은 API ID
** API 암호 접속 키(Passphrase)는 회신하지 않음.
},
body.data: [
** 요청 본문 (JSON): 각 기능 별 Request Parameter 반환 (검증)
]
},
response: {
** 응답 본문 (JSON): 각 기능 별 Response Parameter
** 처리 에러 시 에러메시지 해당 영역에 기재되어 반환
}
}
API 계정 기능
API 계정 신청 및 정보 확인 URL: https://www.viatok.co.kr/api_guide/add.php
[Request URL]
https://www.viatok.co.kr/kakao/v1_2/SEND_MESSAGE_ALARM
[Description]
Ver. 1.0.0의 SEND_MESSAGE_KAKAO, SEND_MESSAGE_FRIEND, MESSAGE_SEND 통합
* 구형 함수 사용 필요할 경우 https://www.viatok.co.kr/kakao/{함수명} URL로 요청
* 구형 함수는 버그 수정 외 업데이트 예정 없으므로 최신버전 함수 사용 권장
[Request Parameters (JSON Array)]Post Data (*: 필수 항목)
변수명 | 자료형 | 설명 |
---|---|---|
* TYPE | CHAR(3) | 발송 타입 |
* USER_KEY | VARCHAR(20) | 고객사 발급 Key (중복 불허) |
* RECEIVE | 전화번호 배열 형식 | 수신자 전화번호 |
* SEND_MSG | VARCHAR(80, 1000, 2000) | 전송 본문 |
알림톡 전송 추가 변수 (TYPE == ALT) | ||
* ALT_TEMPLATECODE | VARCHAR(30) | 템플릿 코드 |
ALT_TITLE | VARCHAR(50) | 강조 메시지 |
친구톡 전송 추가 변수 (TYPE == FRT) | ||
FRT_ADFLAG | CHAR(1) | 광고성 메시지 여부 |
카카오톡 전송 공통 변수 | ||
KAKAO_BUTTON | Array | 메시지 하단 버튼 * 6. 별첨 |
KAKAO_FAIL_TRANSFER | CHAR(1) | 전송 실패 시 전환 발송 여부 |
KAKAO_FAIL_TYPE | CHAR(3) | 전환 발송 타입 |
KAKAO_FAIL_CONTENT | VARCHAR(80, 2000) | 전환 발송 본문 |
KAKAO_FAIL_CALLBACK | 전화번호형식 | 전환 발송 발신전화번호 * 전환 발송 시 필수 |
[Request Payload Example (JSON Array)]
[
{ ** 알림톡
USER_KEY: "alt_210910_151010_0002", ** 고객 입력 Key
TYPE: "ALT", ** 전송 타입 알림톡 지정
RECEIVE: ["010-0000-0000"], ** 수신자 전화번호
SEND_MSG: "안녕하세요.\n알림톡 테스트 입니다.", ** 본문
ALT_TEMPLATECODE: "VIA_TEST_001", ** 알림톡 템플릿 코드
ALT_TITLE: "템플릿", ** 알림톡 강조 메시지
KAKAO_BUTTON: null, ** 카카오톡 버튼
KAKAO_FAIL_TRANSFER: "Y", ** 전환 발송 허용
KAKAO_FAIL_TYPE: "SMS", ** 전환 발송 타입
KAKAO_FAIL_CONTENT: "전환발송 테스트 문자메시지(SMS)",
KAKAO_FAIL_CALLBACK: "010-0000-0000" ** 발신번호
}, { ** 친구톡
USER_KEY: "frt_210910_151010_0002",
TYPE: "FRT",
RECEIVE: ["010-0000-0000"],
SEND_MSG: "안녕하세요.\n친구톡 테스트 입니다.",
FRT_ADFLAG: "N", ** 친구톡 광고성 메시지 여부
}
]
[Response (JSON Array) ]
USER_KEY | 고객 입력 Key (중복 등록 불가) |
---|---|
VIATOK_KEY | VIATOK 발급 Key |
TYPE | 전송 타입 |
FLAG | 성공 및 실패 여부 |
MESSAGE | 성공 및 실패 사유 (Array) |
TRANSFER |
전환 발송 여부KAKAO_FAIL_TRANSFER 값과 상관 없이 전환 여부 응답 * KAKAO_FAIL_TRANSFER = N이면 무조건 N으로 응답 * KAKAO_FAIL_TRANSFER = Y이며 전환 발송 안한 경우 N으로 응답 * KAKAO_FAIL_TRANSFER = Y에 전환 발송 시도한 경우 Y로 응답 |
TRANSFER_KEY | 전환 발송 Key * 전환 발송 성공 시 발송 Key 응답 |
전환 발송 관련 응답값 안내
정상 발송 시 * 발송 성공(전환 발송 상관하지 않음), 발송 실패(전환 발송 안함) | |
---|---|
FLAG | SUCC / FAIL / ERRO (성공, 실패, 에러) |
TYPE | Request의 TYPE |
VIATOK_KEY | Request의 TYPE에 해당하는 응답 Key |
TRANSFER_KEY | (공백) |
TRANSFER | N |
전환 발송 성공 시 * 발송 실패, 전환 발송 성공 | |
FLAG | TRAN (전환 발송) |
TYPE | Request의 KAKAO_FAIL_TYPE |
VIATOK_KEY | Request의 KAKAO_FAIL_TYPE에 해당하는 응답 Key |
TRANSFER_KEY | Request의 TYPE에 해당하는 응답 Key |
TRANSFER | Y |
전환 발송 실패 시 * 발송 실패, 전환 발송 실패 | |
FLAG | FAIL (전환 발송 실패) |
TYPE | Request의 TYPE |
VIATOK_KEY | Request의 TYPE에 해당하는 응답 Key |
TRANSFER_KEY | Request의 KAKAO_FAIL_TYPE에 해당하는 응답 Key |
TRANSFER | Y |
[Request Payload Example (JSON Array)]
response: [
{ ** 알림톡 응답
USER_KEY: "alt_210910_151010_0002", ** Request 유저 입력 Key
VIATOK_KEY: "{VIATOK 발급 Key}", ** VIATOK 발급 Key (전환발송)
TYPE: "ALT",
FLAG: "SUCC",
MESSAGE: ["요청이 정상적으로 완료 되었습니다."],
TRANSFER: "Y", ** 전환 발송 처리 성공
TRANSFER_KEY: "{VIATOK 발급 Key}" ** VIATOK 발급 Key (전환됨)
}, { ** 친구톡 응답
USER_KEY: "frt_210910_151010_0002",
VIATOK_KEY: "{VIATOK 발급 Key}",
TYPE: "FRT",
FLAG: "SUCC",
TRANSFER: "N",
MESSAGE: ["발송 성공"],
TRANSFER_KEY: ""
}
]
전송 내역
[Request URL]
https://www.viatok.co.kr/kakao/v1_2/LOOKUP
[Request Parameters (JSON)]Post Data (*: 필수 항목)
변수명 | 자료형 | 설명 |
---|---|---|
DATE_START | VARCHAR(19), YYYY-MM-DD HH:mm:SS |
검색 시작 일시 (기본 1달 전) |
DATE_END | 검색 종료 일시 (기본 현재) | |
SEARCH_TYPE | CHAR(3) | 전송 타입 |
SEARCH_MESSAGE | VARCHAR(100) | 전송 본문 |
SEARCH_RECEIVER | VARCHAR(16) | 수신자 전화번호 |
SEARCH_USER_KEY | VARCHAR(100) | 전송 키 |
SEARCH_RESULT | VARCHAR(5), “TRUE”, “FALSE”, “” |
전송 결과 |
PAGE | INT | 현재 페이지 number |
PER_PAGE | INT | 페이지당 표출 count |
* 검색시작일시 ~ 검색종료일시는 최장 1년 범위까지 요청 가능 |
[Request Payload Example (JSON)]
{
DATE_START: "2022-01-01 00:00:00", ** 검색 시작 일시
DATE_END: "2022-01-31 23:59:59", ** 검색 종료 일시
SEARCH_TYPE: "ALT", ** 전송 타입
SEARCH_MESSAGE: "알림톡 본문내용", ** 본문 내용 (일부)
SEARCH_RECEIVER: "010-0000-0000", ** 수신자 전화번호
SEARCH_USER_KEY: "alt_test", ** 전송 키(일부)
SEARCH_RESULT: "TRUE", ** 전송 결과
PAGE: 1, ** 현재 페이지 번호 1 ~
PER_PAGE: 100, ** 페이지당 조회할 개수
}
[Response Parameters (JSON)]
COUNT_FULL | 전체 조회 개수 |
---|---|
COUNT_SEARCH | 현재 조회 개수 |
PAGE_END | 전체 페이지 수 |
PAGE_NOW | 현재 페이지 번호 |
DATA (JSON Array) | 조회된 데이터 상세 내용 (Array) |
DATA 하위 속성 | |
USER_KEY | 전송 키 |
REQ_TYPE | 요청 전송 타입 |
REAL_TYPE | 실제 처리된 전송 타입 |
REQUESTED_DATE | 요청 일시 |
RESULT_FLAG | 처리 결과 |
MESSAGE | 전송 본문 |
RECEIVER | 수신자 전화번호 |
[Response Payload Example (JSON Array)]
response: {
COUNT_FULL: 22, ** 조건에 맞는 전체 결과 개수
COUNT_SEARCH: 10, ** 현재 페이지 내용 개수
PAGE_END: 3, ** 총 페이지 수
PAGE_NOW: 1, ** 현재 페이지 번호
DATA: [ ** 전송 내용 Array
{ ** 전송 내용 Array row
USER_KEY: "alt_test_send_1234", ** 전송 시 입력된 Key
REQ_TYPE: "ALT", ** 요청 전송 방식
REAL_TYPE: "ALT", ** 실제 전송 방식 (전환 발송 시 변경)
REQUESTED_DATE: "2022-01-05 12:34:56", ** 요청 시간
RESULT_FLAG: "SUCC",
** 전송 결과 SUCC(성공) / FAIL(실패) / TRAN(전환 발송, 성공)
MESSAGE: "전송된 알림톡 본문내용 입니다.", ** 전송 본문
RECEIVER: "01000000000" ** 수신자 전화번호, - 없음
}, …
]
}
카카오 템플릿 내용 조회
[Request URL]
https://www.viatok.co.kr/kakao/v1_2/TEMPLATE_LOOKUP/
[Request Parameters (JSON)]Post Data (*: 필수 항목)
* TEMPLATE_CODE | 조회할 템플릿 코드 |
[Request Payload Example (JSON)]
{
TEMPLATE_CODE: "{조회할 템플릿 코드}"
}
[Response Parameters (JSON)]
TEMPLATE_CODE | 템플릿 코드 (고객 지정) |
---|---|
TEMPLATE_NAME | 템플릿 명 (고객 지정) |
TEMPLATE_MSG_TYPE | 템플릿 메시지 유형 (BA: 기본형, EX: 부가정보형, AD: 광고형, MI: 복합형) |
TEMPLATE_EMP_TYPE | 템플릿 강조 유형 (NONE: 강조 없음, TEXT: 강조표기형) |
TEMPLATE_TITLE | 템플릿 강조 메시지 |
TEMPLATE_SUBTITLE | 템플릿 강조 메시지 보조 문구 |
TEMPLATE_CONTENT | 템플릿 본문 |
TEMPLATE_CATEGORY_CODE | 템플릿 카테고리 코드 * 4.2.4. 템플릿 카테고리 코드 조회 참고 |
TEMPLATE_EXTRA | 부가 정보 * 4.2.4. TEMPLATE_MSG_TYPE가 EX, MI일 경우 필수 |
TEMPLATE_AD | 수신 동의 요청 혹은 간단 광고 문구 * 4.2.4. TEMPLATE_MSG_TYPE가 AD, MI일 경우 필수 |
SECURITY | 보안템플릿 여부 ("TRUE", "FALSE") * 보안템플릿 지정될 경우, PC버전 열람 불가능 |
BUTTON | 본문 하단 버튼 (JSON Array, 사이트 이동 등) * 하단 참고 |
INSPECTION_STATUS | 템플릿 상태 코드 (REG: 등록, REQ: 승인요청, APR: 승인, REJ: 반려) |
CREATED_DATE | 템플릿 등록 일자 |
MODIFIED_DATE | 템플릿 수정 일자 |
TEMPLATE_STATUS | 템플릿 상태 (S: 중단, A: 정상, R: 대기(발송전)) |
COMMENTS | 검수 결과 댓글 (JSON Array) * 반려 시 반려 사유, 문의 내용 등 COMMENT에 저장 |
[Response Payload Example (JSON)]
response: {
TEMPLATE_CODE: "VIA_TEST_001",
TEMPLATE_NAME: "템플릿 테스트",
TEMPLATE_MSG_TYPE: "BA",
TEMPLATE_EMP_TYPE: "NONE",
TEMPLATE_TITLE: "{템플릿 강조 메시지}",
TEMPLATE_SUBTITLE: "{템플릿 강조 메시지 보조 문구}",
TEMPLATE_CONTENT: "{템플릿 본문}",
TEMPLATE_CATEGORY_CODE: "{템플릿 카테고리 코드}",
TEMPLATE_EXTRA: "{부가 정보}",
TEMPLATE_AD: "{광고 정보}",
SECURITY: "1",
BUTTON: "{버튼 Array}",
INSPECTION_STATUS: "{승인 상태}",
CREATED_DATE: "2021-02-25 14:31:51", ** 생성 일자
MODIFIED_DATE: "2021-03-02 10:59:21", ** 수정 일자
TEMPLATE_STATUS: "A",
COMMENTS: [] ** 템플릿 검수 담당자 의견 및 문의 기록
}
카카오 템플릿 카테고리 코드 조회
템플릿 관련 기능은 홈페이지에서 작업 가능 (연동 필수 아님)
https://www.viatok.co.kr/mypage/kakao_template.php
[Request URL]
https://www.viatok.co.kr/kakao/v1_2/TEMPLATE_CATEGORY_LOOKUP_ALL
[Request Parameters]
없음
[Response Parameters (JSON Array)]
TEMPLATE_CATEGORY_CODE | 카테고리 코드 |
---|---|
CATEGORY_NAME | 카테고리 명 |
DESCRIPTION | 카테고리 설명 |
REMARKS | 카테고리 부가 설명 |
[Response Payload Example (JSON Array)]
response: [
{
TEMPLATE_CATEGORY_CODE: "{카테고리 코드}",
CATEGORY_NAME: "{카테고리 명}",
DESCRIPTION: "{카테고리 코드 설명}",
REMARKS: "{카테고리 코드 부가 설명}"
},
… ** 카테고리 코드 수만큼 반복
]
카카오 템플릿 등록 요청
[Request URL]
https://www.viatok.co.kr/kakao/v1_2/TEMPLATE_REGISTER
[Request Parameters (JSON)]Post Data (*: 필수 항목)
* TEMPLATE_CODE | 템플릿 코드 (고객 지정) |
---|---|
* TEMPLATE_NAME | 템플릿 명 (고객 지정) |
* TEMPLATE_MSG_TYPE | 템플릿 메시지 유형 (BA: 기본형, EX: 부가 정보형, AD: 광고형, MI: 복합형) |
* TEMPLATE_EMP_TYPE | 템플릿 강조 유형 (NONE: 강조 없음, TEXT: 강조 표기형) |
TEMPLATE_TITLE | 템플릿 강조 메시지 |
TEMPLATE_SUBTITLE | 템플릿 강조 메시지 보조 문구 |
* TEMPLATE_CONTENT | 템플릿 본문 |
* TEMPLATE_CATEGORY_CODE | 템플릿 카테고리 코드 * 템플릿 카테고리 코드 조회 참고 |
TEMPLATE_EXTRA | 부가 정보 * TEMPLATE_MSG_TYPE가 EX, MI일 경우 필수 |
TEMPLATE_AD | 수신 동의 요청 혹은 간단 광고 문구 * TEMPLATE_MSG_TYPE가 AD, MI일 경우 필수 |
SECURITY | 보안템플릿 여부 ("TRUE", "FALSE") * 보안템플릿일 경우, PC버전 열람 불가능 |
BUTTON | 본문 하단 버튼 (JSON Array, 사이트 이동 등) * 별첨 참고 |
[Request Payload Example (JSON)]
{
TEMPLATE_CODE: "{템플릿 코드}",
TEMPLATE_NAME: "{템플릿 명}",
TEMPLATE_MSG_TYPE: "{템플릿 메시지 유형}",
TEMPLATE_EMP_TYPE: "{템플릿 강조 유형}",
TEMPLATE_TITLE: "{템플릿 강조 메시지}",
TEMPLATE_SUBTITLE: "{템플릿 강조 메시지 보조 문구}",
TEMPLATE_CONTENT: "{템플릿 본문}",
TEMPLATE_CATEGORY_CODE: "{템플릿 카테고리 코드}",
TEMPLATE_EXTRA: "{부가 정보 문구}",
TEMPLATE_AD: "{광고 문구}",
SECURITY: "{보안템플릿 여부}",
BUTTON: "{본문 하단 버튼}"
}
[Response Parameters (JSON)]
TEMPLATE_CODE | 템플릿 코드 (고객 지정) |
---|---|
TEMPLATE_NAME | 템플릿 명 (고객 지정) |
TEMPLATE_MSG_TYPE | 템플릿 메시지 유형 (BA: 기본형, EX: 부가정보형, AD: 광고형, MI: 복합형) |
TEMPLATE_EMP_TYPE | 템플릿 강조 유형 (NONE: 강조 없음, TEXT: 강조표기형) |
TEMPLATE_TITLE | 템플릿 강조 메시지 |
TEMPLATE_SUBTITLE | 템플릿 강조 메시지 보조 문구 |
TEMPLATE_CONTENT | 템플릿 본문 |
TEMPLATE_CATEGORY_CODE | 템플릿 카테고리 코드 * 템플릿 카테고리 코드 조회 참고 |
TEMPLATE_EXTRA | 부가 정보 * TEMPLATE_MSG_TYPE가 EX, MI일 경우 필수 |
TEMPLATE_AD | 수신 동의 요청 혹은 간단 광고 문구 * TEMPLATE_MSG_TYPE가 AD, MI일 경우 필수 |
SECURITY | 보안템플릿 여부 ("TRUE", "FALSE") * 보안템플릿 지정될 경우, PC버전 열람 불가능 |
BUTTON | 본문 하단 버튼 (JSON Array, 사이트 이동 등) * 별첨 참고 |
INSPECTION_STATUS | 템플릿 상태 코드 (REG: 등록, REQ: 승인요청, APR: 승인, REJ: 반려) |
CREATED_DATE | 템플릿 등록 일자 |
MODIFIED_DATE | 템플릿 수정 일자 |
TEMPLATE_STATUS | 템플릿 상태 (S: 중단, A: 정상, R: 대기(발송전)) |
COMMENTS | 검수 결과 댓글 (JSON Array) * 반려 시 반려 사유, 문의 내용 등 COMMENT에 저장 |
[Response Payload Example (JSON)]
response: {
TEMPLATE_CODE: "VIA_TEST_001",
TEMPLATE_NAME: "템플릿 테스트",
TEMPLATE_MSG_TYPE: "BA",
TEMPLATE_EMP_TYPE: "NONE",
TEMPLATE_TITLE: "{템플릿 강조 메시지}",
TEMPLATE_SUBTITLE: "{템플릿 강조 메시지 보조 문구}",
TEMPLATE_CONTENT: "{템플릿 본문}",
TEMPLATE_CATEGORY_CODE: "{템플릿 카테고리 코드}",
TEMPLATE_EXTRA: "{부가 정보}",
TEMPLATE_AD: "{광고 정보}",
SECURITY: "1",
BUTTON: "{버튼 Array}",
INSPECTION_STATUS: "REG",
CREATED_DATE: "2021-02-25 14:31:51", ** 생성 일자
MODIFIED_DATE: "2021-02-25 14:31:51", ** 생성 일자 (신규 등록)
TEMPLATE_STATUS: "R",
COMMENTS: [] ** 템플릿 검수 담당자 의견 및 문의 기록
}
카카오 템플릿 수정 요청
템플릿 관련 기능은 홈페이지에서 작업 가능 (연동 필수 아님)
https://www.viatok.co.kr/mypage/kakao_template.php
[Request URL]
https://www.viatok.co.kr/kakao/v1_2/TEMPLATE_MODIFY
[Request Parameters (JSON)]Post Data (*: 필수 항목)
* TEMPLATE_CODE_ORIGN | 수정할 템플릿 코드 * 템플릿 상태가 REG인 템플릿만 수정 가능합니다. * REQ, REJ는 검수 취소 요청을 하여 REG상태로 전환 가능합니다. * APR 상태(승인 완료)는 수정 불가합니다. |
---|---|
* TEMPLATE_CODE | 변경할 템플릿 코드 (고객 지정) * 템플릿코드는 수정하고 싶지 않은 경우, 원 템플릿 코드와 동일하게 기재 |
* TEMPLATE_NAME | 템플릿 명 (고객 지정) |
* TEMPLATE_MSG_TYPE | 템플릿 메시지 유형 (BA: 기본형, EX: 부가 정보형, AD: 광고형, MI: 복합형) |
* TEMPLATE_EMP_TYPE | 템플릿 강조 유형 (NONE: 강조 없음, TEXT: 강조 표기형) |
TEMPLATE_TITLE | 템플릿 강조 메시지 |
TEMPLATE_SUBTITLE | 템플릿 강조 메시지 보조 문구 |
* TEMPLATE_CONTENT | 템플릿 본문 |
* TEMPLATE_CATEGORY_CODE | 템플릿 카테고리 코드 * 템플릿 카테고리 코드 조회 참고 |
TEMPLATE_EXTRA | 부가 정보 * TEMPLATE_MSG_TYPE가 EX, MI일 경우 필수 |
TEMPLATE_AD | 수신 동의 요청 혹은 간단 광고 문구 * TEMPLATE_MSG_TYPE가 AD, MI일 경우 필수 |
SECURITY | 보안템플릿 여부 ("TRUE", "FALSE") * 보안템플릿일 경우, PC버전 열람 불가능 |
BUTTON | 본문 하단 버튼 (JSON Array, 사이트 이동 등) * 별첨 참고 |
[Request Payload Example (JSON)]
{
TEMPLATE_CODE_ORIGN: "{원 템플릿 코드}",
TEMPLATE_CODE: "{템플릿 코드}",
TEMPLATE_NAME: "{템플릿 명}",
TEMPLATE_MSG_TYPE: "{템플릿 메시지 유형}",
TEMPLATE_EMP_TYPE: "{템플릿 강조 유형}",
TEMPLATE_TITLE: "{템플릿 강조 메시지}",
TEMPLATE_SUBTITLE: "{템플릿 강조 메시지 보조 문구}",
TEMPLATE_CONTENT: "{템플릿 본문}",
TEMPLATE_CATEGORY_CODE: "{템플릿 카테고리 코드}",
TEMPLATE_EXTRA: "{부가 정보 문구}",
TEMPLATE_AD: "{광고 문구}",
SECURITY: "{보안템플릿 여부}",
BUTTON: "{본문 하단 버튼}"
}
[Response Parameters (JSON)]
TEMPLATE_CODE | 템플릿 코드 (고객 지정) |
---|---|
TEMPLATE_NAME | 템플릿 명 (고객 지정) |
TEMPLATE_MSG_TYPE | 템플릿 메시지 유형 (BA: 기본형, EX: 부가정보형, AD: 광고형, MI: 복합형) |
TEMPLATE_EMP_TYPE | 템플릿 강조 유형 (NONE: 강조 없음, TEXT: 강조표기형) |
TEMPLATE_TITLE | 템플릿 강조 메시지 |
TEMPLATE_SUBTITLE | 템플릿 강조 메시지 보조 문구 |
TEMPLATE_CONTENT | 템플릿 본문 |
TEMPLATE_CATEGORY_CODE | 템플릿 카테고리 코드 * 템플릿 카테고리 코드 조회 참고 |
TEMPLATE_EXTRA | 부가 정보 * TEMPLATE_MSG_TYPE가 EX, MI일 경우 필수 |
TEMPLATE_AD | 수신 동의 요청 혹은 간단 광고 문구 * TEMPLATE_MSG_TYPE가 AD, MI일 경우 필수 |
SECURITY | 보안템플릿 여부 ("TRUE", "FALSE") * 보안템플릿 지정될 경우, PC버전 열람 불가능 |
BUTTON | 본문 하단 버튼 (JSON Array, 사이트 이동 등) * 별첨 참고 |
INSPECTION_STATUS | 템플릿 상태 코드 (REG: 등록, REQ: 승인요청, APR: 승인, REJ: 반려) |
CREATED_DATE | 템플릿 등록 일자 |
MODIFIED_DATE | 템플릿 수정 일자 |
TEMPLATE_STATUS | 템플릿 상태 (S: 중단, A: 정상, R: 대기(발송전)) |
COMMENTS | 검수 결과 댓글 (JSON Array) * 반려 시 반려 사유, 문의 내용 등 COMMENT에 저장 |
[Response Payload Example (JSON)]
response: {
TEMPLATE_CODE: "VIA_TEST_001",
TEMPLATE_NAME: "템플릿 테스트",
TEMPLATE_MSG_TYPE: "BA",
TEMPLATE_EMP_TYPE: "NONE",
TEMPLATE_TITLE: "{템플릿 강조 메시지}",
TEMPLATE_SUBTITLE: "{템플릿 강조 메시지 보조 문구}",
TEMPLATE_CONTENT: "{템플릿 본문}",
TEMPLATE_CATEGORY_CODE: "{템플릿 카테고리 코드}",
TEMPLATE_EXTRA: "{부가 정보}",
TEMPLATE_AD: "{광고 정보}",
SECURITY: "1",
BUTTON: "{버튼 Array}",
INSPECTION_STATUS: "REG",
CREATED_DATE: "2021-02-25 14:31:51", ** 생성 일자
MODIFIED_DATE: "2021-02-25 14:31:51", ** 생성 일자 (신규 등록)
TEMPLATE_STATUS: "R",
COMMENTS: [] ** 템플릿 검수 담당자 의견 및 문의 기록
}
카카오 템플릿 검수 요청
템플릿 관련 기능은 홈페이지에서 작업 가능 (연동 필수 아님)
https://www.viatok.co.kr/mypage/kakao_template.php
[Request URL]
https://www.viatok.co.kr/kakao/v1_2/TEMPLATE_INSPECT
[Request Parameters (JSON)]Post Data (*: 필수 항목)
* TEMPLATE_CODE | 검수 요청할 템플릿 코드 * 상태가 REG인 템플릿만 검수 요청 가능합니다. |
---|---|
COMMENT | 카카오톡 템플릿 검수담당자에 요청 혹은 전달할 메시지 * 생략 가능, 2021-12-13 템플릿 문의 요청 통폐합 |
[Request Payload Example (JSON)]
{
TEMPLATE_CODE: "{검수 요청할 템플릿 코드}”,
COMMENT: "{문의 요청할 내용}”
}
[Response Parameters]
없음
카카오 템플릿 취소 요청
템플릿 관련 기능은 홈페이지에서 작업 가능 (연동 필수 아님)
https://www.viatok.co.kr/mypage/kakao_template.php
[Request URL]
https://www.viatok.co.kr/kakao/v1_2/TEMPLATE_CANCEL
[Request Parameters (JSON)]Post Data (*: 필수 항목)
* TEMPLATE_CODE | 검수 취소 요청할 템플릿 코드 * 상태가 REQ인 템플릿만 검수 취소 요청 가능합니다. |
---|
[Request Payload Example (JSON)]
{
TEMPLATE_CODE: "{검수 취소 요청할 템플릿 코드}"
}
[Response Parameters]
없음
VIATOK 계정 기능
VIATOK 사용 신청 및 정보 확인 URL: https://www.viatok.co.kr/api_guide/reg.php
포인트 조회
[Request URL]
https://www.viatok.co.kr/kakao/v1_2/GET_POINT_INFO
[Request Parameters]
없음
[Response Parameters (JSON)]
REMAIN_POINT | 잔여 포인트 |
---|---|
ALT_POINT | 알림톡 1건당 비용 |
FRT_POINT | 친구톡 1건당 비용 |
SMS_POINT | SMS 1건당 비용 |
LMS_POINT | LMS 1건당 비용 |
MMS_POINT | MMS 1건당 비용 (홈페이지 전용) |
MSG_COUNT_PER_DAY | 문자메시지 1일 전송 제한 횟수 (0: 무제한) |
TALK_COUNT_PER_DAY | 카카오톡 1일 전송 제한 횟수 (0: 무제한) |
[Response Payload Example (JSON)]
response: {
REMAIN_POINT: "{잔여 포인트}",
ALT_POINT: "{알림톡 1건당 비용}",
FRT_POINT: "{친구톡 1건당 비용}",
SMS_POINT: "{SMS 1건당 비용}",
LMS_POINT: "{LMS 1건당 비용}",
MMS_POINT: "{MMS 1건당 비용}",
MSG_COUNT_PER_DAY: "{문자메시지 1일 발송 제한 횟수}",
TALK_COUNT_PER_DAY: "{카카오톡 1일 발송 제한 횟수}"
}
API 계정 목록 조회
[Request URL]
https://www.viatok.co.kr/kakao/v1_2/VIATOK_GET_ACCOUNT_LIST
[Request Parameters (JSON)]
SEARCH_API_ID | API ID로 검색 |
---|---|
SEARCH_ALLOW_IP | 등록 도메인으로 검색 |
SEARCH_USER_STATUS | API 계정 상태로 검색 (0: 신청 중, 1: 정상, 2: 사용 정지, 99: 삭제 대기) |
[Request Payload Example (JSON)]
{
SEARCH_API_ID: "{API ID, 생략 가능}",
SEARCH_ALLOW_IP: "{등록 도메인, 생략 가능}",
SEARCH_USER_STATUS: "{계정 상태, 생략 가능}",
}
[Response Parameters (JSON Array)]
API_ID | API 계정 ID |
---|---|
ALLOW_IP | API 접속 도메인 |
USER_STATUS | API 계정 상태 |
USE_KAKAO | 카카오톡 발신 프로필이 계정에 등록되어 있는지 여부 |
USE_MESSAGE | 발신 번호가 계정에 등록되어 있는지 여부 |
[Response Payload Example (JSON Array)]
response: [
{
API_ID: "{계정 ID}",
ALLOW_IP: "{접속 도메인}",
USER_STATUS: "{계정 상태}",
USE_KAKAO: "{카카오톡 발신 가능 여부}",
USE_MESSAGE: "{문자메시지 발신 가능 여부}"
},
** 생성된 API 계정 중 입력한 조건에 부합하는 만큼 반복
]
API 포인트 사용 내역 조회
[Request URL]
https://www.viatok.co.kr/kakao/v1_2/USE_LOG_POINT
[Request Parameters (JSON)]
ORDERING | 표출 정/역순 구분 |
---|---|
PAGE | 페이지 번호 |
PER_PAGE | 페이지당 노출 개수 |
POINT_IO_TYPE | 충전 및 사용 검색 구분 * I: 충전, O: 사용 |
DATE_START | 검색 시작일 |
DATE_END | 검색 종료일 |
[Request Payload Example (JSON)]
{
ORDERING: "{표출 정/역순 구분}",
PAGE: "{페이지 번호}",
PER_PAGE: "{페이지당 노출 개수, 생략 가능}",
POINT_IO_TYPE: "{충전 / 사용 구분, 생략 가능}",
DATE_START: "{검색 시작일, 생략 가능}",
DATE_END: "{검색 종료일, 생략 가능}",
}
[Response Parameters (JSON)]
POINT_IO_TYPE | 포인트 사용 및 충전 구분 |
---|---|
POINT_CHANGE | 포인트 변경 양 (차감된 포인트 or 충전된 포인트) |
DATETIME | 변동 시간 |
TITLE | 변동 사유 |
ORDER_NO | VIATOK 발급 키 값 |
[Response Payload Example (JSON)]
response: {
POINT_IO_TYPE: "{충전/사용 구분}",
POINT_CHANGE: "{변동 포인트 양(충전량 혹은 소모량)}",
DATETIME: "{변동 발생 일시}",
TITLE: "{변동 사유}",
ORDER_NO: "{VIATOK 발급 키 값}"
}
자주 하는 질문
HTTP Referer
* 참고 URL: https://datatracker.ietf.org/doc/html/rfc7231#section-5.5.2
VIATOK API Request시 Header에 Referer값이 정의되어 있어야 합니다.
원래 Referer값은 하이퍼링크를 통해서 방문시 이전 URL을 담는 헤더값이지만,
VIATOK API에서는 고객의 접속 HOST값으로 판단합니다.
요청하시는 방식 혹은 언어에 따라 Referer값이 자동으로 포함되어 요청되거나 누락될 수도 있습니다.
Referer값이 누락되거나 등록된 값(접속 도메인)과 상이하게 요청이 오는 경우
API 서버는 HTTP 403 Forbidden (fail_auth_fail_002)를 반환합니다.
VIATOK API에서 Referer와 비교하는 값은 API 계정 신청 시 등록하신 "접속 도메인" 값입니다. (IP형식도 허용, www.는 생략 가능)
* https://www.viatok.co.kr/api_guide/add.php
* https://www.viatok.co.kr/api_guide/reg.php
JSON, JSON Array
요청 및 응답 처리 시, 각 함수의 Request Parameter 및 Response Parameter에 명시된 JSON, JSON Array 구분을 확인해 주세요.
JSON(객체 형식)
Key - Value 형식으로 이루어진 JSON Object * 중괄호로 감싸진 JSON 데이터
** 단일 행 (JSON) 예시
{
KEY: "{String Value}",
KEY2: Integer Value
}
JSON Array(객체 배열 형식)
한 개 이상의 JSON Object로 구성된 배열(Array) * 대괄호로 감싸진 JSON 데이터
** 다중 행 (JSON Array) 예시
[
{
KEY: "{String Value}",
KEY2: Integer Value
}, {
KEY3: "{String Value}",
KEY4: Integer Value
}
]
카카오톡 버튼 관련 정리
버튼은 템플릿 및 1회 전송 시 최대 5개까지 추가가 가능합니다.
템플릿 등록용
[Parameters (JSON Array)]Post Data (*: 필수 항목)
* ORDER_NO | 버튼 노출 순서 |
---|---|
* BUTTON_NAME | 버튼 명 (버튼 텍스트) |
* BUTTON_TYPE | 버튼 종류 * WL (Web Link) |
* LINK_WEB_MOBILE | 버튼 클릭 시 이동할 URL |
LINK_WEB_PC | PC버전에서 버튼 클릭 시 이동할 URL * 할당하지 않을 경우 LINK_WEB_MOBILE과 동일 |
[Payload Example (JSON)]
[
{
ORDER_NO: 1,
BUTTON_NAME: "사이트 이동(테스트)",
BUTTON_TYPE: "WL",
LINK_WEB_MOBILE: "https://www.viatok.co.kr",
LINK_WEB_PC: null
},
** 최대 버튼 5개까지 추가 가능
]
알림톡 및 친구톡 발송용
Description
알림톡의 경우 템플릿과 발송 시 버튼 내용이 동일해야 합니다.
[Parameters (JSON Array)]Post Data (*: 필수 항목)
* BUTTON_NAME | 버튼 명 (버튼 텍스트) |
---|---|
* BUTTON_TYPE | 버튼 종류 * WL (Web Link) |
* LINK_WEB_MOBILE | 버튼 클릭 시 이동할 URL |
LINK_WEB_PC | PC버전에서 버튼 클릭 시 이동할 URL * 할당하지 않을 경우 LINK_WEB_MOBILE과 동일 |
LINK_APP_OUT | 버튼 클릭 시 카카오톡 내장 브라우저에서 이동할지 선택하는 변수 * 모바일 환경에만 영향 * OUT: 외부 브라우저 실행, IN: 카카오톡 내장 브라우저 실행 |
[Payload Example (JSON)]
[
{
BUTTON_NAME: "사이트 이동(테스트)",
BUTTON_TYPE: "WL",
LINK_WEB_MOBILE: "https://www.viatok.co.kr",
LINK_WEB_PC: null,
LINK_APP_OUT: "OUT"
},
** 최대 버튼 5개까지 추가 가능
]
적용 샘플
![]() |
![]() |
알림톡 템플릿 적용 예시 | 버튼 클릭 후 웹사이트 이동 예시 |
* TEMPLATE_TITLE: 비아톡 * TEMPLATE_SUBTITLE: VIATOK * BUTTON: 6.2.2. 알림톡 및 친구톡 발송용 내 예제 데이터와 동일 |
LINK_APP_OUT: OUT 옵션으로 외부 브라우저 실행 |
응답 코드
status | 200 |
---|---|
code | success |
message | 정상 처리 |
description | - |
status | 200 |
---|---|
code | success_created |
message | 정상 처리: 생성 완료 |
description | - |
status | 200 |
---|---|
code | success_modified |
message | 정상 처리: 수정 완료 |
description | - |
status | 200 |
---|---|
code | success_request |
message | 정상 처리: 요청 완료 |
description | - |
status | 206 |
---|---|
code | success_partial |
message | 정상 처리: 부분 성공 |
description | 다중 행 요청 함수에서 일부분의 데이터만 성공했을 경우 |
status | 200 |
---|---|
code | success_send_001 |
message | 정상 처리: 메시지 전송 요청 완료 |
description | * 응답 값 제거 예정 |
status | 200 |
---|---|
code | success_send_002 |
message | 정상 처리: 알림톡 전송 요청 완료 |
description | * 응답 값 제거 예정 |
status | 200 |
---|---|
code | success_send_003 |
message | 정상 처리: 친구톡 전송 요청 완료 |
description | * 응답 값 제거 예정 |
status | 200 |
---|---|
code | success_send_004 |
message | 정상 처리: 전환 발송됨 |
description | * 응답 값 제거 예정 |
status | 200 |
---|---|
code | success_send_005 |
message | 정상 처리: 일부 데이터만 전송 성공 |
description | * 응답 값 제거 예정 |
status | 400 |
---|---|
code | fail |
message | 요청 오류: 잘못된 요청 |
description | 요청 자체가 잘못된 경우 (보안접속 미사용 등) |
status | 404 |
---|---|
code | fail_404 |
message | 요청 오류: 요청된 페이지를 찾을 수 없음 |
description | 요청된 URL에 해당하는 기능을 찾을 수 없음 |
status | 406 |
---|---|
code | fail_format |
message | 요청 오류: 요청된 포맷을 지원하지 않음 |
description | 요청된 Type이 json이 아님 |
status | 400 |
---|---|
code | fail_url_001 |
message | 요청 오류: 요청된 URL 구문 오류 |
description | URL의 형식이 이상하거나, 버전이 맞지 않음 |
status | 405 |
---|---|
code | fail_url_002 |
message | 요청 오류: 요청된 METHOD는 허용되지 않음 |
description | VIATOK API의 모든 호출 방식은 POST이며, 이외로 오는 경우 405 회신 |
status | 400 |
---|---|
code | fail_payload_001 |
message | 요청 오류: Request BODY가 JSON 형식이 아니거나 데이터가 없음 |
description | Body의 내용이 없거나, JSON 형식이 아닌 경우 |
status | 400 |
---|---|
code | fail_payload_002 |
message | 요청 오류: Request BODY의 필수인자 불충분 |
description | * 미사용 |
status | 400 |
---|---|
code | fail_payload_003 |
message | 요청 오류: Request BODY.DATA에 데이터가 없거나, 요구되는 데이터가 충족되지 않음 |
description | 함수에서 요구하는 변수 중 Body의 데이터가 불충분한 경우 |
status | 400 |
---|---|
code | fail_payload_004 |
message | 요청 오류: Request BODY.DATA에 데이터가 너무 많음 |
description | 다중 행 함수에 너무 많은 데이터를 요청한 경우 |
status | 401 |
---|---|
code | fail_auth_fail_001 |
message | 요청 오류: 로그인 정보가 없음. |
description | api_site_id, api_api_id, api_user_pw 등 헤더 인증 값이 부족한 경우 |
status | 403 |
---|---|
code | fail_auth_fail_002 |
message | 요청 오류: 권한이 부족하거나 없음 |
description | 계정 인증에 실패하거나, 요청한 기능을 수행할 권한이 부족한 경우 |
status | 403 |
---|---|
code | fail_auth_fail_003 |
message | 요청 오류: 결제 포인트 부족 |
description | VIATOK 아이디의 포인트 잔여량이 부족한 경우 |
status | 403 |
---|---|
code | fail_auth_fail_004 |
message | 요청 오류: 오늘 사용량 초과 |
description | 오늘 발송 가능한 제한 횟수를 모두 소모한 경우 |
status | 404 |
---|---|
code | fail_not_found |
message | 정상 처리: 요청은 성공했으나, 요청에 해당하는 회신 값이 없음 |
description | VIATOK API에 요청한 조회 기능이 성공했으나, 반환할 값이 없음 |
status | 422 |
---|---|
code | fail_already_exists |
message | 처리 오류: 이미 존재하는 데이터입니다. |
description | 이미 존재하는 데이터를 중복해서 입력 시도한 경우 |
status | 403 |
---|---|
code | fail_not_allowed |
message | 요청 오류: 발신 전화번호는 VIATOK 사이트에서 로그인 후 진행해 주시길 바랍니다. |
description | API에서 허용되지 않은 기능을 시도한 경우 |
status | 403 |
---|---|
code | fail_not_matched |
message | 요청 오류: 입력된 데이터가 등록 정보와 상이하여 요청 거부 |
description | VIATOK에 등록된 정보와 다른 데이터로 요청한 경우 (발신번호 등) |
status | 429 |
---|---|
code | fail_too_many_req |
message | 요청 오류: 단위 시간내 너무 많은 데이터를 요청하였습니다. |
description | 짧은 시간 안에 API에 많은 요청을 보낸 경우 |
status | 520 |
---|---|
code | fail_error_endpoint |
message | 처리 오류: 비정상적인 접근 경로입니다. |
description | * 미사용 |
status | 500 |
---|---|
code | fail_api_fail_001 |
message | 요청 오류: 요청이 실패했습니다. (실패 응답 수신) |
description | VIATOK 서버에 요청은 성공했으나, 문자 혹은 알림톡 서버에서 실패를 반환한 경우 |
status | 500 |
---|---|
code | fail_api_fail_002 |
message | 처리 오류: 요청이 실패했습니다. (서버 응답 없음) |
description | VIATOK 서버에 요청은 성공했으나, 문자 혹은 알림톡 서버에서 응답이 없는 경우 |
status | 500 |
---|---|
code | fail_api_fail_003 |
message | 처리 오류: 요청이 실패했습니다. (서버 응답 오류) |
description | VIATOK 서버에 요청은 성공했으나, 문자 혹은 알림톡 서버에서 에러를 반환한 경우 |
status | 500 |
---|---|
code | fail_api_fail_004 |
message | 처리 오류: 처리 중 오류가 발생했습니다. |
description | VIATOK API 서버에서 처리 중 에러가 발생한 경우 |
status | 500 |
---|---|
code | fail_api_fail_005 |
message | 처리 오류: 요청 데이터 없음 |
description | 문자 혹은 카카오톡 서버로 요청할 데이터가 없는 경우 |
status | 500 |
---|---|
code | fail_api_fail_006 |
message | 처리 오류: 요청하신 ID의 설정 정보를 찾을 수 없습니다. |
description | * 미사용 |