택배사 가이드

천일택배 조회 API

천일택배는 천일정기화물자동차(주)가 화물 노선망 위에서 운영하는 택배 서비스입니다. 배송조회 API에서는 courier code chunil을 쓰며, chunilps로 보내도 같은 택배사로 처리됩니다.

천일택배 소개

천일택배는 오랫동안 기업 간 화물 운송을 해 온 천일정기화물자동차(주)의 택배 브랜드입니다. 전국 영업소에서 물건을 받아 권역별 터미널로 모으고, 다시 도착지 영업소로 내려 보내는 노선 화물 구조를 그대로 쓰기 때문에, 이력에 "터미널 하차·출발"처럼 화물 용어가 그대로 나옵니다.

안내와 영업소 검색은 천일택배 홈페이지에 있고, 운송장 조회 화면만 chunil.co.kr에 따로 있습니다. 홈페이지의 조회창도 결국 이 주소를 새 창으로 열어 줍니다.

기본 정보

택배사명	천일택배
운영사	천일정기화물자동차(주)
API courier code	`chunil` (별칭: `chunilps`)
고객센터	1877-6606 (택배) / 1800-0977 (특송)
조회 화면	chunil.co.kr 운송장 조회
지원 범위	조회(tracking) 전용 — 계정 기반 등록·출력은 지원하지 않습니다

운송장번호 형식

천일택배 운송장번호는 숫자만 6~16자리입니다. 하이픈이나 공백은 요청 전에 제거해 주세요.

상한 16자리는 천일이 조회창에서 실제로 막는 값입니다. 조회 화면의 입력칸이 maxlength="16"이고, 홈페이지 조회창과 결과 화면 모두 16자리를 넘기면 "16자리까지만 입력하세요"라고 되돌립니다. 하한은 천일이 따로 막지 않아서, 저희 쪽 공통 규칙(6자리 이상)을 그대로 적용합니다. 실제로 쓰이는 번호는 11자리가 많지만 11자리만 받도록 좁히지는 않았습니다 — 조회창이 16자리까지 받는 이상, 길이로 미리 잘라내면 멀쩡한 운송장이 거부될 수 있기 때문입니다.

운송장번호 예시

실측 샘플: 12643277012 — 11자리입니다.

API 연동 예시

조회는 단일 엔드포인트 호출로 끝납니다. {API_KEY}와 {SECRET_KEY}에는 발급받은 키 쌍을 넣으세요.

curl -X POST https://api.deliveryapi.co.kr/v1/tracking/trace \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {API_KEY}:{SECRET_KEY}" \
  -d '{
    "items": [
      {
        "courierCode": "chunil",
        "trackingNumber": "12643277012"
      }
    ]
  }'

items는 배열이므로 천일택배 운송장 여러 건을 한 번에, 또는 다른 택배사 송장과 함께 묶어 보낼 수 있습니다. 응답 필드 정의와 오류 코드는 API 문서를 참고하세요.

배송 경로와 단계

천일택배의 이력은 출발 영업소에서 시작해 두 종류의 터미널을 거친 뒤 도착 영업소로 내려오는 흐름으로 쌓입니다. 각 이력에는 처리 영업소명과 그 영업소 전화번호가 함께 담겨 있어, 위치를 확인하거나 문의처를 안내할 때 바로 쓸 수 있습니다.

순서	이력 문구	의미
1	접수	출발 영업소에서 운송장이 발행되고 물건이 맡겨진 시점
2	발송	출발 영업소가 물건을 실어 터미널로 보냄
3	발송터미널하차	출발 권역 터미널에 도착해 분류 작업에 들어감
4	발송터미널출발	분류를 마치고 도착 권역으로 간선 이동 시작
5	도착터미널하차	도착 권역 터미널·거점에 내려짐
6	영업소도착	배송을 맡을 도착 영업소까지 들어옴
7	배송완료	수취인에게 전달되어 배송이 종료됨

이력의 날짜에는 시각이 없습니다

천일택배 운송경로는 날짜(YYYY-MM-DD)만 공개하고 시·분은 주지 않습니다. 그래서 같은 날 여러 이력이 찍히는 일이 흔합니다(실측 건도 7단계 중 4건이 같은 날짜였습니다). 저희는 천일이 내려주는 순서를 그대로 뒤집어 최신순으로 돌려드리므로, 날짜만 보고 다시 정렬하면 같은 날 이력의 순서가 오히려 뒤섞입니다. progresses 배열의 순서를 그대로 쓰세요.

배송 상태 코드 매핑

위 문구들은 API에서 아래와 같이 통합 상태값으로 정규화되어 나갑니다. 택배사 원문 대신 이 상태값을 기준으로 분기하면 다른 택배사와 같은 코드로 처리할 수 있습니다.

천일택배 표기	통합 상태	설명
접수	`REGISTERED`	운송장이 등록되었고 아직 운송이 시작되지 않았습니다.
발송	`PICKED_UP`	출발 영업소가 물건을 인수해 실어 보냈습니다.
발송터미널하차 · 발송터미널출발	`IN_TRANSIT`	출발 권역 터미널에서 분류·간선 이동 중입니다.
도착터미널하차	`IN_TRANSIT`	도착 권역 터미널·거점까지 이동했습니다.
영업소도착	`IN_TRANSIT`	도착 영업소에 입고됐으나 아직 배송 출발 전입니다.
배송출발	`OUT_FOR_DELIVERY`	배송 기사가 수취인에게 향하고 있습니다.
배송완료	`DELIVERED`	수취인에게 물건이 전달되었습니다.

"발송터미널출발"을 배송 출발로 오해하지 마세요. 이 문구의 "출발"은 기사가 수취인에게 가는 것이 아니라 터미널에서 다음 권역으로 간선 이동을 시작한다는 뜻이라, 통합 상태는 IN_TRANSIT입니다. 수취인에게 향하는 단계는 OUT_FOR_DELIVERY로 따로 구분됩니다.

자주 묻는 질문 (FAQ)

천일택배의 courier code는 무엇인가요?

표준값은 chunil이며, 요청 본문에 "courierCode": "chunil"로 넣으면 됩니다. 안내 도메인을 딴 chunilps도 별칭으로 등록되어 있어 동일한 결과를 받습니다.

운송장번호 자릿수를 검증해도 되나요?

숫자만 6~16자리라는 범위 검사까지는 안전합니다. 다만 실측 샘플이 11자리라고 해서 11자리만 유효하다고 가정하지는 마세요. 천일 조회창 자체가 16자리까지 받기 때문에, 길이를 좁게 잡으면 멀쩡한 운송장이 걸러질 수 있습니다.

배송완료 시각은 왜 날짜만 나오나요?

천일택배가 조회 화면에서 날짜까지만 공개하기 때문입니다. dateDelivered와 각 이력의 dateTime은 YYYY-MM-DD 형식이고 시·분은 비어 있습니다. 시각까지 필요한 업무라면 이력의 순서(배열 순)를 기준으로 삼으시는 편이 안전합니다.

수취인 주소도 받을 수 있나요?

받을 수 없습니다. 천일택배 조회 화면은 수취인 주소를 공개하지 않고 도착영업소만 알려줍니다. API 응답에서는 이 값을 arrivalBranch로 내려드리며, 보내는 사람·받는 사람 이름은 천일이 마스킹한 값 (예: 이**) 그대로입니다.

운송장 발행이나 출력도 API로 되나요?

되지 않습니다. 천일택배는 조회(tracking)만 지원합니다. 접수는 천일택배 영업소를 통해 이루어지고, 발행된 운송장번호를 받아 조회하는 용도로 API를 쓰게 됩니다.

천일택배 API 연동 시작하기

화물 노선망 택배와 일반 택배사 송장을 하나의 응답 형식으로 받아보세요

무료로 시작하기 →