CDMS 개발 내역서

Size: px

Start display at page:

Download "CDMS 개발 내역서"

광렬 난
5 years ago
Views:

2 변경내역 작성일자버전변경사항 배포 사용예제업데이트 템플릿조회 API 업데이트 발신번호등록 / 인증 API 업데이트 오류코드추가 템플릿버튼 5 개추가. 템플릿조회 API, Response 추가 CALLBACK Optional 수정 2

3 [ 목차 ] 1 범위 (Scope) 개요 API 목록 인증 공통정의사항 API 정의 카카오알림톡 API Report 조회 Template 조회 발신번호인증 / 등록 발신번호리스트조회 Test Summary 발신번호등록규칙 코드및메시지정의 Appendix Report Code

4 1 범위 (Scope) 본규격서는 HTTP 프로토콜을기반으로작성되었습니다. 본규격서는 Message 전송에대한규격을정의하고있습니다. 4

5 2 개요 2.1 API 목록 종류 API 기능 발송 /kko/{v1}/msg/{client_id} 카카오알림톡발송기능 결과조회 /kko/{v1}/report/{client_id} 결과조회기능 템플릿조회발신번호 2.2 인증 /kko/{v1}/template/list/{client_id} /kko/{v1}/sendnumber/save/{client_id} /kko/{v1}/sendnumber/list/{client_id} 등록된템플릿조회 발신번호등록 등록된발신번호리스트조회 구매시발급받은 Key 의코드값을헤더 x-waple-authorization 의값으로설정 x-waple-authorization: MS0xMzY1NjY2MTAyNDk0LTA2MWE4ZDgyLTZhZmMtNGU5OS05YThkLTgyNmFmYzVlOTkzZQ== 2.3 공통정의사항 공통URL {client_id} 는 API스토어에가입한후해당 API를사용 ( 구매 ) 신청한 ID. {apiversion} : 1 {type}: 은 msg, report 중택1 공통헤더 Content-Type: application/x-www-form-urlencoded; charset=utf-8 x-waple-authorization: MS0xMzY1NjY2MTAyDk0LTA2MWE4ZDgyLTZhZmMtNGU5OS05YThkLTgyNmFmYzVlOTkzZ Q== 5

6 3 API 정의 3.1 카카오알림톡 API / msg/{client_id} 기본정보 기능 : 카카오알림톡전송기능 방식 : POST 호출 URL: 요청파라미터 PHONE String No 수신할핸드폰번호 CALLBACK String No 발신자전화번호 ( - 제외 / 숫자만입력 ) REQDATE String Yes 발송시간 ( 없을경우즉시발송 ) ( :11:11) MSG String No 전송할메시지 ( 승인된템플릿의내용과동일하게작성 ) TEMPLATE_CODE String No 카카오알림톡템플릿코드 FAILED_TYPE String No 카카오알림톡전송실패시전송할메시지타입 ( SMS, LMS, N( 전송안함 ) ) FAILED_SUBJECT String Yes 카카오알림톡전송실패시전송할제목 (SMS 미사용 ) FAILED_MSG String Yes 카카오알림톡전송실패시전송할내용 BTN_TYPES String No 카카오알림톡버튼타입 ( 웹링크, 앱링크, 봇키워드, 메시지전달, 배송조회 ), 최대 5 개까지추가가능하며타입별콤마로구분함. ( 승인된템플릿과불일치시전송실패 ) BTN_TXTS String No 카카오알림톡버튼이름 (BNT_TYPES 입력순으로버튼이름 TEXT 입력, 승인된템플릿과불일치시전송실패 ), TEXT 별콤마로구분함. ( 승인된템플릿과불일치시전송실패 ) BTN_URLS1 String No 알림톡버튼링크주소 URL. 버튼 URL 버튼이 2 개이상일경우콤마로구분함. 웹링크, 앱링크는 URL 이필수이며, 기타 ( 배송조회, 봇키워드, 메시지전달 ) 은 null 값임. ( 승인된템플릿과불일치시전송실패 ) 6

7 BTN_URLS2 String No 알림톡버튼링크주소 URL. 버튼 1 개에링크가 2 개인경우 BTN_URLS2 파라미터사용. 버튼이 2 개이상일경우콤마로구분함. ( 승인된템플릿과불일치시전송실패 ) FAILED_TYPE No 처리결과코드 100 : User Error 200 : OK 300 : Parameter Error 301 : failed_type 이 "N" 이아닌경우에실패SMS 제목과내용이없으면에러 400 : Etc Error result_code String 500 : 발신번호사전등록제에의한미등록차단 ( 3.4 발신번호인증 / 등록참조 ) 600 : 충전요금부족 700 : 템플릿코드사전승인제에의한미승인차단 800 : 템플릿코드에러 900 : 프로파일이존재하지않음 No 잔금부족 [ 미발송목록 ] result_message String cmid String No 서버에서생성한 request 를식별할수있는 유일한키 사용예제 REQUEST URL POST Content-Type: application/x-www-form-urlencoded; charset=utf-8 Header x-waple-authorization: MS0xMzY1NjY2MTAyNDk0LTA2MWE4ZDgyLTZhZmMtNGU5OS05YThkLTgyNmFmYzVlOTkzZQ== Parameter PHONE= CALLBACK= MSG= 테스트 TEMPLATE_CODE=A1111 FAILED_TYPE=LMS 7

8 FAILED_SUBJECT= 테스트 FAILED_MSG= 테스트 BTN_TYPES= 웹링크, 웹링크 BTN_TXTS= 홈페이지1, 홈페이지2 BTN_URLS1= RESONSE 200 Access-Control-Allow-Origin Content-Type: application/json { result_code : 200, cmid : } 3.2 Report 조회 /report/{client_id} 기본정보 기능 : report 조회기능 방식 : GET 호출 URL: 요청파라미터 cmid( 소문자 ) String No 서버에서생성한 request를식별할수있는유일한키 반환값 STATUS String No 발송상태 1: 발송대기 2: 전송완료 3: 알림톡결과수신완료 4: Failback 결과수신완료 PHONE String No 수신한핸드폰번호 CALLBACK String No 발신자전화번호 RSLT String Yes 카카오알림톡결과수신 (6.1 Appendix Report Code 참조 ) MSG_RSLT String Yes 카카오알림톡실패시메시지결과수신 (6.1 Appendix Report Code 참조 ) 사용예제 REQUEST URL 8

9 GET Content-Type: application/x-www-form-urlencoded; charset=utf-8 Header x-waple-authorization: MS0xMzY1NjY2MTAyNDk0LTA2MWE4ZDgyLTZhZmMtNGU5OS05YThkLTgyNmFmYzVlOTkzZQ== RESONSE 200 Access-Control-Allow-Origin: * Content-Type: application/json {"PHONE":" ","RSLT":"0","CALLBACK":" ","MSG_RSLT":"00"," STATUS":"3","CMID":" "} 3.3 Template 조회 /template/list/{client_id} 기본정보 기능 : template 조회기능 방식 : GET 호출 URL: 요청파라미터 TEMPLATE_CO Yes 템플릿코드 입력안할경우전체리스트 String DE 반환 검수상태 입력안할경우전체리스트반 환 STATUS String Yes 등록 (1) / 검수요청 (2) 승인 (3) / 반려 (4) / 승인중단 (5) 반환값 TEMPLATE_CO DE String No 템플릿코드 TEMPLATE_NA ME String No 템플릿명 TEMPLATE_MS G String No 템플릿내용 STATUS String No 등록상태 ( 등록, 검수요청, 승인, 반려 ) BTNLIST String No 버튼리스트 9

10 TEMPLATE_BTN _URL TEMPLATE_BTN _NAME TEMPLATE_BTN _TYPE 사용예제 REQUEST String No 버튼 URL String No 버튼이름 String No 버튼타입 URL GET Content-Type: application/x-www-form-urlencoded; charset=utf-8 Header x-waple-authorization: MS0xMzY1NjY2MTAyNDk0LTA2MWE4ZDgyLTZhZmMtNGU5OS05YThkLTgyNmFmYzVlOTkzZQ== Parameter TEMPLATE_CODE=api123&status=1 RESONSE 200 Access-Control-Allow-Origin: * Content-Type: application/json {"template_code : test1","template_name":"test1","template_msg":" 메시지내용 ","status": " 등록 ","btnlist": "template_btn_url2": null,"template_btn_name": " 홈페이지 ",template_btn_url":" : 웹링크 } 3.4 발신번호인증 / 등록 /sendnumber/save/{client_id} 기능 : 발신번호인증 / 등록 API (apiversion = 2) 기본정보 인증방법 : SMS, VMS 중 1 개선택 방식 : POST 호출 URL: 요청파라미터 10

11 sendnumber String No 발신번호 ( - 제외 ) ( 발신번호등록규칙참조 ) comment String No 코멘트 (200자) pintype String Yes 인증방법 (SMS. VMS( 음성 ) 중 1개선택 ) Yes 인증번호-인증번호받은후, pincode 파라미 pincode String 터사용 (SMS 인증번호 (6자리), VMS인증번호 (2자리)) 반환값 result_code String No 처리결과코드 200 : 성공 300 : 파라메터에러 400 : 인증업데이트중에러 500 : 이미등록된번호 600 : 일치하지않는인증번호 700 : 핀코드인증시간만료 (3분이후만료이며재등록요청해야함.) sendnumber String No 등록한번호 사용예제 REQUEST < 요청 > URL POST Content-Type: application/x-www-form-urlencoded; charset=utf-8 Header x-waple-authorization: MS0xMzY1NjY2MTAyNDk0LTA2MWE4ZDgyLTZhZmMtNGU5OS05YThkLTgyNmFmYzVlOTkzZQ== Parameter sendnumber= &comment= 케이티하이텔대표번호 &pintype=sms 또는 VMS( 음성 ) < 인증 > URL POST Content-Type: application/x-www-form-urlencoded; charset=utf-8 Header x-waple-authorization: MS0xMzY1NjY2MTAyNDk0LTA2MWE4ZDgyLTZhZmMtNGU5OS05YThkLTgyNmFmYzVlOTkzZQ== Parameter 11

12 sendnumber= &comment= 케이티하이텔대표번호 &pintype=sms&pincode=123456(6 자리 ) (pintype=vms 일경우 pincode=12(2 자리 )) RESONSE [ 요청 ] 200 Access-Control-Allow-Origin: * Content-Type: application/json {"result_code":"200","sendnumber":" "} [ 인증 ] 200 Access-Control-Allow-Origin: * Content-Type: application/json {"result_code":"200","sendnumber":" "} 3.5 발신번호리스트조회 /sendnumber/list/{client_id} 기본정보 기능 : list 조회기능 방식 : GET 호출 URL: 요청파라미터 sendnumber String Yes 발신번호 ( - 제외 ) 입력안할경우전체리스트반환 반환값 result_code String No 처리결과코드 100 : User Error 200 : OK 300 : Parameter Error 400 : Etc Error USE_YN : Y 값은정상등록된번호. N 값은요청후미인증번호. client_id String No API스토어계정 comment String No 등록내용 sendnumber String No 등록한번호 12

13 사용예제 REQUEST URL GET Content-Type: application/x-www-form-urlencoded; charset=utf-8 Header x-waple-authorization: MS0xMzY1NjY2MTAyNDk0LTA2MWE4ZDgyLTZhZmMtNGU5OS05YThkLTgyNmFmYzVlOTkzZQ== RESONSE 200 Access-Control-Allow-Origin: * Content-Type: application/json {"result_code":"200", numberlist": [{ client_id : {client_id}, comment : null, sendnumber":" "}, { client_id : {client_id}, comment : null, sendnumber":" "} 4 Test Summary TEST는실제로메시지전송은되지않으며, 요청한데이터에대한처리결과만확인가능. URL을제외한파라미터및리턴데이터는위와동일. URL POST 카카오알림톡 5 발신번호등록규칙 - 기본 : 8자리 ~ 11자리발신번호 - 유선전화번호 : 지역번호를포함 - 이동통신전화번호 - 대표전화번호 : 15xx, 16xx, 18xx( 번호앞에지역번호사용금지 ) 6 코드및메시지정의 6.1 Appendix Report Code 구분결과코드코드 Description 0 SUCCESS 성공 1 INVALID_SENDER_KEY 발신프로필키가유효하지않음 RSLT 2 NOT_CONNECTED_USER 서버와연결되어있지않은사용자 5 ACK_TIMEOUT 메시지발송후수신여부불투명 13

14 6 RESPONSE_HISTORY_NOTFOUND 메시지전송결과를찾을수없음 8 NO_SEND_AVALIABLE_STATUS 메시지를전송할수없는상태 9 NO_VISIT_USER 최근카카오톡을미사용자 a E_INSUFFICIENT 건수부족 b E_REJECT_ITER 전송권한없음 c E_DUP_KEY 중복된키접수차단 d E_DUP_PHONE 중복된수신번호접수차단 e E_SERVER_ERROR 서버내부에러 f E_FORMAT_ERR 메시지포맷에러 k MESSAGE_NOT_FOUND 메시지가존재하지않음 o E_TIMEOUT_AGENT TIME OUT 처리 (Agent 내부 ) p E_DUPLICATE_PHONE_MSG 메시지본문중복차단 (Agent 내부 ) t MESSAGE_EMPTY 메시지가비어있음 A NO_USER 카카오톡을미사용자 B USER_BLOCKED_DELIVERY 알림톡차단을선택한사용자 C SERIAL_NUMBER_DUPLICATED 메시지일련번호중복 D DUPLICATED 5 초이내메시지중복발송 E UNSUPPORTED_CLIENT 미지원클라이언트버전 F ETC 기타오류 H FAILED_TO_SEND_MESSAGE 카카오시스템오류 I INVALID_PHONE_NUMBER 전화번호오류 J SAFETY_PHONE_NUMBER 050 안심번호발송불가 L MESSAGE_LENGTH_OVER_LIMIT 메시지길이제한오류 M TEMPLATE_NOT_FOUND 템플릿을찾을수없음 S SPAM 발신번호검증오류 U NO_MATCHED_TEMPLATE 메시지가템플릿과일치하지않음 V FAILED_TO_MATCH_TEMPLATE 메시지가템플릿과비교실패 0 E_OK 성공 MSG_RSLT 1 E_TIMEOUT 전송시간초과 2 E_INVALID_PHONE 잘못된전화번호 / 비가입자 5 E_NOT_ACK 통신사결과미수신 8 E_PHONE_BUSY 단말기 BUSY 9 E_SHADOW_REGION 음영지역 a E_INSUFFICIENT 건수부족 b E_REJECT_ITER 전송권한없음 c E_DUP_KEY 중복된키접수차단 d E_DUP_PHONE 중복된수신번호접수차단 e E_SERVER_ERROR 서버내부에러 o E_TIMEOUT_AGENT TIME OUT 처리 (Agent 내부 ) p E_DUPLICATE_PHONE_MSG 메시지본문중복차단 (Agent 내부 ) q E_DUPLICATE_KEY 메시지중복키체크 (Agent 내부 ) t E_TOGETHER_COUNT 잘못된동보전송수신번호 14

15 리스트카운트 (Agent 내부 ) A E_MSG_FULL 단말기메시지저장개수초과 B E_SERVICE_STOP 단말기일시서비스정지 C E_ETC_PHONE 기타단말기문제 D E_DENY 착신거절 E E_POWER_OFF 전원꺼짐 F E_ETC 기타 G E_INNER_FORMAT_ERR 내부포맷에러 H E_TELCO_FORMAT_ERR 통신사포맷에러 I E_UNACCEPTED_PHONE SMS/MMS 서비스불가단말기 J E_MSG_FAIL 착신측호불가상태 K E_TELCO_MSG_DEL 통신사에서메시지삭제처리 L E_TELCO_QUE_FULL 통신사메시지처리불가상태 M E_WIRELESS_FAIL 무선망단전송실패 S E_SPAM 스팸 V E_CONTENTS_SIZE_ERR 컨텐츠사이즈초과 U E_CONTENTS_ERR 잘못된컨텐츠 15

CDMS 개발 내역서

CDMS 개발 내역서 카카오알림톡 API 사용자가이드 2017.11 Copyright 2015 KTH Corp. All Rights Reserved 1 변경내역 작성일자버전변경사항 2017.05.15 1.0 배포 2017.05.24 1.1 사용예제업데이트 2017.06.15 1.2 템플릿조회 API 업데이트 2017.07.05 1.3 발신번호등록 / 인증 API 업데이트 2017.08.16