우체국택배 조회 API
우체국택배는 우정사업본부가 운영하는 국내 대표 공공 택배 서비스입니다. 전국 우체국 네트워크를 기반으로 도서 산간 지역을 포함한 전국 어디서나 신뢰할 수 있는 배송을 제공합니다. DeliveryAPI를 통해 우체국택배 배송 상태를 단일 API로 조회할 수 있습니다.
택배사 소개
우체국택배는 우정사업본부(Korea Post)가 운영하는 택배 서비스로, 대한민국 전역에 분포한 우체국 네트워크를 활용합니다. 민간 택배사가 배송을 거부하거나 추가 요금을 부과하는 도서 지역, 산간 지역에도 균일한 요금으로 배송이 가능한 것이 가장 큰 특징입니다.
우체국택배 기본 정보
- 운영 기관: 우정사업본부 (Korea Post)
- 고객센터: 1588-1300
- 공식 조회: 우체국 배송조회
- 택배사 코드 (API):
post
송장번호 형식
우체국택배 송장번호는 숫자 13자리로 구성됩니다. API 요청 시 하이픈이나 공백 없이 숫자만 입력해야 합니다.
| 항목 | 내용 |
|---|---|
| 자릿수 | 13자리 |
| 구성 | 숫자만 사용 |
| 예시 | 1234567890123 |
| 입력 형식 | 하이픈(-), 공백 없이 숫자만 입력 |
API 연동 예시
DeliveryAPI에서 우체국택배를 조회할 때는 courierCode를 post로 지정합니다.
하나의 요청으로 여러 택배사의 송장을 동시에 조회할 수도 있습니다.
curl -X POST https://api.deliveryapi.co.kr/v1/tracking/trace \
-H "Authorization: Bearer {API_KEY}:{SECRET_KEY}" \
-H "Content-Type: application/json" \
-d '{
"items": [
{
"courierCode": "post",
"trackingNumber": "1234567890123"
}
]
}'API 엔드포인트
URL: POST https://api.deliveryapi.co.kr/v1/tracking/trace
인증: Authorization: Bearer {API_KEY}:{SECRET_KEY}
택배사 코드: post
배송 상태 코드 매핑
API 응답의 deliveryStatus 필드는 DeliveryAPI 표준 상태 코드를 사용합니다.
배송 이력(progresses)의 status 필드에서 우체국택배 원본 상태 텍스트를, statusCode 필드에서 정규화된 상태 코드를 확인할 수 있습니다.
| DeliveryAPI 상태 코드 | 설명 | 우체국택배 원본 상태 예시 |
|---|---|---|
PENDING | 접수 대기 | 접수 |
IN_TRANSIT | 배송 중 | 집배 발송, 도착, 운송 중 |
OUT_FOR_DELIVERY | 배달 출발 | 배달 출발 |
DELIVERED | 배달 완료 | 배달 완료 |
FAILED | 배달 실패 | 배달 불가, 수취인 부재 |
RETURNED | 반송 | 반송 |
자주 묻는 질문 (FAQ)
우체국택배 송장번호를 입력했는데 조회가 안 됩니다
우체국택배는 접수 후 시스템에 등록되기까지 수 시간이 걸릴 수 있습니다. 특히 방문 접수의 경우 당일 저녁 이후 조회되는 경우가 많습니다. 13자리 숫자를 정확히 입력했는지 확인한 후 잠시 후 다시 시도해보세요.
EMS 국제 우편도 같은 API로 조회할 수 있나요?
현재 DeliveryAPI는 국내 우체국택배 조회를 지원합니다. EMS(국제특급우편) 조회는 별도로 문의해 주세요.
도서 산간 지역 배송도 실시간으로 추적되나요?
도서 산간 지역의 경우 배송 단계별 업데이트 간격이 육지보다 길 수 있습니다. 선박 이동 구간이 포함되면 해당 구간의 상태 업데이트가 지연될 수 있습니다.
API 요청 시 우체국택배 코드를 잘못 입력했어요
우체국택배의 택배사 코드는 post입니다.
대소문자를 구분하므로 반드시 소문자로 입력하세요.
지원 택배사 전체 목록은 API 문서에서 확인할 수 있습니다.