GET /ai/progress-table/application/{applicationId}/delivery
배송 정보 조회
배송 정보 조회
신청 건의 배송 정보를 조회합니다. 자동 배송조회 폴링으로 적재된 trackingDetail(택배사 전체 추적 내용 JSON)을 함께 내려주므로, 배송 상세보기 화면에서 단계별 타임라인을 렌더링할 수 있습니다.
HTTP 요청
GET /ai/progress-table/application/{applicationId}/deliveryPath Parameters
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
applicationId | long | 예 | 신청 ID |
응답
| 필드 | 타입 | 설명 |
|---|---|---|
deliveryStatus | string | beforeDelivery / shipping / delivered / wrongTrackingNumber / invalidTracking |
trackingNumber | string | 운송장 번호 |
courierCode | string | 택배사 코드(kr.xxx) 또는 기타 한글명/OTHER |
trackingDetail | string(JSON) | 배송조회 전체 응답. 폴링 시마다 최신 전체로 갱신. 미조회 시 null |
shippedAt | string | 배송 시작(집화) 시각. 추적 전/불가 시 null |
deliveredAt | string | 배송 완료 시각. 완료 전 null |
trackingDetail 은 events.edges[].node 에 단계별 time / status{code,name} / location{name} / contact{name,phoneNumber} / description 을 담은 JSON 문자열입니다(택배사 원본). contact 는 배송기사 정보로 단계에 따라 null 일 수 있습니다. 프론트는 이 전체 타임라인 중 표시할 단계를 선택해 렌더링하면 됩니다(아래 디코드 예시 참고).
trackingDetail 예시는 임시(추정)값입니다 — 실측 후 교체 필요.
아래 JSON 의 trackingDetail 문자열은 GraphQL 응답 구조를 보고 유추한 형태라, 실제 적재되는 정확한 형식(필드 순서·null 처리·events 전체 구조 등)과 다를 수 있습니다. test 배포 후 폴링이 1회 돈 뒤 실제 적재값을 확인해 교체하세요.
실측 확인 절차
- test 서버 배포 + DDL 적용 후, SHIPPING 상태인 실제 송장이 폴링되길 대기(또는 cron 단축)
- DB 에서 실제 적재값 확인:
SELECT tracking_detail FROM TB_APPLICATION_DELIVERY WHERE tracking_detail IS NOT NULL ORDER BY updated_at DESC LIMIT 1; - 그 실제 JSON 으로 아래 예시 교체
{
"status": 200,
"code": null,
"message": "조회 성공",
"data": {
"id": 199,
"applicationId": 123,
"deliveryStatus": "delivered",
"trackingNumber": "589498233426",
"courierCode": "kr.cjlogistics",
"trackingDetail": "(실측 전 임시 예시) {\"lastEvent\":{\"time\":\"2026-05-27T13:20:18.000+09:00\",\"status\":{\"code\":\"DELIVERED\",\"name\":\"배송완료\"},\"description\":\"고객님의 상품이 배송완료 되었습니다.\"},\"events\":{\"edges\":[ ... ]}}",
"shippedAt": "2026-05-26T18:02:53",
"deliveredAt": "2026-05-27T13:56:22",
"createdAt": "2026-05-26T13:53:13",
"updatedAt": "2026-05-27T13:25:00"
}
}trackingDetail 디코드 예시 (CJ대한통운 실제 구조)
trackingDetail 문자열을 파싱하면 아래 구조입니다(배송기사 실명·전화는 예시에서 마스킹). events.edges 는 집화→간선→배송출발→배송완료 순의 전체 타임라인이고, lastEvent 는 그중 마지막 이벤트입니다.
{
"lastEvent": {
"time": "2026-05-27T13:56:22.000+09:00",
"status": { "code": "DELIVERED", "name": "배송완료" },
"location": { "name": "광주서A상무" },
"contact": { "name": "홍길동", "phoneNumber": "+8210XXXXXXXX" },
"description": "고객님의 상품이 배송완료 되었습니다.(담당사원:홍길동 010-XXXX-XXXX)"
},
"events": {
"edges": [
{ "node": { "time": "2026-05-26T18:02:53.000+09:00", "status": { "code": "AT_PICKUP", "name": "집화처리" }, "location": { "name": "경기평촌중앙" }, "contact": null, "description": "보내시는 고객님으로부터 상품을 인수받았습니다" } },
{ "node": { "time": "2026-05-27T00:15:08.000+09:00", "status": { "code": "IN_TRANSIT", "name": "간선상차" }, "location": { "name": "이천MPHub" }, "contact": null, "description": "배송지역으로 상품이 이동중입니다." } },
{ "node": { "time": "2026-05-27T08:59:05.000+09:00", "status": { "code": "IN_TRANSIT", "name": "간선하차" }, "location": { "name": "광주서ASub" }, "contact": { "name": "홍길동", "phoneNumber": "+8210XXXXXXXX" }, "description": "고객님의 상품이 배송지에 도착하였습니다.(배송예정:홍길동 010-XXXX-XXXX)" } },
{ "node": { "time": "2026-05-27T09:04:17.000+09:00", "status": { "code": "OUT_FOR_DELIVERY", "name": "배송출발" }, "location": { "name": "광주서A상무" }, "contact": { "name": "홍길동", "phoneNumber": "+8210XXXXXXXX" }, "description": "고객님의 상품을 배송할 예정입니다.(14~16시)(배송담당:홍길동 010-XXXX-XXXX)" } },
{ "node": { "time": "2026-05-27T13:56:22.000+09:00", "status": { "code": "DELIVERED", "name": "배송완료" }, "location": { "name": "광주서A상무" }, "contact": { "name": "홍길동", "phoneNumber": "+8210XXXXXXXX" }, "description": "고객님의 상품이 배송완료 되었습니다.(담당사원:홍길동 010-XXXX-XXXX)" } }
]
}
}단계 status.code 는 AT_PICKUP(집화) · IN_TRANSIT(간선상·하차) · OUT_FOR_DELIVERY(배송출발) · DELIVERED(배송완료) 등이며, 택배사 표준 코드입니다. name 은 택배사 원문 한글 표기라 같은 코드라도 표현이 다를 수 있습니다.
배송 상태(deliveryStatus) 값
| 값 | 의미 |
|---|---|
beforeDelivery | 배송 전 |
shipping | 배송 중 (조회 안 됨 NOT_FOUND 도 유지하며 재시도) |
delivered | 배송 완료 |
wrongTrackingNumber | 잘못된 운송장 번호 (형식 오류 — 정정 재입력 필요) |
invalidTracking | 배송조회 미지원 (OTHER/추적 불가 택배사) |