대용량 SMS 서비스 API 사용자가이드 2017.07 Copyright 2015 KTH Corp. All Rights Reserved 1
변경내역 작성일자버전변경사항 2013.03.14 1.0 배포 2013.04.19 1.1 사용예제업데이트 2013.05.07 1.2 report 기능수정 2013.05.29 1.3 send_time 형식수정 2013.07.19 1.4 BaseURL 변경 2013.12.20 1.5 MMS 예제수정등 2014.01.27 1.6 에러코드업데이트 2015.08.05 1.7 에러코드업데이트 2015.09.17 1.8 발신번호등록기능추가 2015.10.30 1.9 발신번호관련에러코드업데이트 2016.04.27 2.0 SMS 발송설명문구추가 2016.07.05 2.1 SMS Byte 업데이트 2016.10.07 2.2 에러코드업데이트 2016.11.03 2.3 URL 변경 (io > co.kr) 2017.06.15 2.4 발신번호등록 API 기존, 신규내용추가 2017.07.05 2.5 발신번호신규 API 적용. 2
[ 목차 ] 1 범위 (Scope)... 4 2 개요... 5 2.1 API 목록... 5 2.2 인증... 5 2.3 공통정의사항... 5 3 API 정의... 6 3.1 SMS API... 6 3.2 LMS API... 7 3.3 MMS API... 9 3.4 Report 조회... 10 3.5 발신번호등록 / 인증... 오류! 책갈피가정의되어있지않습니다. 3.6 발신번호리스트조회... 11 4 Test Summary... 14 5 발신번호등록규칙... 14 6 코드및메시지정의... 15 6.1 Appendix Report Code... 15 3
1 범위 (Scope) 본규격서는 HTTP 프로토콜을기반으로작성되었습니다. 본규격서는 Message 전송에대한규격을정의하고있습니다. 4
2 개요 2.1 API 목록 종류 API 기능 SMS /sms/{client_id} SMS 전송기능 LMS /lms/{client_id} LMS 전송기능 MMS /mms/{client_id} MMS 전송기능 Report /report/{client_id} Report 조회기능 발신번호 2.2 인증 /sendnumber/save/{client_id} /sendnumber/list/{client_id} 발신번호등록 / 인증 등록한발신번호리스트조회기능 구매시발급받은 Key 의코드값을헤더 x-waple-authorization 의값으로설정 x-waple-authorization: MS0xMzY1NjY2MTAyNDk0LTA2MWE4ZDgyLTZhZmMtNGU5OS05YThkLTgyNmFmYzVlOTkzZQ== 2.3 공통정의사항 공통URL - 발송, 리포트 http://api.apistore.co.kr/ppurio/{apiversion}/message/{message_type}/{client_id} (sms, lms, mms, report 중택 1) - 발신번호 http://api.apistore.co.kr/ppurio/{apiversion}/sendnumber/{type}/{client_id} {client_id} 는 API스토어에가입한후해당 API를사용 ( 구매 ) 신청한 ID. {apiversion} : 1 ( 발신번호인증시 2) {type}: 등록-save, 조회-list 공통헤더 Content-Type: application/x-www-form-urlencoded; charset=utf-8 x-waple-authorization: MS0xMzY1NjY2MTAyDk0LTA2MWE4ZDgyLTZhZmMtNGU5OS05YThkLTgyNmFmYzVlOTkzZ Q== * KSC5601에업는특수기호및문자입력시정상발송되지않음 5
3 API 정의 3.1 SMS API /sms/{client_id} 기본정보 기능 : SMS 전송기능 방식 : POST 호출 URL: http://api.apistore.co.kr/ppurio/{apiversion}/message/sms/{client_id} 요청파라미터 send_time Yes 발송시간 ( 없을경우즉시발송 ) 20130529171111 (2013-05-29-17:11:11) send_phone No 등록된발신자전화번호 ( - 제외 / 숫자만입력 ) 01012345678 No 수신자전화번호 ( 동보발송시콤마, 구분자 dest_phone 사용 ) ( - 제외 ) 01012345678 send_name Yes 발신자이름 (32byte 미만 ) dest_name Yes 수신자이름 (32byte 미만 ) msg_body No 메시지의내용 (90byte 미만 ) - 90byte가넘을경우 LMS로자동변환발송 smsexcel multipart/form-data Yes 대량전송할경우엑셀파일에파라미터데이터입력하여보냄 ( 필드구성 : 발송시간 수신자번호 수신자이름 발신자번호 발신자이름 제목 내용 ) 반환값 result_code No 처리결과코드 100 : User Error 200 : OK 300 : Parameter Error 400 : Etc Error 500 : 발신번호사전등록제에의한미등록차단 600 : 선불제충전요금부족 6
result_msg No 잔금부족 [ 미발송목록 ] 01012345678 cmid No 서버에서생성한 request 를식별할수있는 유일한키 사용예제 REQUEST URL http://api.apistore.co.kr/ppurio/1/message/sms/{client_id} POST Content-Type: application/x-www-form-urlencoded; charset=utf-8 Header x-waple-authorization: MS0xMzY1NjY2MTAyNDk0LTA2MWE4ZDgyLTZhZmMtNGU5OS05YThkLTgyNmFmYzVlOTkzZQ== Parameter dest_phone=01043558081 send_phone=01043558081 msg_body=test RESONSE 200 Access-Control-Allow-Origin Content-Type: application/json { result_code : 200, cmid : 20130314163439459 } 3.2 LMS API /lms/{client_id} 기본정보 기능 : LMS 전송기능 방식 : POST 호출 URL: http://api.apistore.co.kr/ppurio/{apiversion}/message/lms/{client_id} 요청파라미터 send_time send_phone Yes 발송시간 ( 없을경우즉시발송 ) 20130529171111 (2013-05-29-17:11:11) No 등록된발신자전화번호 ( - 제외 / 숫자만입력 ) 01012345678 No 수신자전화번호 ( 동보발송시콤마, 구분자 dest_phone 사용 ) ( - 제외 ) 01012345678 7
send_name Yes 발신자이름 (32byte 미만 ) dest_name Yes 수신자이름 (32byte 미만 ) subject Yes 메시지의제목 (60byte 미만 ) msg_body No 메시지의내용 (2000byte 미만 ) Yes 대량전송할경우엑셀파일에파라미터데 smsexcel 반환값 multipart/form-data 이터입력하여보냄 ( 필드구성 : 발송시간 수신 자번호 수신자이름 발신자번호 발신자이름 제 목 내용 ) No 처리결과코드 result_code result_msg 100 : User Error 200 : OK 300 : Parameter Error 400 : Etc Error 500: 발신번호사전등록제에의한미등록차단 600 : 선불제충전요금부족 No 잔금부족 [ 미발송목록 ] 01012345678 cmid No 서버에서생성한 request 를식별할수있는 유일한키 사용예제 REQUEST URL http://api.apistore.co.kr/ppurio/1/message/lms/{client_id} POST Content-Type: application/x-www-form-urlencoded; charset=utf-8 Header x-waple-authorization: MS0xMzY1NjY2MTAyNDk0LTA2MWE4ZDgyLTZhZmMtNGU5OS05YThkLTgyNmFmYzVlOTkzZQ== Parameter dest_phone=01043558081 send_phone=01043558081 msg_body=lmstest LMSTEST LMSTEST LMSTEST LMSTEST LMSTEST LMSTEST LMSTEST LMSTEST RESONSE 200 Access-Control-Allow-Origin Content-Type: application/json 8
{ result_code : 200, cmid : 20130314163439459 } 3.3 MMS API /mms/{client_id} 기본정보 기능 : MMS 전송기능 방식 : POST 호출 URL: http://api.apistore.co.kr/ppurio/{apiversion}/message/mms/{client_id} 요청파라미터 send_time Yes 발송시간 ( 없을경우즉시발송 ) 20130529171111 (2013-05-29-17:11:11) send_phone No 등록된발신자전화번호 ( - 제외 / 숫자만입력 ) 01012345678 No 수신자전화번호 ( 동보발송시콤마, 구분자 dest_phone 사용 ) ( - 제외 ) 01012345678 send_name Yes 발신자이름 (32byte 미만 ) dest_name Yes 수신자이름 (32byte 미만 ) subject Yes 메시지의제목 (60byte 미만 ) msg_body No 메시지의내용 (2000byte 미만 ) file multipart/form-data Yes 전송하는첨부파일 (TXT[2000byte 미만 ], JPG[20kbyte 이하, 최대 3개첨부가능, 이미지파일합 40kbyte 이하 ], MA3[16kz 이하 ] 파일전송가능 ) 반환값 result_code No 처리결과코드 100 : User Error 200 : OK 300 : Parameter Error 400 : Etc Error 500: 발신번호사전등록제에의한미등록차단 600 : 선불제충전요금부족 9
result_msg No 잔금부족 [ 미발송목록 ] 01012345678 cmid No 서버에서생성한 request 를식별할수있는 유일한키 사용예제 REQUEST URL http://api.apistore.co.kr/ppurio/1/message/mms/{client_id} POST Content-Type: multipart/form-data; boundary=----webkitformboundary8uhbmc4vavbxt6z3 Header x-waple-authorization: MS0xMzY1NjY2MTAyNDk0LTA2MWE4ZDgyLTZhZmMtNGU5OS05YThkLTgyNmFmYzVlOTkzZQ== Parameter dest_phone=01043558081 send_phone=01043558081 msg_body=mms file={ 이미지경로 } RESONSE 200 Access-Control-Allow-Origin Content-Type: application/json { result_code : 200, cmid : 20130314163439459 } 3.4 Report 조회 /report/{client_id} 기본정보 기능 : report 조회기능 방식 : GET 호출 URL: http://api.apistore.co.kr/ppurio/{apiversion}/message/report/{client_id} 요청파라미터 cmid No 송신측메시지 ID client_id No 서비스사용자 ID 반환값 dest_phone No 수신자의전화번호 ( - 제외 ) 01012345678 10
No 리포트시간 Report_time yyyymmddhhmmss 20130302143001 call_status No 처리결과코드 (Appendix참조) umid No 서버에서생성한 request를식별할수있는유일한키 사용예제 REQUEST URL http://api.apistore.co.kr/ppurio/1/message/report/{client_id}?cmid=20130313171524964 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 {"dest_phone":"01043558081","report_time":"1363162529","call_status":"4100","umid":"apisto_a17200 316252414981818"} 3.5 발신번호인증 / 등록 /sendnumber/save/{client_id} 기능 : 발신번호인증 / 등록 API (apiversion = 2) 기본정보 인증방법 : SMS, VMS 중 1 개선택 방식 : POST 호출 URL: http://api.apistore.co.kr/ppurio/{apiversion}/sendnumber/save/{client_id} 요청파라미터 sendnumber No 발신번호 ( - 제외 ) * 발신번호등록규칙참조 comment No 코멘트 (200자) pintype Yes 인증방법 (SMS. VMS 중 1 개선택 ) 11
pincode Yes 인증번호 (SMS 인증번호 (6자리), VMS인증번호 (2자리)) 반환값 result_code No 처리결과코드 200 : 성공 300 : 파라메터에러 400 : 인증업데이트중에러 500 : 이미등록된번호 600 : 일치하지않는인증번호 700 : 핀코드인증시간만료 (3분이후만료이며재등록요청해야함.) sendnumber No 등록한번호 사용예제 REQUEST < 요청 > URL http://api.apistore.co.kr/ppurio/2/sendnumber/save/{client_id} POST Content-Type: application/x-www-form-urlencoded; charset=utf-8 Header x-waple-authorization: MS0xMzY1NjY2MTAyNDk0LTA2MWE4ZDgyLTZhZmMtNGU5OS05YThkLTgyNmFmYzVlOTkzZQ== Parameter sendnumber=0232894122&comment= 케이티하이텔대표번호 &pintype=sms 또는 VMS < 인증 > URL http://api.apistore.co.kr/ppurio/2/sendnumber/save/{client_id} POST Content-Type: application/x-www-form-urlencoded; charset=utf-8 Header x-waple-authorization: MS0xMzY1NjY2MTAyNDk0LTA2MWE4ZDgyLTZhZmMtNGU5OS05YThkLTgyNmFmYzVlOTkzZQ== Parameter sendnumber=0232894122&comment= 케이티하이텔대표번호 &pintype=sms&pincode=123456(6자리) (pintype=vms 일경우 pincode=12(2자리 )) 12
RESONSE [ 요청 ] 200 Access-Control-Allow-Origin: * Content-Type: application/json {"result_code":"200","sendnumber":"0232894122"} [ 인증 ] 200 Access-Control-Allow-Origin: * Content-Type: application/json {"result_code":"200","sendnumber":"0232894122"} 3.6 발신번호리스트조회 /sendnumber/list/{client_id} 기본정보 기능 : list 조회기능 방식 : GET 호출 URL: http://api.apistore.co.kr/ppurio/{apiversion}/sendnumber/list/{client_id} 요청파라미터 sendnumber Yes 발신번호 ( - 제외 ) 입력안할경우전체리스트반환 반환값 result_code No 처리결과코드 100 : User Error 200 : OK 300 : Parameter Error 400 : Etc Error client_id No API스토어계정 comment No 등록내용 sendnumber No 등록한번호 사용예제 REQUEST 13
URL http://api.apistore.co.kr/ppurio/1/sendnumber/list/{client_id} 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":"0232892888"}, { client_id : {client_id}, comment : null, sendnumber":"0212345678"} 4 Test Summary TEST는실제로메시지전송은되지않으며, 요청한데이터에대한처리결과만확인가능. URL을제외한파라미터및리턴데이터는위와동일. URL SMS http://api.apistore.co.kr/ppurio_test/1/message_test/sms/{client_id} POST LMS http://api.apistore.co.kr/ppurio_test/1/message_test/lms/{client_id} MMS http://api.apistore.co.kr/ppurio_test/1/message_test/mms/{client_id} GET REPORT http://api.apistore.co.kr/ppurio_test/1/message_test/report/{client_id} TEST_KEY ( 택 1) MS0xMzY1NjY2MTAyNDk0LTA2MWE4ZDgyLTZhZmMtNGU5OS05YThkLTgyNmFmYzVlOTkzZQ== MzkxLTEzNjU2NjcxMjgwNjEtYTZlNjZjZjEtY2I2Ny00ZTAxLWE2NmMtZjFjYjY3NmUwMTIz MTItMTM2NTc1MzA4MjQ3Ni1lNzIxOWQzNy1jZTlmLTRiM2QtYTE5ZC0zN2NlOWZlYjNkMjg= 5 발신번호등록규칙 - 기본 : 8자리 ~ 11자리발신번호 - 유선전화번호 : 지역번호를포함 - 이동통신전화번호 - 대표전화번호 : 15xx, 16xx, 18xx( 번호앞에지역번호사용금지 ) * 위규칙외등록필요시담당자 (tel: 02-3289-4122, e-mail: apistore.help@kt.com) 에게문의 14
6 코드및메시지정의 6.1 Appendix Report Code 구분 Report Code Description 4100 전달 4421 타임아웃 4426 재시도한도초과 4425 단말기호처리중 4400 음영지역 4401 단말기전원꺼짐 4402 단말기메시지저장초과 4410 잘못된번호 4422 단말기일시정지 4427 기타단말기문제 4405 단말기 busy 4423 단말기착신거부 4412 착신거절 4411 NPDB 에러 SMS 4428 시스템에러 4404 가입자위치정보없음 4413 SMSC 형식오류 4414 비가입자, 결번, 서비스정지 4424 URL SMS 미지원폰 4403 메시지삭제됨 4430 스팸 4431 발송제한수신거부 ( 스팸 ) 4432 번호도용문자차단서비스에가입된 발신번호 ( 개인 ) 사용 4433 번호도용문자차단서비스에가입된 발신번호 ( 개인 ) 사용 4434 발신번호사전등록제에의한미등록차단 4435 KISA 에스팸신고된발신번호사용 4436 발신번호사전등록제번호규칙위반 4420 기타에러 MMS/LMS 6600 전달 6601 타임아웃 15
6602 핸드폰호처리중 6603 음영지역 6604 전원이꺼져있음 6605 메시지저장개수초과 6606 잘못된번호 6607 서비스일시정지 6608 기타단말기문제 6609 착신거절 6610 기타에러 6611 통신사의 SMC 형식오류 6612 게이트웨이의형식오류 6613 서비스불가단말기 6614 핸드폰호불가상태 6615 SMC 운영자에의해삭제 6616 통신사의메시지큐초과 6617 통신사의스팸처리 6618 공정위의스팸처리 6619 게이트웨이의스팸처리 6620 발송건수초과 6621 메시지의길이초과 6622 잘못된번호형식 6623 잘못된데이터형식 6624 MMS 정보를찾을수없음 6625 NPDB 에러 6626 080 수신거부 (SPAM) 6627 발신제한수신거부 (SPAM) 6628 번호도용문자차단서비스에가입된 발신번호 ( 개인 ) 사용 6629 번호도용문자차단서비스에가입된 발신번호 ( 개인 ) 사용 6630 서비스불가번호 6631 발신번호사전등록제에의한미등록차단 6632 KISA 에스팸신고된발신번호사용 6633 발신번호사전등록제번호규칙위반 6670 이미지파일크기제한 공통 9903 선불사용자사용금지 9904 Block time( 날짜제한 ) 16
9082 발송해제 9083 IP 차단 9023 Callback error 9905 Block time( 요일제한 ) 9010 아이디틀림 9011 비밀번호틀림 9012 중복접속량많음 9013 발송시간지난데이터 9014 시간제한 ( 리포트수신대기 timeout) 9020 9021 Wrong Data Format 9022 Wrong Data Format(cinfo 가특수 문자 /, 공백을포함하고있다 ) 9080 Deny User Ack 9214 Wrong Phone Num 9311 Fax File Not Found 9908 PHONE, FAX 선불사용자제한기능 9090 기타에러 -1 잘못된데이터형식, 발송오류 17