농협택배 조회 API
농협택배는 농협물류가 운영하는 택배 서비스로, 하나로마트와 지역농협 접수처에서 물건을 받아 보냅니다.
배송조회 API에서는 courier code nonghyup을 쓰며, nhlogis로 보내도 같은 택배사로 처리됩니다.
농협택배 소개
농협택배는 하나로마트·지역농협 접수처에서 물건을 접수합니다. 접수한 물건을 실제로 실어 나르고 집 앞까지 전달하는 일은 제휴택배사인 한진택배의 배송망이 맡습니다. 그래서 농협택배 홈페이지에도 고객센터 번호로 제휴택배사(한진)의 번호가 안내되어 있습니다.
운송장 조회는 농협택배 홈페이지의 배송조회에서 할 수 있고, API는 이 화면이 보여 주는 것과 같은 조회 결과를 다른 택배사와 똑같은 통합 응답 형식으로 바꿔 돌려드립니다. 공식 사이트는 ex.nhlogis.co.kr입니다.
기본 정보
| 택배사명 | 농협택배 |
|---|---|
| 운영사 | 농협물류 (배송은 제휴택배사 한진택배 망) |
| API courier code | nonghyup (별칭: nhlogis) |
| 고객센터 | 1588-0011 (제휴택배사 한진 고객센터) / 1644-6702 (방문택배 전용) |
| 조회 화면 | ex.nhlogis.co.kr 배송조회 |
| 지원 범위 | 조회(tracking) 전용 — 계정 기반 등록·출력은 지원하지 않습니다 |
운송장번호 형식
농협택배 운송장번호는 숫자 12자리입니다. 하이픈이나 공백은 빼고 숫자만 보내 주세요.
12자리라는 상한은 농협이 직접 정해 둔 값입니다. 홈페이지 조회창의 입력칸이 숫자만, 최대 12자리까지 받도록 되어 있어 12자리를 넘게 칠 수 없습니다. 그래서 API도 12자리를 넘는 번호는 농협에 묻기 전에 형식 오류로 돌려드립니다. 더 짧은 번호는 농협이 따로 밝힌 하한이 없어서, 저희 공통 규칙(6자리 이상)만 적용합니다.
끝자리 검증은 농협의 판정을 따릅니다
농협은 운송장번호에 검증 숫자 규칙이 있는지, 있다면 어떻게 계산하는지를 공개하지 않았습니다.
그래서 저희는 자릿수만 확인하고 끝자리 계산은 하지 않습니다. 짐작한 규칙으로 멀쩡한 송장을 막는 것보다
농협에 그대로 물어보는 편이 안전하다고 판단했습니다. 농협에 없는 번호는 농협 조회 결과가 비어 있으므로,
API는 이 경우를 조회 결과 없음(NOT_FOUND)으로 응답합니다.
API 연동 예시
조회는 단일 엔드포인트 호출로 끝납니다. {API_KEY}와 {SECRET_KEY}에는 발급받은 키 쌍을 넣으세요.
아래 운송장번호 123456789013은 자릿수를 보여 주기 위한 예시이며 실제 송장이 아닙니다.
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": "nonghyup",
"trackingNumber": "123456789013"
}
]
}' items는 배열이므로 농협택배 운송장 여러 건을 한 번에, 또는 다른 택배사 송장과 섞어서 보낼 수 있습니다.
응답 필드 정의와 오류 코드는 API 문서를 참고하세요.
배송 이력과 단계
농협택배 조회 화면의 진행 막대에는 출고준비 → 집하완료 → 간선이동 → 배송출발 → 배송완료 다섯 단계와, 배송하지 못한 경우를 위한 미배송 단계가 있습니다. 실측한 배송완료 건에는 아래 다섯 단계가 한 줄씩, 모두 5줄이 찍혔습니다.
| 진행 단계 | 이력 문구 | 의미 |
|---|---|---|
| 출고준비 | 고객님의 상품을 접수하였습니다. | 하나로마트·지역농협 접수처가 물건을 받아 두고 집하를 기다림 |
| 집하완료 | 고객님의 상품이 집하점에 입고되었습니다. | 접수처의 물건을 집하점이 가져가 배송망에 들어옴 |
| 간선이동 | 배송점으로 이동중 입니다. | 배송을 맡을 지역의 배송점으로 옮겨지는 중 |
| 배송출발 | 배송원이 상품을 전달하기위해 출발하였습니다. | 배송원이 물건을 싣고 수취인에게 가는 중 |
| 배송완료 | 배송완료 되었습니다. | 수취인(또는 대신 받은 사람)에게 전달되어 배송이 끝남 |
각 이력의 location에는 그 단계를 처리한 곳의 이름이 들어갑니다.
접수 단계는 농협 원본에 처리 장소가 비어 있어, 대신 물건을 받은 접수처 이름(예: ○○농협 하나로마트)을 채워 드립니다.
배송출발 이후에는 배송을 맡은 곳의 이름이 응답의 arrivalBranch에도 담깁니다.
이력마다 분 단위 시각이 있습니다
농협은 이력 한 줄마다 날짜와 시·분을 함께 줍니다. API는 농협 조회 화면에 보이는 것과 같은 시각을 한국 시간 기준으로
각 이력의 dateTime에 담습니다. 농협 원본은 오래된 이력부터 나열하지만, API는 다른 국내 택배사와 마찬가지로
최신 이력이 맨 앞에 오도록 정렬해 돌려드립니다.
배송 상태 코드 매핑
위 단계들은 API에서 아래 통합 상태값으로 정규화되어 나갑니다.
택배사 원문 대신 이 상태값으로 분기하면 다른 택배사와 같은 코드로 처리할 수 있습니다.
송장 전체의 현재 상태(deliveryStatus)는 농협이 조회 결과에 함께 주는 현재 단계 요약을 따릅니다.
| 농협택배 표기 | 통합 상태 | 설명 |
|---|---|---|
| 출고준비 | REGISTERED | 접수처에 접수되었고, 아직 집하 전입니다. |
| 집하완료 | PICKED_UP | 집하점에 입고되어 배송망에 들어왔습니다. |
| 간선이동 | IN_TRANSIT | 배송점으로 이동 중입니다. |
| 배송출발 | OUT_FOR_DELIVERY | 배송원이 수취인에게 향하고 있습니다. |
| 배송완료 | DELIVERED | 수취인에게 물건이 전달되었습니다. |
| 미배송 | FAILED | 배송을 시도했으나 전달하지 못했습니다. |
"출고준비"를 배송 출발로 읽지 마세요. 이 단계는 하나로마트·지역농협 접수처가 물건을 받아 두고
집하를 기다리는 상태라, 물건은 아직 접수처를 떠나지 않았습니다. 그래서 통합 상태는 REGISTERED이고,
수취인에게 가는 단계는 "배송출발"(OUT_FOR_DELIVERY)에서 따로 시작됩니다.
"미배송"은 실제 이력을 아직 확인하지 못했지만, 농협 조회 화면이 이 단계를 실패 표시로 그리기 때문에 FAILED로 매핑합니다.
농협이 미배송 사유를 함께 주면 그 이력의 description에 덧붙여 드립니다.
자주 묻는 질문 (FAQ)
농협택배의 courier code는 무엇인가요?
표준값은 nonghyup이며, 요청 본문에 "courierCode": "nonghyup"으로 넣으면 됩니다.
조회 사이트 도메인에서 딴 nhlogis도 별칭으로 등록되어 있어 같은 결과를 받습니다.
배송은 한진택배가 하는데, hanjin으로 조회하면 안 되나요?
농협택배 송장은 nonghyup으로 조회하세요. 같은 송장이 한진 조회에도 나오고,
한진 쪽은 터미널 사이 이동을 더 잘게 보여 줍니다. 하지만 하나로마트·지역농협 접수처에
맡긴 단계("출고준비")는 농협 조회에만 나옵니다. API는 농협 조회를 기준으로 결과를 드리므로,
접수 단계부터 함께 받을 수 있습니다.
운송장번호를 미리 검증해도 되나요?
"숫자만, 12자리 이하"까지는 안전하게 걸러도 됩니다. 실제로 쓰이는 번호는 12자리입니다.
다만 끝자리를 직접 계산해 막는 것은 권하지 않습니다 — 공개된 계산식이 없으니,
잘못된 번호인지는 조회 결과(NOT_FOUND 여부)로 판단하는 편이 정확합니다.
조회했는데 NOT_FOUND가 나와요
두 가지 경우가 대부분입니다. 숫자를 잘못 옮겨 적었거나 농협에 없는 번호라 농협 조회 화면에서도 "검색된 결과가 없습니다"로 나오는 경우,
그리고 다른 택배사의 송장을 nonghyup으로 조회한 경우입니다. 번호와 택배사를 다시 확인해 보세요.
받는 분 주소나 배송원 연락처도 받을 수 있나요?
받을 수 없습니다. 수취인 주소와 배송원 이름·휴대폰 번호, 집배점 연락처는 개인정보라서, 농협 쪽 조회 결과에 들어 있더라도 API 응답에는 담지 않습니다.
보내는 분·받는 분 이름은 농협 조회 화면과 같은 방식으로 가운데를 가린 값(예: 김*국)으로만 드립니다.
이력에 연락처(telno)가 들어가지 않으므로, 배송 문의처는 고객센터 1588-0011로 안내해 주세요.
운송장 발행이나 출력도 API로 되나요?
되지 않습니다. 농협택배는 조회(tracking)만 지원합니다. 접수는 하나로마트·지역농협 접수처를 통해 이루어지고, 발행된 운송장번호로 배송 상태를 조회하는 데 API를 쓰게 됩니다.