Stats
Actions
Tags
From k-skill
Track CJ대한통운 and 우체국 parcels by invoice number using official endpoints. Workflow structured around carrier adapter for adding more couriers.
How this skill is triggered — by the user, by Claude, or both
Slash command
/k-skill:delivery-trackingThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
CJ대한통운과 우체국 공식 조회 표면을 사용해 송장 번호로 현재 배송 상태를 조회한다.
CJ대한통운과 우체국 공식 조회 표면을 사용해 송장 번호로 현재 배송 상태를 조회한다.
python3curljqcj 또는 epost이 스킬은 택배사별 로직을 carrier adapter 단위로 나눈다.
새 택배사를 붙일 때는 아래 필드를 먼저 정한다.
carrier id: 예) cj, epostvalidator: 송장번호 자리수/패턴entrypoint: 공식 조회 진입 URLtransport: JSON API / HTML form / CLI 중 무엇을 쓰는지parser: 어떤 필드나 테이블에서 상태를 뽑는지status map: 각 택배사의 원본 상태 코드를 공통 상태로 어떻게 줄일지retry policy: timeout/retry 규칙현재 어댑터는 아래 둘이다.
| carrier adapter | official entry | transport | validator | parser focus |
|---|---|---|---|---|
cj | https://www.cjlogistics.com/ko/tool/parcel/tracking | page GET + tracking-detail POST JSON | 10자리 또는 12자리 숫자 | parcelDetailResultMap.resultList |
epost | https://service.epost.go.kr/trace.RetrieveRegiPrclDeliv.postal?sid1= | form POST HTML | 13자리 숫자 | 기본정보 table_col + 상세 processTable |
cj / epost 둘 중 하나로 정규화한다.- 를 제거한다.공식 진입 페이지에서 _csrf 를 읽고, 그 값을 tracking-detail POST에 같이 보낸다.
https://www.cjlogistics.com/ko/tool/parcel/trackinghttps://www.cjlogistics.com/ko/tool/parcel/tracking-detail_csrf, paramInvcNo기본 예시는 curl 로 _csrf 와 cookie를 유지하고, Python은 JSON 정리에만 쓴다.
tmp_body="$(mktemp)"
tmp_cookie="$(mktemp)"
tmp_json="$(mktemp)"
invoice="1234567890" # 공식 페이지 placeholder 성격의 smoke-test 값
curl -sS -L -c "$tmp_cookie" \
"https://www.cjlogistics.com/ko/tool/parcel/tracking" \
-o "$tmp_body"
csrf="$(python3 - <<'PY' "$tmp_body"
import re
import sys
text = open(sys.argv[1], encoding="utf-8", errors="ignore").read()
print(re.search(r'name="_csrf" value="([^"]+)"', text).group(1))
PY
)"
curl -sS -L -b "$tmp_cookie" \
-H "Content-Type: application/x-www-form-urlencoded; charset=UTF-8" \
--data-urlencode "_csrf=$csrf" \
--data-urlencode "paramInvcNo=$invoice" \
"https://www.cjlogistics.com/ko/tool/parcel/tracking-detail" \
-o "$tmp_json"
python3 - <<'PY' "$tmp_json"
import json
import sys
payload = json.load(open(sys.argv[1], encoding="utf-8"))
events = payload["parcelDetailResultMap"]["resultList"]
if not events:
raise SystemExit("조회 결과가 없습니다.")
status_map = {
"11": "상품인수",
"21": "상품이동중",
"41": "상품이동중",
"42": "배송지도착",
"44": "상품이동중",
"82": "배송출발",
"91": "배달완료",
}
latest = events[-1]
normalized_events = [
{
"timestamp": event.get("dTime"),
"location": event.get("regBranNm"),
"status_code": event.get("crgSt"),
"status": status_map.get(event.get("crgSt"), event.get("scanNm") or "알수없음"),
}
for event in events
]
print(json.dumps({
"carrier": "cj",
"invoice": payload["parcelDetailResultMap"]["paramInvcNo"],
"status_code": latest.get("crgSt"),
"status": status_map.get(latest.get("crgSt"), latest.get("scanNm") or "알수없음"),
"timestamp": latest.get("dTime"),
"location": latest.get("regBranNm"),
"event_count": len(events),
"recent_events": normalized_events[-min(3, len(normalized_events)):],
}, ensure_ascii=False, indent=2))
PY
rm -f "$tmp_body" "$tmp_cookie" "$tmp_json"
아래 값은 2026-03-27 기준 live smoke test(1234567890)에서 확인한 정규화 결과다.
{
"carrier": "cj",
"invoice": "1234567890",
"status_code": "91",
"status": "배달완료",
"timestamp": "2026-03-21 12:22:13",
"location": "경기광주오포",
"event_count": 3,
"recent_events": [
{
"timestamp": "2026-03-10 03:01:45",
"location": "청원HUB",
"status_code": "44",
"status": "상품이동중"
},
{
"timestamp": "2026-03-21 10:53:19",
"location": "경기광주오포",
"status_code": "82",
"status": "배송출발"
},
{
"timestamp": "2026-03-21 12:22:13",
"location": "경기광주오포",
"status_code": "91",
"status": "배달완료"
}
]
}
추가 smoke test 로는 000000000000 도 사용할 수 있다.
CJ 응답은 parcelResultMap.resultList 가 비어 있어도 parcelDetailResultMap.resultList 쪽에 이벤트가 들어올 수 있으므로, 상세 이벤트 배열을 우선 본다. published 예시는 공통 결과 스키마(carrier, invoice, status, timestamp, location, event_count, recent_events, 선택적 status_code)에 맞춰 비식별 필드만 남기고, 담당자 이름·연락처가 섞일 수 있는 crgNm 원문은 그대로 보여주지 않는다.
우체국은 공식 entry page가 다시 trace.RetrieveDomRigiTraceList.comm 으로 sid1 을 POST하는 구조다.
https://service.epost.go.kr/trace.RetrieveRegiPrclDeliv.postal?sid1=https://service.epost.go.kr/trace.RetrieveDomRigiTraceList.commsid1우체국은 로컬 Python HTTP client보다 curl --http1.1 --tls-max 1.2 경로가 더 안정적이므로 그 조합을 기본 예시로 쓴다.
tmp_html="$(mktemp)"
python3 - <<'PY' "$tmp_html"
import html
import json
import re
import subprocess
import sys
invoice = "1234567890123" # 공식 페이지 placeholder 성격의 smoke-test 값
output_path = sys.argv[1]
cmd = [
"curl",
"--http1.1",
"--tls-max",
"1.2",
"--silent",
"--show-error",
"--location",
"--retry",
"3",
"--retry-all-errors",
"--retry-delay",
"1",
"--max-time",
"30",
"-o",
output_path,
"-d",
f"sid1={invoice}",
"https://service.epost.go.kr/trace.RetrieveDomRigiTraceList.comm",
]
subprocess.run(cmd, check=True)
page = open(output_path, encoding="utf-8", errors="ignore").read()
summary = re.search(
r"<th scope=\"row\">(?P<tracking>[^<]+)</th>.*?"
r"<td>(?P<sender>.*?)</td>.*?"
r"<td>(?P<receiver>.*?)</td>.*?"
r"<td>(?P<delivered_to>.*?)</td>.*?"
r"<td>(?P<kind>.*?)</td>.*?"
r"<td>(?P<result>.*?)</td>",
page,
re.S,
)
if not summary:
raise SystemExit("기본정보 테이블을 찾지 못했습니다.")
def clean(raw: str) -> str:
text = re.sub(r"<[^>]+>", " ", raw)
return " ".join(html.unescape(text).split())
def clean_location(raw: str) -> str:
text = clean(raw)
return re.sub(r"\s*(TEL\s*:?\s*)?\d{2,4}[.\-]\d{3,4}[.\-]\d{4}", "", text).strip()
events = re.findall(
r"<tr>\s*<td>(\d{4}\.\d{2}\.\d{2})</td>\s*"
r"<td>(\d{2}:\d{2})</td>\s*"
r"<td>(.*?)</td>\s*"
r"<td>\s*<span class=\"evtnm\">(.*?)</span>(.*?)</td>\s*</tr>",
page,
re.S,
)
normalized_events = [
{
"timestamp": f"{day} {time_}",
"location": clean_location(location),
"status": clean(status),
}
for day, time_, location, status, _detail in events
]
latest_event = normalized_events[-1] if normalized_events else None
print(json.dumps({
"carrier": "epost",
"invoice": clean(summary.group("tracking")),
"status": clean(summary.group("result")),
"timestamp": latest_event["timestamp"] if latest_event else None,
"location": latest_event["location"] if latest_event else None,
"event_count": len(normalized_events),
"recent_events": normalized_events[-min(3, len(normalized_events)):],
}, ensure_ascii=False, indent=2))
PY
rm -f "$tmp_html"
아래 값은 2026-03-27 기준 live smoke test(1234567890123)에서 확인한 정규화 결과다.
{
"carrier": "epost",
"invoice": "1234567890123",
"status": "배달완료",
"timestamp": "2025.12.04 15:13",
"location": "제주우편집중국",
"event_count": 2,
"recent_events": [
{
"timestamp": "2025.12.04 15:13",
"location": "제주우편집중국",
"status": "배달준비"
},
{
"timestamp": "2025.12.04 15:13",
"location": "제주우편집중국",
"status": "배달완료"
}
]
}
우체국 기본정보 테이블은 등기번호, 보내는 분/접수일자, 받는 분, 수령인/배달일자, 취급구분, 배달결과 순서를 사용하고, 상세 이벤트는 processTable 아래 날짜 / 시간 / 발생국 / 처리현황 행을 읽으면 된다. published 예시는 CJ와 같은 공통 결과 스키마(carrier, invoice, status, timestamp, location, event_count, recent_events)에 맞춰 배송 상태에 필요한 값만 남기고, 이벤트 location에 섞일 수 있는 TEL 번호 조각도 제거한 뒤 수령인/상세 메모 원문은 그대로 노출하지 않는다.
응답 원문을 그대로 붙이지 말고 아래 공통 결과 스키마로 요약한다.
carrier: 택배사 식별자 (cj 또는 epost)invoice: 정규화된 송장번호status: 현재 배송 상태timestamp: 마지막 이벤트 시각location: 마지막 이벤트 위치event_count: 전체 이벤트 수recent_events: 최근 최대 3개 이벤트 목록status_code: 필요할 때만 남기는 원본 상태 코드 (현재는 CJ 예시에서만 사용)_csrf 재취득 후 한 번 더 시도한다.curl --retry 3 --retry-all-errors --retry-delay 1 을 유지한다._csrf 추출 실패 또는 tracking-detail 응답 스키마 변경sid1 이 13자리가 아님curl 없이 다른 client로 붙다가 timeout/reset 발생npx claudepluginhub nomadamas/k-skill --plugin k-skillSearches Gmail for dispatch emails to extract tracking numbers and generates direct tracking links for Australian couriers like AusPost, StarTrack, Sendle, Toll and international ones like DHL, FedEx, UPS.
Queries NZ Post public APIs for parcel tracking, address/postcode lookup, and PostShop/parcel-collect/postbox location search. No authentication required.
Handles freight exceptions like shipment delays, damages, losses, and carrier disputes with escalation protocols, claims procedures, and resolution workflows. Useful for shipping issues, delivery problems, or logistics claims.