스마트택배 API로 배송 정보 조회 기능 만들기
목차 펼치기
머리말
머리말
스마트택배에서 택배사 코드와 운송장번 호를 이용하여 상세 배송 정보를 조회할 수 있는 API를 제공해주고 있다.
크게 조회, 추적 API로 나뉘는데
조회 API는 요청이 발생 했을 때 실시간 배송상태를 제공해주는 API이고,
추적 API는 별도의 요청이 없어도 주기적으로 배송상태를 추적하여 제공해주는 API로 추적 API를 이용할 경우에는 별도의 연간 계약과 후불제가 도입된다.
“일정 시간마다 조회API 호출하여 배송 상태 값을 저장하는 기능을 추가 개발하신다면그것이 바로 추적API와 동일한 기능입니다.” - 스마트 택배
스마트택배 API 요금제. 출처 : 스마트택배 API 공식 사이트
API 연동은
공식 사이트에서 회원가입 및 로그인 후 Key를 발급받은 다음 RESTful 형태로 호출하면 된다.
공식 사이트에서 연동 택배사 코드 및 swagger를 통한 API 명세도 제공해주고 있다.
배송 조회 API의 응답값을 기준으로 interface를 설계하면 다음과 같다.
파라미터별 데이터 의미는 공식 문서의 설명을 참고하자.
Invoice: 운송장번호 정보
TrackingInfoDetail: 배송 단계별 상세 정보
TrackingInfo: 배송 정보
1export interface Invoice {
2 id: number;
3 invoice_number: string;
4 logistics_company_code: string;
5 logistics_company_name: string;
6 invoice_date: string;
7 created_at: string;
8}
9
10export interface TrackingInfoDetail {
11 code?: string;
12 kind: string;
13 level: number;
14 manName: string;
15 manPic: string;
16 remark?: string;
17 telno: string;
18 telno2: string;
19 time: number | Date;
20 timeString: string;
21 where: string;
22}
23
24export interface TrackingInfo {
25 adUrl: string;
26 complete: boolean;
27 estimate: string;
28 firstDetail: TrackingInfoDetail;
29 lastStateDetail: TrackingInfoDetail;
30 lastDetail: TrackingInfoDetail;
31 invoiceNo: string;
32 itemName: string;
33 itemImage: string;
34 receiverAddr: string;
35 receiverName: string;
36 recipient: string;
37 result: string;
38 level: number;
39 senderName: string;
40 orderNumber?: number;
41 productInfo?: string;
42 zipCode?: string;
43 completeYN?: string;
44 trackingDetails: TrackingInfoDetail[];
45 status?: boolean;
46 msg?: string;
47}배송 조회 API 응답값 interface
그런데… 이 데이터를 어떻게 사용해서 케이스를 판별하고 사용할 지에 대한 가이드가 나와있지 않고, 리턴되는 응답값의 예시가 잘 마련되어 있지 않았다. 하여 처음에는
trackingDetails와
compelte만 사용해서 보여주면 되는 건가 하는 가벼운 마음으로 로직을 구성하였지만, 테스트를 진행할 수록 나오는 엣지 케이스에 대응하기 위해 수정을 반복할 수밖에 없었다.
이 응답값을 어떻게 사용하여 보여주면 모든 케이스에 대응이 될 지를 찾아내야 한다 !!! 🧐
…
…
…
로직을 수정하여도 계속 발견되는 추가 케이스에 따라 수정을 반복한 결과, 다음과 같이 판단 기준이 정리되었다.
운송장번호가 등록이 되었는데 아직 택배사가 상품을 인수받지 못해 추적할 배송 정보가 없는 케이스.
택배사에서 배송 과정을 진행 중인 케이스.
배송이 완료된 케이스
배송이 완료되고 시일이 흘러 운송장 번호에서 상품 정보가 사라진 케이스.
상품 정보만 사라지고 배송에 대한 정보는 그대로 남아있는데, 운송장 번호가 초기화되기 전에 상품정보만 먼저 사라지는 것으로 추정된다.
운송장 번호에서 상품 정보 및 배송 정보가 모두 사라진 케이스.
운송장 번호가 재사용되기 위해 초기화된 케이스로 보인다.
위 케이스들을 토대로 로직을 처음부터 다시 수정였는데 바로 배송 조회 결과의
level,
trackingDetails,
complete세 데이터와 운송장번호가 등록된 시간까지 총 4개의 데이터로 판단하는 로직이다.
level: 배송상태 별 number 코드 값.
1 : 배송준비중
2 : 집 화완료
3 : 배송중
4 : 지점 도착
5 : 배송출발
6 : 배송 완료
trackingDetails: 배송 단계별 상세정보가 담긴 배열
complete: 배송 완료 여부의 boolean
created_at: 운송장 번호가 등록된 시간
개발자가 이해하기 쉬운 if-else 문으로 알고리즘을 정리해보면 다음과 같다.
1if (today - created_at > 60일 && level === 1) {
2 // 60일이 지난 상태이기 때문에 배송이 완료된 것으로 간주.
3 // 혹시 상품을 받지 못했다면 판매사에 문의하라는 사용자 안내 문구도 추가되면 좋다.
4} else {
5 if (trackingDetails.length > 0) {
6 // 배송 단계별 정보 노출
7 // level, where, remark, manName, telno 등등
8 } else{
9 // 배송 단계별 정보가 없기 때문에 level값을 기준으로 텍스트만 노출.
10 if (level === 1) {
11 // 판매업체에서 상품 발송을 준비중으로,
12 // 송장번호가 등록되었으나 아직 택배사가 상품을 인수받지 못해 추적할 배송 정보가 없는 경우.
13 } else if (level <= 5) {
14 // 배송 중이지만 배송 추적 정보가 없는 경우.
15 } else {
16 // 배송이 완료된 경우. (level 6)
17 }
18 }
19}배송정보 판별 로직.
추가로 개발하면서 느낀 점들을정 리하고 글을 마치려한다.
동일 운송장번호로 1일 최대 20번까지만 조회를 해주기 때문에 개발 및 배포 환경에서는 캐싱을 사용해주면 도움이 될 수 있다.
각 케이스별에 해당하는 운송장번호로 테스트하기 어렵기 때문에 각 케이스에 해당하는 테스트 데이터 셋을 만들어서 개발 단계에서 사용했다.
테스트 데이터 셋
테스트 데이터 셋
배송 완료 코드 보기
배송 완료 코드 보기
배송 중 코드 보기
배송 중 코드 보기
배송 준비 중 코드 보기
배송 준비 중 코드 보기
운송장 정보 초기화 코드 보기
운송장 정보 초기화 코드 보기