32
4. xit mms API
gitea-관리자 edited this page 3 months ago
1. 문자발송 요청 API
문자발송 등록은 POST요청으로 JSON데이터를 보내면 응답을 JSON 데이터로 받습니다.
요청 URL
/intf/message/regist
파라미터(JSON)
JSON요청을 다음 형식과 같이 보냅니다.
JSON요청 중에서 args의 argName프로퍼티는 TB_MSG_STNG 테이블의 TMPLT_CN 컬럼의 내용 중에서 {{로 시작해서 }}로 끝나는 문자열과 동일한 값으로 입력합니다.
{
//요청시스템(코드값,필수) : 공통코드MSG005(프로젝트별로 다를 수 있음. 예시: 01=엑스아이티,02=진우,03=이노)
"reqSys" : "03",
//메시지발송목적(코드값,필수) : 공통코드MSG006(프로젝트별로 다를 수 있음. 예시: 01=주정차위반단속,02=이동주차안내(단속기),03=이동주차안내,04=고장신고접수,05=화재의심경고,06=화재발생경고)
"msgPrps" : "02",
//메시지발송상세목적(문자열,선택사항)
"msgDtlPrps" : "",
//시군구코드 5자리(필수)
"sggCd" : "50000",
//과태료업무구분(선택사항) : 장애인주차구역위반(DPV),전기차주차구역위반(ECA) 등등
"taskSeCd" : "",
//발송 요청 목록(배열)
"reqs" : [
{
//수신번호(테스트시에는 끝자리를 00~09 이외의 값으로 지정해서 테스트하시기 바랍니다. 테스트시 실제 문자발송이 되지 않기 때문에 결과코드는 모두 기타오류(9999)로 표시됩니다.)
"recptnNo" : "01099999999",
//발송예약일시(선택사항) : 연월일시분초(14자리)
"resDate" : "20241113131415"
//변수목록(배열(변수명,변수이름))
"args" : [
{ "argName" : "주차시간", "argValue": "12시간" },
{ "argName" : "충전소", "argValue": "제주시청 전기차 충전소" },
{ "argName" : "충전기", "argValue": "(완속)시청_충전기8-88" },
{ "argName" : "차량번호", "argValue": "88나8888" },
{ "argName" : "입차시간", "argValue": "2024-12-09 05:30" }
]
}
]
}
결과(JSON)
saved가 false일 경우 전체 요청 등록이 실패하며 발송요청 테이블에 등록되지 않습니다.
failList 배열 안의 요청들은 실패 처리된 자료들이며 발송요청 테이블에 등록되지 않습니다.
{
//전체 요청 성공 여부
"saved": true,
//전체 요청 실패 사유(필수파라미터 미입력 오류, 템플릿 조회 오류 등)
"failRsn" : null,
"resultMap": {
//개별 요청 등록 성공 목록
"successList": [],
//개별 요청 등록 실패 목록(failRsn 실패사유 : 수신번호 오류, 예약발송일시 오류 등)
"failList": []
}
}
API 연계 테스트 방법
응용프로그램으로 테스트
- 비주얼스튜디오코드+익스텐션 : https://code.visualstudio.com/
1. 비주얼스튜디오코드 설치
2. 비주얼스튜디오코드 실행 후 "REST Client" 익스텐션 검색 및 설치
3. 확장자가 .http인 파일 생성 후 비주얼스튜디오코드로 열기
4. .http파일 내용 작성
예시)
POST 아이피또는도메인주소/intf/message/regist
Content-Type: application/json; charset=UTF-8
{
"reqSys" : "03",
"msgPrps" : "02",
"msgDtlPrps" : "",
"sggCd" : "50000",
"taskSeCd" : "",
"reqs" : [
{
"recptnNo" : "01011110632",
"args" : [
{ "argName" : "주차시간", "argValue": "12시간" },
{ "argName" : "충전소", "argValue": "KCC스위첸 동측 공영주차장(아란길공영주차장)" },
{ "argName" : "충전기", "argValue": "(급속)KCC스위첸 동측 공영주차장(아란길공영주차장)_02" },
{ "argName" : "차량번호", "argValue": "188나8888" },
{ "argName" : "입차시간", "argValue": "2024-12-23 05:30" }
]
}
]
}
5. 작성한 내용 위에 Send Request 링크가 생성됨.
6. Send Request 링크 클릭시 서버와 통신함.
- 포스트맨 : https://www.postman.com/
- SoapUI : https://www.soapui.org/
1. SoapUI 설치
2. SoapUI 실행 후 메뉴바 -> File -> Create Empty Project
3. 신규로 생성된 프로젝트에 우클릭 -> New REST Service From URI 클릭 -> 아이피또는도메인주소/intf/message/regist 입력
4. 좌측 네비게이터에 트리 형태로 총 5레벨(프로젝트-서비스-리소스-메소드-리퀘스트) 요소 생성
5. 메소드 프로퍼티(4레벨) 변경 : 좌측하단의 HTTP Method를 GET 에서 POST 로 변경
6. 리퀘스트 프로퍼티(5레벨) 변경 : 좌측하단의 Encoding을 UTF-8 로 변경
7. 리퀘스트 더블 클릭 -> 팝업에서 좌측하단에 요청을 보낼 json 작성 -> 팝업의 좌측상단 실행 버튼 클릭
예시)
{
"reqSys" : "03",
"msgPrps" : "02",
"msgDtlPrps" : "",
"sggCd" : "50000",
"taskSeCd" : "",
"reqs" : [
{
"recptnNo" : "01011110632",
"args" : [
{ "argName" : "주차시간", "argValue": "12시간" },
{ "argName" : "충전소", "argValue": "KCC스위첸 동측 공영주차장(아란길공영주차장)" },
{ "argName" : "충전기", "argValue": "(급속)KCC스위첸 동측 공영주차장(아란길공영주차장)_02" },
{ "argName" : "차량번호", "argValue": "188나8888" },
{ "argName" : "입차시간", "argValue": "2024-12-23 05:30" }
]
}
]
}
리눅스 명령어로 테스트
- CURL 명령어 + json파일
1. json 파일을 작성한다.
json파일 작성 예시)
{
"reqSys" : "03",
"msgPrps" : "02",
"msgDtlPrps" : "",
"sggCd" : "50000",
"taskSeCd" : "",
"reqs" : [
{
"recptnNo" : "01011110632",
"args" : [
{ "argName" : "주차시간", "argValue": "12시간" },
{ "argName" : "충전소", "argValue": "KCC스위첸 동측 공영주차장(아란길공영주차장)" },
{ "argName" : "충전기", "argValue": "(급속)KCC스위첸 동측 공영주차장(아란길공영주차장)_02" },
{ "argName" : "차량번호", "argValue": "188나8888" },
{ "argName" : "입차시간", "argValue": "2024-12-23 05:30" }
]
}
]
}
2. curl 명령어를 사용한다.
curl 명령어 사용 예시)
curl -X POST -H "Content-Type: application/json" 아이피또는도메인주소/intf/message/regist -d @/home/dev01/applications/demon/nuri2/단속기이동안내.json
JAVA로 테스트
- cokr.xit.foundation.web.WebClient 클래스를 사용한 통신
1. pom.xml 파일을 수정하여 xit-foundation 라이브러리 의존성 추가한다.
<dependency>
<groupId>cokr.xit.base</groupId>
<artifactId>xit-foundation</artifactId>
<version>23.04.01-SNAPSHOT</version>
</dependency>
2. WebClient를 사용한다.
예시)
public class someClass {
@Resource(name="objectMapper")
private ObjectMapper objectMapper;
public void someMethod() {
HttpResponse<String> apiRslt = new WebClient().post(request -> {
request.contentType(WebClient.Request.ContentType.JSON);
request.uri(url + "/intf/message/regist");
request.data("msgPrps", "01");
request.data("reqSys", "01");
request.data("sggCd", "50000");
request.data("teskSeCd", "");
request.data("msgDtlPrps", "");
request.data("reqs", reqs);
});
String rslt = apiRslt.body();
DataObject respDataObject = new DataObject();
try {
respDataObject = objectMapper.readValue(rslt, new TypeReference<DataObject>() {});
} catch (JsonMappingException e) {
e.printStackTrace();
} catch (JsonProcessingException e) {
e.printStackTrace();
}
}
}
브라우저(javascript)에서 테스트
- ajax.post 함수로 통신
1. pom.xml 파일을 수정하여 xit-web-res 라이브러리 의존성 추가한다.
<dependency>
<groupId>cokr.xit.base</groupId>
<artifactId>xit-web-res</artifactId>
<version>23.04.01-SNAPSHOT</version>
</dependency>
2. 공통 자바스크립트 파일을 jsp 페이지에 삽입한다.
<script src="<c:url value="/webjars/3rd-party/sneat/libs/jquery/jquery.js"/>" ></script>
<script src="<c:url value="/webjars/js/base/base.js"/>"></script>
3. ajax.post를 호출한다.
let data = {
"reqSys" : "03",
"msgPrps" : "02",
"msgDtlPrps" : "",
"sggCd" : "50000",
"taskSeCd" : "",
"reqs" : [
{
"recptnNo" : "01011110632",
"args" : [
{ "argName" : "주차시간", "argValue": "12시간" },
{ "argName" : "충전소", "argValue": "KCC스위첸 동측 공영주차장(아란길공영주차장)" },
{ "argName" : "충전기", "argValue": "(급속)KCC스위첸 동측 공영주차장(아란길공영주차장)_02" },
{ "argName" : "차량번호", "argValue": "188나8888" },
{ "argName" : "입차시간", "argValue": "2024-12-23 05:30" }
]
}
]
};
ajax.post({
url : 아이피또는도메인주소+"/intf/message/regist",
data : data,
success : function(resp){
console.log(resp);
}
});
2. 문자발송 요청 자료 목록 조회 API
문자발송 요청 자료에 대한 발송상태, 발송처리일시 등을 조회할 수 있습니다.
목록 조회 클래스,메소드
업무 프로젝트별로 MessageController 클래스를 상속한 후 @requestMapping 어노테이션으로 url을 매핑하고 list메소드를 호출하여 문자발송요청 목록을 조회할 수 있습니다.
클래스명 : co.kr.xit.interfaces.message.MessageController
메소드명 : public ModelAndView list(MessageQuery messageQuery);
파라미터(MessageQuery.class)
요청등록일자 시작일과 종료일을 필수로 지정하여 다음 변수를 파라미터로 보냅니다.
private String sggCd; //시군구코드
private String taskSeCd; //업무구분코드
private String svcType; //서비스유형(XMS,RCS,알림톡) : 공통코드 MSG004
private String msgPrps; //발송목적 : 공통코드 MSG006
private String schInputYmdFrom; //요청등록일자 조회조건(시작일)(필수)
private String schInputYmdTo; //요청등록일자 조회조건(종료일)(필수)
private String transmitStts; //발송상태 : 공통코드 MSG007
결과(List<DataObject>)
조회결과는 jsonView형식으로 List변수에 다음과 같은 값을 응답합니다.
MSG_KEY : nuri2 문자발송 테이블 PK
SUB_ID : 국가정보자원관리원과 협의한 기관만 입력하는 파라미터
USER_KEY :
USER_GROUP :
USER_ID :
USER_JOBID :
CENTER_KEY :
MSG_PRIORITY : 발송 우선순위 코드
MSG_STATE : 메시지 상태 코드
MSG_STATE_NM : 메시지 상태 코드 명
INPUT_DATE : 발송 요청 등록일시(Date형식)
INPUT_DT : 발송 요청 등록일시(문자열 14자리)
RES_DATE : 발송 예약 일시(Date형식)
RES_DT : 발송 예약 일시(문자열 14자리)
QUE_DATE : 메시지 수집 일시
SENT_DATE : 메시지 전송 일시
RSLT_DATE : 핸드폰에 전달된 시간
REPORT_DATE : 게이트웨이에서 결과를 수신한 시간
RSLT_CODE : 결과 코드
RSLT_NET : 결과처리 통신사
RSLT_TYPE : 결과 타입 코드
SENT_COUNT : 발송횟수
HISTORY_MSG_TYPE : n차 발송 메시지 유형 이력
HISTORY_RSLT_CODE : n차 발송 결과코드 이력
IDENTIFIER :
PHONE : 수신전화번호
CALLBACK : 발신전화번호
MSG_TYPE_1 : 1차발송 메시지 유형
CONTENTS_TYPE_1 : 1차발송 콘텐츠 유형
QUE_DATE_1 : 1차발송 메시지 수집 일시
SENT_DATE_1 : 1차발송 일시
MSG_TYPE_2 : 2차발송 메시지 유형
CONTENTS_TYPE_2 : 2차발송 콘텐츠 유형
QUE_DATE_2 : 2차발송 메시지 수집 일시
SENT_DATE_2 : 2차발송 일시
MSG_TYPE_3 : 3차발송 메시지 유형
CONTENTS_TYPE_3 : 3차발송 콘텐츠 유형
QUE_DATE_3 : 3차발송 메시지 수집 일시
SENT_DATE_3 : 3차발송 일시
XMS_RSLT_CODE : xMS 처리 결과 코드
XMS_RSLT_NET : xMS 처리 통신사
XMS_RSLT_DATE : xMS로 핸드폰에 전달된 시간
XMS_REPORT_DATE : xMS 게이트웨이에서 결과를 수신한 시간
ALT_RSLT_CODE : 알림톡 처리 결과 코드
ALT_RSLT_NET : 알림톡 처리 통신사
ALT_RSLT_DATE : 알림톡으로 핸드폰에 전달된 시간
ALT_REPORT_DATE : 알림톡 게이트웨이에서 결과를 수신한 시간
RCS_RSLT_CODE : RCS 처리 결과 코드
RCS_RSLT_NET : RCS 처리 통신사
RCS_RSLT_DATE : RCS로 핸드폰에 전달된 시간
RCS_REPORT_DATE : RCS 게이트웨이에서 결과를 수신한 시간
XMS_SUBJECT : xMS 제목
XMS_TEXT : xMS 내용
XMS_FILE_NAME_1 : xMS파일명1
XMS_FILE_NAME_2 : xMS파일명2
XMS_FILE_NAME_3 : xMS파일명3
ALT_COUNTRY_CODE : 알림톡 국가코드
ALT_SENDER_KEY : 알림톡 프로필키
ALT_TEMPLATE_CODE : 알림톡 템플릿코드
ALT_JSON : 알림톡 내용
RCS_BRAND_ID : RCS브랜드아이디
RCS_BRAND_KEY : RCS브랜드키
RCS_MESSAGE_BASE_ID : RCS베이스아이디
RCS_JSON : RCS 내용
REQ_SYS : 발송요청시스템 코드
REQ_SYS_NM : 발송요청시스템
MSG_PRPS : 문자발송 목적 코드
MSG_PRPS_NM : 문자발송 목적
MSG_DTL_PRPS : 상세 문자발송 목적
SGG_CD : 시군구코드
SGG_NM : 시군구명
TASK_SE_CD : 업무구분코드
TASK_SE_NM : 업무구분명
DMND_IP : 발송요청자IP주소
TRANSMIT_STTS_NM : 발송상태명