주문이 몇 건 안 될 때는 택배사 화면에 직접 입력해도 되지만, 출고가 늘면 운송장 출력과 배송상태 복사가 금방 병목이 됩니다. 택배 API 연동방법을 찾는 이유는 주문정보를 한 번 입력하고 송장 발급부터 배송조회까지 이어 붙이기 위해서입니다.
이 글에서는 한진 기업고객 API의 공식 절차를 기준으로 인증키, DEV 테스트, 주문등록, 배송정보 수신, LIVE 전환을 차례대로 정리합니다. 계약이나 승인 없이 호출 주소만 복사해서 붙이는 방식이 아니라는 점부터 확인하면 시행착오를 줄일 수 있습니다.
택배 API 연동방법은 기업계약과 계정 승인 뒤 DEV 환경에서 주문·배송정보를 시험하고 통합테스트를 거쳐 LIVE로 전환하는 7단계입니다.
공식 흐름은 회원가입, 계정생성 메일 확인, 한진 담당자 승인, 인증키 확인, API Self TEST와 개발, 통합테스트와 LIVE 인증키 발급, 실제 적용과 모니터링 순서입니다. 가입만 했다고 운영 호출이 열리는 구조는 아닙니다.
연동 대상은 운송장 출력 하나로 끝나지 않습니다. 주문정보 등록에는 출고와 반품이 포함되고 예약취소, 배송정보 조회까지 같은 기업고객 API 묶음에서 다룹니다.
공식 연동방법과 인증 절차는 한진 Developers Portal에서 확인할 수 있습니다.
택배 API 연동방법 공식 가이드 바로가기회사 계약과 담당자 승인이 필요한 기업고객용 서비스이며 개인 배송조회 화면과는 다릅니다.
인증키 발급에는 Client id, Key, Secret key 세 값과 한진 담당자의 가입 승인이 필요합니다.
1Login에서 Create an account를 선택하고 성명, 이메일, 회사명, 전화번호, 비밀번호를 입력합니다.
2계정생성 안내메일의 본인확인 링크를 열고 회사명과 고객사 담당자 정보를 공식 지원 이메일로 회신합니다.
3고객사 담당 한진 영업담당자에게 API 센터 가입 승인을 요청합니다.
4승인 뒤 My Apps에서 DEV용 Client id와 Key, Secret key를 확인합니다.
HMAC은 요청 내용과 비밀키로 서명을 만드는 인증 방식입니다. 이 서명을 Request header의 Authorization에 넣어 서버가 보낸 쪽과 데이터가 바뀌지 않았는지 확인하게 합니다.
Secret key를 브라우저 자바스크립트나 공개 저장소에 넣으면 안 됩니다. 쇼핑몰 서버에서 서명을 만들고 프런트 화면에는 필요한 결과만 내려주는 구성이 안전합니다.
쇼핑몰 데이터 연결은 주문등록, 운송장번호 저장, 운송장 출력, 예약취소, 배송상태 갱신의 다섯 흐름으로 나누면 됩니다.
| 연동 구간 | 쇼핑몰에서 할 일 | 확인할 결과 |
|---|---|---|
| 주문등록 | 출고·반품 주문정보 전송 | 접수 성공과 오류코드 |
| 운송장 | 발급 번호를 주문에 저장 | 중복·누락 여부 |
| 출력 | 라벨과 바코드 인쇄 | 분류정보 인식 상태 |
| 취소 | 출고 전 예약취소 전송 | 취소 가능 상태 |
| 배송정보 | 상태를 주문 화면에 반영 | 마지막 갱신 시각 |
쇼핑몰 주문번호와 택배사 운송장번호를 서로 다른 칸에 저장하는 것이 핵심입니다. 두 번호를 한 필드에 덮어쓰면 취소, 재출고, 부분배송 때 어느 송장을 조회해야 하는지 알 수 없게 됩니다.
한 주문을 여러 상자로 나누는 경우에는 주문 1개에 운송장 여러 개가 연결될 수 있어야 합니다. 반대로 재시도할 때 같은 주문을 두 번 등록하지 않도록 요청 식별값도 보관합니다.
배송상태는 화면 문구만 저장하기보다 원본 상태값, 처리 시각, 마지막 조회 시각을 함께 남기는 편이 좋습니다. 그래야 고객에게 보이는 문구를 바꾸더라도 원본 이력을 잃지 않습니다.
운송장번호만 직접 확인하려는 이용자라면 개발 연동보다 운송장번호 조회방법이 빠릅니다. 이 페이지의 API는 쇼핑몰 운영자가 반복 업무를 자동화할 때 쓰는 경로입니다.
HMAC과 주문등록 테스트는 DEV 인증키로 서명을 만든 뒤 공식 Self TEST 화면에서 예제 요청을 실행하는 방식입니다.
서명 시험 경로는 /v1/util/hmacgen입니다. x-api-key와 Client id 예제값을 넣어 만든 HMAC signature를 주문정보·배송정보 요청의 Authorization 값으로 전달합니다.
주문등록 시험 경로는 /parcel-delivery/v1/order/insert-order입니다. x-api-key, HMAC 결과, Request Body 예제를 넣고 실행한 뒤 응답과 쇼핑몰 로그를 함께 확인합니다.
가이드의 hmacgen은 단순 시험용입니다. 운영환경에서는 쇼핑몰 서버가 같은 규칙으로 HMAC을 직접 생성해야 하며 시험용 생성 경로에 의존하면 안 됩니다.
RESTful API는 URL과 HTTP 요청으로 기능을 나누는 방식이고 JSON은 주문값을 이름과 값의 짝으로 담는 형식입니다. 이 두 용어를 모르면 개발자에게 “REST·JSON 방식의 주문등록과 배송조회 연동”이라고 요청하면 됩니다.
DEV와 LIVE는 시험 주문이 실제 배송으로 섞이는 사고를 막기 위해 개발 환경과 운영 환경을 나눈 것입니다.
DEV에서는 정상 주문뿐 아니라 필수값 누락, 잘못된 주소, 중복 호출, 취소 뒤 재호출 같은 실패 사례를 같이 시험합니다. 성공 응답만 한 번 보고 운영으로 넘기면 실제 주문이 몰릴 때 오류 원인을 찾기 어렵습니다.
개발 뒤에는 양사 주문정보와 배송정보가 오가는 통합테스트를 진행합니다. 고객사가 운송장을 직접 출력한다면 한진 영업담당자가 분류정보와 바코드 인쇄 상태도 검수합니다.
통합테스트를 통과해야 LIVE API와 운영 인증키를 받습니다. LIVE 운송장 출력에는 방화벽 조치가 필요하므로 고객사 서버 IP도 회신해야 합니다.
운영 전 증거는 주문등록 성공 화면 하나가 아니라 주문 전송, 송장 출력, 상태 수신, 취소, 재시도까지 이어진 기록입니다. 각 단계의 요청 시각과 응답코드를 남기면 장애 때 어느 구간에서 끊겼는지 바로 찾을 수 있습니다.
택배계약 자체가 아직이라면 택배계약 신청방법에서 월 물량과 규격을 먼저 정리하세요. API 승인과 운임 계약은 서로 연결되지만 같은 절차는 아닙니다.
배송조회 API 호출량은 한진 공식 기준으로 1초당 10개 요청인 10ps 이내에서 묶어 보내고 같은 운송장을 불필요하게 반복 조회하지 않도록 관리합니다.
제한을 넘으면 errorCode -103과 Too many request가 반환될 수 있습니다. 트래픽 급증을 막는 SpikeArrest 정책과 슬라이딩 창 방식이 적용됩니다.
주문 화면을 열 때마다 택배사 API를 직접 호출하기보다 서버가 일정 간격으로 갱신한 결과를 데이터베이스에 저장하고 이용자에게 보여주는 구성이 안정적입니다. 배송이 끝난 송장은 갱신 대상에서 빼면 호출량도 줄어듭니다.
오류가 나면 즉시 같은 요청을 수십 번 보내지 말고 대기 시간을 늘려 재시도합니다. 주문등록처럼 중복이 위험한 요청은 이전 응답과 주문 식별값을 확인한 뒤 다시 보내야 합니다.
여러 택배사를 한 화면에 모으려면 택배사 조회 바로가기 목록과 택배 조회 앱 비교방법도 함께 확인할 수 있습니다.
연동 오류 확인 순서는 환경, 승인 상태, 인증 헤더, 요청 본문, 호출 제한, 택배사 응답의 여섯 항목입니다.
환경: DEV 주소에 LIVE 키를 넣거나 LIVE 주소에 DEV 키를 넣지 않았는지 봅니다.
승인: App이 실제 승인 상태인지 확인합니다. 3개월 동안 쓰지 않은 App은 중지될 수 있으며 이때 errorCode -101이 표시됩니다.
인증: Client id, x-api-key, Authorization의 HMAC signature가 같은 요청을 기준으로 만들어졌는지 대조합니다.
본문: 필수 주문값과 JSON 형식, 문자 인코딩이 가이드 예제와 맞는지 확인합니다.
호출이 많을 때만 실패한다면 -103 여부와 10ps 제한을 먼저 봅니다. 특정 주문만 실패한다면 주소나 상품정보처럼 그 요청의 입력값을 정상 주문과 비교하는 편이 빠릅니다.
App not approved가 장기 미사용 때문에 발생했다면 openapi@hanjin.com으로 사용 재개를 요청합니다. 운영 URL과 최신 API 명세는 Developers Portal의 Guides와 API Spec download에서 다시 확인하세요.
택배 API 연동 자주 묻는 질문은 개인도 쓸 수 있는지, 운영키가 바로 나오는지, 운송장 출력이 필수인지, 조회만 붙일 수 있는지에 모입니다.
아닙니다. 기업고객 계약과 한진 영업담당자의 가입 승인 뒤 인증키를 확인하는 구조입니다. 승인 전에는 운영 호출을 전제로 개발 일정을 확정하지 않는 편이 좋습니다.
통합테스트가 먼저입니다. 주문정보와 배송정보 송수신을 확인하고 직접 송장을 출력한다면 인쇄 상태 검수까지 거친 뒤 LIVE 환경이 발급됩니다.
공식 서비스에는 배송정보 조회가 포함됩니다. 다만 사용할 API 범위와 계약 조건은 담당자에게 확인하고, 주문번호와 운송장번호를 연결할 내부 저장 구조는 별도로 마련해야 합니다.
요청 시각, 주문 식별값, HTTP 상태, 택배사 errorCode와 message를 서버 로그에 함께 저장합니다. Secret key와 개인정보 전체가 로그에 남지 않도록 가리는 처리도 필요합니다.
운영 전 마지막 점검표 30개는 계정부터 호출 제한까지 빠진 연결고리를 한 번에 찾는 목록입니다.
1번 회원가입, 2번 본인확인 메일, 3번 회사명, 4번 고객사 담당자, 5번 IT 담당자를 확인합니다.
6번 한진 영업담당자, 7번 가입 승인, 8번 Client id, 9번 Key, 10번 Secret key를 확인합니다.
11번 DEV 환경, 12번 My Apps, 13번 HMAC 서명, 14번 x-api-key, 15번 Authorization 헤더를 대조합니다.
16번 hmacgen 시험, 17번 Request Body, 18번 insert-order 경로, 19번 출고 주문, 20번 반품 주문을 시험합니다.
21번 예약취소, 22번 배송정보, 23번 운송장 출력, 24번 인쇄 상태, 25번 통합테스트 결과를 남깁니다.
26번 LIVE 인증키, 27번 서버 IP, 28번 10ps 제한, 29번 -103 오류, 30번 -101 오류까지 확인하면 운영 전 범위가 닫힙니다.
쇼핑몰 운영자가 함께 보면 좋은 글은 계약, 운송장, 통합조회, 발송 규격을 실제 업무 순서로 이어 줍니다.
출처: 한진 Developers Portal 이용안내·자주 묻는 질문. 확인일 2026-08-30. 비공식 안내 페이지입니다.