Delivery Tracker - 배송 조회 API 서비스 연동하기

https://tracker.delivery/guide/ 에서 제공하는 API를 연동했던 내용을 남긴다.

글 정리 하기가 귀찮아 그냥 소스코드만 싸지르고 나중에 정리하는 걸로... 요즘 왜 이렇게 피곤한지...

해당 API는 MIT 라이센스이다.

 

- EX) https://apis.tracker.delivery/carriers/[kr.cjlogistics]/tracks/[invoiceNum]

위의 URL과같이 API 호출 결과는 대충 아래 json문자열이다.

{
   "carrier":{
      "id":"kr.cjlogistics",
      "name":"CJ Logistics",
      "tel":"+8215881255"
   },
   "from":{
      "name":"소**",
      "time":"2023-10-23T18:23:35+09:00"
   },
   "to":{
      "name":"강**",
      "time":null
   },
   "progresses":[
      {
         "time":"2023-10-23T18:23:35+09:00",
         "status":{
            "id":"at_pickup",
            "text":"집화처리"
         },
         "location":{
            "name":"경기평택용이"
         },
         "description":"보내시는 고객님으로부터 상품을 인수받았습니다"
      },
      {
         "time":"2023-10-23T19:30:17+09:00",
         "status":{
            "id":"in_transit",
            "text":"간선상차"
         },
         "location":{
            "name":"평택A"
         },
         "description":"물류터미널로 상품이 이동중입니다."
      },
      {
         "time":"2023-10-24T06:51:05+09:00",
         "status":{
            "id":"in_transit",
            "text":"간선상차"
         },
         "location":{
            "name":"곤지암Hub"
         },
         "description":"배송지역으로 상품이 이동중입니다."
      },
      {
         "time":"2023-10-24T10:35:24+09:00",
         "status":{
            "id":"in_transit",
            "text":"간선하차"
         },
         "location":{
            "name":"강동A"
         },
         "description":"고객님의 상품이 배송지에 도착하였습니다.(배송예정:홍길동 010-1234-1234)"
      },
      {
         "time":"2023-10-24T13:00:50+09:00",
         "status":{
            "id":"delivered",
            "text":"배송완료"
         },
         "location":{
            "name":"서울암사중앙"
         },
         "description":"고객님의 상품이 배송완료 되었습니다.(담당사원:홍길동 010-1234-1234)"
      },
      {
         "time":"2023-10-24T14:33:29+09:00",
         "status":{
            "id":"out_for_delivery",
            "text":"배송출발"
         },
         "location":{
            "name":"서울암사중앙"
         },
         "description":"고객님의 상품을 배송할 예정입니다.(17~19시)(배송담당:홍길동 010-1234-1234)"
      }
   ],
   "state":{
      "id":"out_for_delivery",
      "text":"배송출발"
   }
}

1. 화면쪽에서 호출하는 AJAX

function jsView() {

    $('.js_traceDeliveryCop').each(function(e){
        var invoiceNo = $(this).data("invoice");//송장번호
        var dcApiId = $(this).data("apiid");//배송업체ID
        var ordiSeq = $(this).data("ordiseq");//상품순서
        if(invoiceNo.length != 0 && dcApiId.length != 0){//송장번호,배송업체ID가 있을때만 API호출
            $.ajax({
                async: true,
                traditional:true,
                method : "get",
                url : "${ctx}/getInvoiceStatus.ajax",
                dataType : "json",
                data : {
                    invoiceNo : invoiceNo,
                    dcApiId   : dcApiId
                },
                success : function(data) {
                    var dataCode = data.code;
                    if(dataCode == 0){//결과 코드 0=성공, 0이외는 모두 실패
                        $('#traceDeliveryCop_'+invoiceNo+'_'+ordiSeq).text(data.message);
                        $('#traceDeliveryCop_'+invoiceNo+'_'+ordiSeq).prop('title',data.etc);
                    }else{
                        $('#traceDeliveryCop_'+invoiceNo+'_'+ordiSeq).text("-");
                        $('#traceDeliveryCop_'+invoiceNo+'_'+ordiSeq).prop('title',data.message);
                    }			
                },
                error : function() {
                    //alert("배송추적 API오류!!");
                }
            });

        }else{
            //송장번호, 배송업체ID 없을 경우
            $('#traceDeliveryCop_'+invoiceNo+'_'+ordiSeq).text("-");
            $('#traceDeliveryCop_'+invoiceNo+'_'+ordiSeq).prop('title',"운송장번호 또는 택배사ID를 확인할 수 없습니다.");					
        }				
    });
}

2. Controller 부분 그냥 서비스 호출만 하는 걸로...

	/**
	 * @param invoiceNo
	 * @param dcApiId
	 * @return
	 * @throws MalformedURLException
	 * @throws ParseException
	 */
	@RequestMapping(value="/order/ajax/getInvoiceStatus.json", method=RequestMethod.GET)
	@ResponseBody
	public Object getInvoiceStatusAPI(
			@RequestParam String invoiceNo
			,@RequestParam String dcApiId
			)  {
		Map<String, Object> result = new HashMap<>();
		result = b2bService.getInvoiceStatusApiService(invoiceNo, dcApiId);
		return result;
	}

3. Srvice 부분 

	/**
	 * @param invoiceNo
	 * @param dcApiId
	 * @return
	 * ************************************
	 * 이 코드는 클라이언트가 지정된 URL로 GET 요청을 수행하고 송장 번호와 API 식별자를 
	 * 쿼리 매개변수로 전달하여 송장의 상태를 조회할 수 있는 웹 서비스의 일부로 설계되었습니다. 
	 * API 응답이 처리되고 상태 정보와 함께 JSON 객체로 반환됩니다.
	 */
	public Map<String, Object> getInvoiceStatusApiService(String invoiceNo, String dcApiId) {
	    Map<String, Object> result = new HashMap<>();
	    String apiUrl = "https://apis.tracker.delivery/carriers/" + dcApiId + "/tracks/" + invoiceNo;
	    
	    try {
	        URI url = new URI(apiUrl);
	        HttpURLConnection conn = (HttpURLConnection) url.toURL().openConnection();
	        conn.setDoOutput(true);
	        conn.setRequestProperty("Content-Type", "application/x-www-form-urlencoded");

	        try (InputStream is = conn.getInputStream(); Scanner scan = new Scanner(is)) {
	            StringBuilder response = new StringBuilder();
	            while (scan.hasNext()) {
	                response.append(scan.nextLine());
	            }

	            JSONObject jsonResponse = (JSONObject) new JSONParser().parse(response.toString());
	            JSONObject state = (JSONObject) jsonResponse.get("state");
	            String statusText = state.get("text").toString();

	            result.put("code", 0);
	            result.put("message", statusText);
	            result.put("etc", response.toString());
	        } catch (ParseException e) {
	        	trackerHandleException(result, e);
	        }
	    } catch (URISyntaxException | IOException e) {
	    	trackerHandleException(result, e);
	    }

	    return result;
	}
	/**
	 * @param result
	 * @param e
	 * ********************************
	 * getInvoiceStatusApiService()의 예외를 처리하고 에러 메시지를 로깅하며, 결과 맵에 오류 코드와 메시지를 설정합니다.
	 */
	private void trackerHandleException(Map<String, Object> result, Exception e) {
	    String errorMessage = "[배송추적_API_ERROR]: " + e.getMessage();
	    logger.error(errorMessage);
	    result.put("code", 1);
	    result.put("message", errorMessage);
	}

일부 오류가 있는 듯하다 특정 택배사의 경우 배송완료된 건이 배송 출발로 나오는 경우가 있는 듯하다.

기타 다른 오류 관련 내용은 해당 API사이트 https://tracker.delivery/guide/의 github의 내용을 참고...

https://github.com/shlee322/delivery-tracker/issues

GitHub - shlee322/delivery-tracker: 🚚 Delivery and Shipping Tracking Service