delivery-tracking
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseDelivery Tracking
快递查询
What this skill does
技能功能
CJ대한통운과 우체국 공식 조회 표면을 사용해 송장 번호로 현재 배송 상태를 조회한다.
- CJ대한통운: 공식 배송조회 페이지가 노출하는 JSON endpoint 사용
- 우체국: 공식 배송조회 페이지가 사용하는 HTML endpoint 사용
- 결과는 공통 포맷(택배사 / 송장번호 / 현재 상태 / 최근 이벤트들)으로 짧게 정리
使用CJ大韩通运和韩国邮政的官方查询接口,通过运单号查询当前配送状态。
- CJ大韩通运: 使用官方配送查询页面公开的JSON endpoint
- 韩国邮政: 使用官方配送查询页面的HTML endpoint
- 结果会统一整理为通用格式(快递公司 / 运单号 / 当前状态 / 最新物流事件)
When to use
适用场景
- "CJ대한통운 송장 조회해줘"
- "우체국 택배 지금 어디야"
- "이 송장번호 배송완료인지 확인해줘"
- "택배사별 조회 로직을 나중에 더 붙일 수 있게 정리해줘"
- "帮我查下CJ大韩通运的运单"
- "韩国邮政的快递现在到哪了"
- "帮我确认下这个运单是否已配送完成"
- "希望按后续可新增更多快递公司查询逻辑的规范来整理代码"
When not to use
不适用场景
- 주문번호만 있고 송장번호가 없는 경우
- 택배 예약/반품 접수까지 바로 해야 하는 경우
- 비공식 통합 배송조회 서비스로 우회하고 싶은 경우
- 只有订单号没有运单号的情况
- 需要直接进行快递预约/退货申请的情况
- 希望跳转到非官方的综合快递查询服务的情况
Prerequisites
前置要求
- 인터넷 연결
python3curl- 선택 사항:
jq
- 网络连接
python3curl- 可选:
jq
Inputs
输入参数
- 택배사 식별자: 또는
cjepost - 송장번호
- CJ대한통운: 숫자 10자리 또는 12자리
- 우체국: 숫자 13자리
- 快递公司标识符: 或
cjepost - 运单号
- CJ大韩通运: 10位或12位数字
- 韩国邮政: 13位数字
Carrier adapter rule
承运商适配器规则
이 스킬은 택배사별 로직을 carrier adapter 단위로 나눈다.
새 택배사를 붙일 때는 아래 필드를 먼저 정한다.
- : 예)
carrier id,cjepost - : 송장번호 자리수/패턴
validator - : 공식 조회 진입 URL
entrypoint - : JSON API / HTML form / CLI 중 무엇을 쓰는지
transport - : 어떤 필드나 테이블에서 상태를 뽑는지
parser - : 각 택배사의 원본 상태 코드를 공통 상태로 어떻게 줄일지
status map - : timeout/retry 규칙
retry policy
현재 어댑터는 아래 둘이다.
| carrier adapter | official entry | transport | validator | parser focus |
|---|---|---|---|---|
| | page GET + | 10자리 또는 12자리 숫자 | |
| | form POST HTML | 13자리 숫자 | 기본정보 |
本技能将不同快递公司的逻辑按 carrier adapter 单元拆分。
新增快递公司时,需先定义以下字段:
- : 示例)
carrier id,cjepost - : 运单号位数/格式校验规则
validator - : 官方查询入口URL
entrypoint - : 使用JSON API / HTML表单 / CLI中的哪一种
transport - : 从哪些字段或表格中提取状态信息
parser - : 如何将各快递公司的原生状态码映射为通用状态
status map - : 超时/重试规则
retry policy
当前已支持的适配器如下:
| carrier adapter | official entry | transport | validator | parser focus |
|---|---|---|---|---|
| | page GET + | 10位或12位数字 | |
| | form POST HTML | 13位数字 | 基础信息 |
Workflow
工作流
0. Normalize the input first
0. 首先对输入做标准化处理
- 택배사 이름을 /
cj둘 중 하나로 정규화한다.epost - 송장번호에서 공백과 를 제거한다.
- - 자리수 검증이 먼저 실패하면 조회를 보내지 않는다.
- 将快递公司名称标准化为 /
cj两个值之一epost - 移除运单号中的空格和 符号
- - 如果位数校验不通过,不会发起查询请求
1. CJ대한통운: official JSON flow
1. CJ大韩通运: 官方JSON查询流程
공식 진입 페이지에서 를 읽고, 그 값을 POST에 같이 보낸다.
_csrftracking-detail- 진입 페이지:
https://www.cjlogistics.com/ko/tool/parcel/tracking - 상세 endpoint:
https://www.cjlogistics.com/ko/tool/parcel/tracking-detail - 필수 필드: ,
_csrfparamInvcNo
기본 예시는 로 와 cookie를 유지하고, Python은 JSON 정리에만 쓴다.
curl_csrfbash
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"从官方入口页面读取 参数,将该值随 POST请求一同发送。
_csrftracking-detail- 入口页面:
https://www.cjlogistics.com/ko/tool/parcel/tracking - 详情查询endpoint:
https://www.cjlogistics.com/ko/tool/parcel/tracking-detail - 必填字段: ,
_csrfparamInvcNo
基础示例使用 维持 和cookie,Python仅用于JSON数据整理。
curl_csrfbash
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"CJ 공개 출력 예시
CJ公开输出示例
아래 값은 2026-03-27 기준 live smoke test()에서 확인한 정규화 결과다.
1234567890json
{
"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 로는 도 사용할 수 있다.
000000000000CJ 응답은 가 비어 있어도 쪽에 이벤트가 들어올 수 있으므로, 상세 이벤트 배열을 우선 본다. published 예시는 공통 결과 스키마(, , , , , , , 선택적 )에 맞춰 비식별 필드만 남기고, 담당자 이름·연락처가 섞일 수 있는 원문은 그대로 보여주지 않는다.
parcelResultMap.resultListparcelDetailResultMap.resultListcarrierinvoicestatustimestamplocationevent_countrecent_eventsstatus_codecrgNm以下是2026-03-27 基于线上冒烟测试用例()得到的标准化结果。
1234567890json
{
"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": "배달완료"
}
]
}额外的冒烟测试用例也可以使用 。
000000000000CJ的响应即便 为空, 一侧也可能包含物流事件,因此优先读取详情事件数组。公开示例符合通用结果schema(, , , , , , , 可选),仅保留非敏感字段,不会展示可能包含负责人姓名、联系方式的原文。
parcelResultMap.resultListparcelDetailResultMap.resultListcarrierinvoicestatustimestamplocationevent_countrecent_eventsstatus_codecrgNm2. 우체국: official HTML flow
2. 韩国邮政: 官方HTML查询流程
우체국은 공식 entry page가 다시 으로 을 POST하는 구조다.
trace.RetrieveDomRigiTraceList.commsid1- 진입 페이지:
https://service.epost.go.kr/trace.RetrieveRegiPrclDeliv.postal?sid1= - 실제 조회 endpoint:
https://service.epost.go.kr/trace.RetrieveDomRigiTraceList.comm - 필수 필드:
sid1
우체국은 로컬 Python HTTP client보다 경로가 더 안정적이므로 그 조합을 기본 예시로 쓴다.
curl --http1.1 --tls-max 1.2bash
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"韩国邮政官方入口页面会将 参数POST到 完成查询。
sid1trace.RetrieveDomRigiTraceList.comm- 入口页面:
https://service.epost.go.kr/trace.RetrieveRegiPrclDeliv.postal?sid1= - 实际查询endpoint:
https://service.epost.go.kr/trace.RetrieveDomRigiTraceList.comm - 必填字段:
sid1
相比本地Python HTTP客户端, 的访问路径更稳定,因此基础示例使用该组合。
curl --http1.1 --tls-max 1.2bash
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()에서 확인한 정규화 결과다.
1234567890123json
{
"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": "배달완료"
}
]
}우체국 기본정보 테이블은 , , , , , 순서를 사용하고, 상세 이벤트는 아래 행을 읽으면 된다. published 예시는 CJ와 같은 공통 결과 스키마(, , , , , , )에 맞춰 배송 상태에 필요한 값만 남기고, 이벤트 location에 섞일 수 있는 번호 조각도 제거한 뒤 수령인/상세 메모 원문은 그대로 노출하지 않는다.
등기번호보내는 분/접수일자받는 분수령인/배달일자취급구분배달결과processTable날짜 / 시간 / 발생국 / 처리현황carrierinvoicestatustimestamplocationevent_countrecent_eventsTEL以下是2026-03-27 基于线上冒烟测试用例()得到的标准化结果。
1234567890123json
{
"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": "배달완료"
}
]
}韩国邮政基础信息表按、、、、、的顺序读取,详情事件读取下的行即可。公开示例和CJ使用相同的通用结果schema(, , , , , , ),仅保留配送状态所需字段,移除事件位置中可能包含的号码片段,不会公开收件人/详情备注原文。
挂号编号寄件人/收件日期收件人签收人/配送日期处理类型配送结果processTable日期 / 时间 / 处理局 / 处理状态carrierinvoicestatustimestamplocationevent_countrecent_eventsTEL3. Normalize for humans
3. 结果人性化标准化
응답 원문을 그대로 붙이지 말고 아래 공통 결과 스키마로 요약한다.
不要直接返回响应原文,需按以下通用结果schema进行摘要整理。
공통 결과 스키마
通用结果Schema
- : 택배사 식별자 (
carrier또는cj)epost - : 정규화된 송장번호
invoice - : 현재 배송 상태
status - : 마지막 이벤트 시각
timestamp - : 마지막 이벤트 위치
location - : 전체 이벤트 수
event_count - : 최근 최대 3개 이벤트 목록
recent_events - : 필요할 때만 남기는 원본 상태 코드 (현재는 CJ 예시에서만 사용)
status_code
- : 快递公司标识符 (
carrier或cj)epost - : 标准化后的运单号
invoice - : 当前配送状态
status - : 最后一次物流事件时间
timestamp - : 最后一次物流事件位置
location - : 总物流事件数
event_count - : 最近最多3条物流事件列表
recent_events - : 仅必要时保留的原始状态码 (当前仅CJ示例使用)
status_code
4. Retry and fallback policy
4. 重试与降级策略
- 자리수 오류면 바로 멈추고 올바른 형식을 다시 받는다.
- CJ는 재취득 후 한 번 더 시도한다.
_csrf - 우체국은 을 유지한다.
curl --retry 3 --retry-all-errors --retry-delay 1 - 다른 택배사로 우회하지 않는다.
- 运单号位数错误直接终止,提示用户输入正确格式
- CJ查询失败会重新获取后重试一次
_csrf - 韩国邮政查询维持配置
curl --retry 3 --retry-all-errors --retry-delay 1 - 不会跳转使用其他快递公司的接口
Done when
完成判定条件
- 택배사와 송장번호가 올바르게 식별되어 있다
- 현재 상태와 최근 이벤트가 정리되어 있다
- 어느 official surface를 썼는지 설명할 수 있다
- 다른 택배사 확장 시 어떤 carrier adapter 필드를 추가해야 하는지 남아 있다
- 快递公司和运单号已正确识别
- 当前状态和最近物流事件已整理完成
- 可说明使用了哪些官方接口
- 已保留扩展其他快递公司时需要新增的carrier adapter字段说明
Failure modes
失败场景
- CJ: 추출 실패 또는
_csrf응답 스키마 변경tracking-detail - CJ: 송장번호 길이가 10자리 또는 12자리가 아님
- 우체국: 이 13자리가 아님
sid1 - 우체국: HTML 마크업 변경으로 테이블 추출 규칙이 깨짐
- 우체국: 없이 다른 client로 붙다가 timeout/reset 발생
curl
- CJ: 提取失败或
_csrf响应Schema变更tracking-detail - CJ: 运单号长度不是10位或12位
- 韩国邮政: 长度不是13位
sid1 - 韩国邮政: HTML标记变更导致表格提取规则失效
- 韩国邮政: 不使用改用其他客户端访问时出现超时/连接重置
curl
Notes
备注
- 조회형 스킬이다.
- 기본 표면은 공식 carrier endpoint만 사용한다.
- 다른 택배사 추가는 새 carrier adapter 1개를 같은 포맷으로 붙이는 방식으로 확장한다.
- 属于查询类技能
- 仅使用快递公司官方接口作为查询入口
- 新增其他快递公司仅需按相同格式添加1个新的carrier adapter即可完成扩展