합동택배 조회 API

합동택배 소개

합동택배(합동익스프레스)는 전국 지방 권역의 소형 화물과 농산물 배송에 강점을 가진 택배사입니다. 대형 택배사가 커버하기 어려운 농촌 및 도서 산간 지역까지 배송 네트워크를 운영합니다.

송장번호 형식

합동택배 송장번호는 숫자 10~15자리이며, 주로 13자리로 발행됩니다. 하이픈(-)이나 공백 없이 숫자만 입력해야 합니다.

API 연동 예시

아래 curl 예시를 참고해 합동택배 배송조회를 연동하세요. API_KEY와 SECRET_KEY는 대시보드에서 발급받을 수 있습니다.

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": "hapdong",
        "trackingNumber": "1234567890123"
      }
    ]
  }'

배송 상태 코드 매핑

합동택배 원본 상태 코드와 API 응답의 정규화된 statusCode 매핑입니다. status 필드에는 택배사 원본 텍스트가, statusCode에는 정규화된 코드가 반환됩니다.

상태 코드	상태명	설명
0002	발송	발송인이 택배를 접수하여 집하 완료된 상태
0003	이동중	집하지에서 허브 또는 경유 터미널로 이동 중인 상태
0004	노선상차	배송 노선 차량에 상차 완료된 상태
0005	간선하차	간선 차량에서 하차하여 배송 터미널에 도착한 상태
0006	도착	배송 담당 지점에 도착 완료된 상태
0008	배송출발	배송 기사가 수령인에게 배달을 출발한 상태
0007	인수확인 (배달완료)	수령인이 택배를 수령하여 배달이 완료된 상태

자주 묻는 질문 (FAQ)

합동택배 송장번호가 조회되지 않아요

택배 접수 후 시스템 등록까지 수 시간이 소요될 수 있습니다. 접수 당일 오후 또는 익일에 다시 조회해보세요. 고객센터(1588-0002)로 문의하면 상세 확인이 가능합니다.

courierCode를 잘못 지정하면 어떻게 되나요?

잘못된 courierCode를 입력하면 API가 404 또는 조회 실패 응답을 반환합니다. 합동택배는 반드시 "hapdong"으로 지정해야 합니다.

농산물 배송 특성상 지연이 발생할 수 있나요?

합동택배는 농산물 및 신선식품 배송 특성상 기상 조건이나 수확 시기에 따라 배송 일정이 변동될 수 있습니다. 상태 코드 0003(이동중) 또는 0004(노선상차) 단계에서 일시적으로 조회가 지연될 수 있습니다.

여러 송장번호를 한 번에 조회할 수 있나요?

네. items 배열에 여러 객체를 추가하면 단일 요청으로 다수의 송장을 조회할 수 있습니다. 자세한 배치 조회 방법은 API 문서를 참고하세요.