관세청 API로 화물 조회하는 법, 인증키 발급부터 엑셀 조회까지 (UNI-PASS 오픈API)
3줄 요약
- 관세청 UNI-PASS에 회원가입·로그인 후 'OpenAPI 사용관리'에서 '화물통관진행정보조회'를 신청하면 인증키가 바로 나옵니다.
- 인증키와 B/L 번호·입항년도를 넣은 주소를 브라우저나 엑셀에 넣으면 화물 진행상태를 조회할 수 있습니다.
- 근거: 관세청 UNI-PASS OpenAPI 연계가이드 v4.1 (API001 화물통관 진행정보), 원문 파일은 이 글에 첨부했습니다.
"수입 화물이 지금 어디까지 왔는지, 매번 유니패스에 들어가서 B/L을 하나씩 넣어 봐야 하나요?" 수입 건이 많은 회사 담당자분들이 자주 하시는 질문입니다.
관세청은 화물 진행정보를 오픈API로 제공합니다. 인증키만 받아 두면 브라우저 주소창이나 엑셀에서 바로 조회할 수 있고, 사내 시스템에 연결해 자동으로 확인할 수도 있습니다. 프로그래밍을 몰라도 따라 할 수 있도록 실제 화면 순서대로 정리했습니다.
1단계. UNI-PASS 회원가입·로그인
관세청 UNI-PASS(unipass.customs.go.kr)에 접속합니다. 화면 오른쪽 MY CUSTOMS 영역에 '로그인'과 '회원가입'이 있습니다. 오픈API는 UNI-PASS 회원만 신청할 수 있습니다.
회원가입을 누르면 회원유형 선택 화면이 나옵니다.
- 업체 및 대표자: 회사 명의로 처음 가입할 때 선택합니다. 관세청의 사용승인이 필요합니다.
- 업체 직원: 회사가 이미 가입되어 있고 직원 아이디를 추가할 때 선택합니다. 대표자의 사용승인이 필요합니다.
- 일반(개인) 사용자: 사업자가 아닌 개인으로 가입할 때 선택합니다.
가입이 끝나면 로그인합니다. 아이디·비밀번호 외에 공동·금융인증서나 정부 통합로그인(Any-ID)으로도 로그인할 수 있습니다.
2단계. 인증키 발급 (OpenAPI 사용관리)
로그인 후 상단 'My메뉴'를 누르고, 왼쪽에서 '서비스관리' → 'OpenAPI 사용관리'로 들어갑니다. 신청기간 '전체'를 누르고 '조회'를 누르면 관세청이 제공하는 오픈API 목록이 모두 나옵니다(현재 55종).
목록 마지막 페이지에 있는 '화물통관진행정보조회' 왼쪽 칸을 체크하고, 아래 'OPEN API 신청' 버튼을 누릅니다.
승인은 신청 즉시 이루어집니다. 다시 조회하면 처리상태가 '승인'으로 바뀌어 있고, 서비스명을 누르면 아래 '상세내역'의 '인증키' 칸에 내 인증키가 표시됩니다.
- ✔ 인증키는 API마다 따로 발급됩니다. HS부호, 환율 등 다른 API를 쓰려면 각각 신청하세요.
- ✔ 인증키는 비밀번호처럼 관리하고, 메일·메신저로 외부에 공유하지 마세요.
3단계. 브라우저 주소창으로 조회하기
조회 주소는 정해진 주소 뒤에 인증키와 조회할 번호를 붙여 만듭니다.
- B/L 번호로 조회할 때: 인증키(crkyCn) + House B/L(hblNo) 또는 Master B/L(mblNo) + 입항년도(blYy)
- 화물관리번호로 조회할 때: 인증키(crkyCn) + 화물관리번호(cargMtNo)
B/L 번호로 조회할 때는 입항년도를 꼭 넣어야 합니다. 완성한 주소를 크롬이나 엣지 주소창에 붙여 넣고 엔터를 누르면 결과가 태그 형식(XML)으로 나옵니다.
정상적으로 조회되면 위와 같은 결과가 나옵니다. 이해를 돕기 위해 가상의 B/L 번호(AINH26101501)와 화물 정보로 만든 예시입니다.
- ① 진행상태(prgsStts)·통관진행상태(csclPrgsStts): 화물이 지금 어느 단계인지 보여 줍니다. 예시는 수입신고가 수리되고 창고에서 반출까지 끝난 상태입니다.
- ② 조회한 B/L 번호가 맞는지 확인합니다.
- ③ 입항일자(etprDt)는 '20261008'처럼 연월일 8자리로 나옵니다.
- ④ 아래쪽 반복 묶음은 처리 이력입니다. 위가 가장 최근이고, 반입신고 → 수입신고 수리 → 반출신고 순으로 진행됐다는 뜻입니다. 처리일시(prcsDttm)와 장치장(shedNm)도 함께 나옵니다.
인증키가 틀리면 위처럼 '존재하지 않는 인증키입니다' 메시지와 함께 tCnt(결과 건수)가 -1로 나옵니다. 키를 복사할 때 앞뒤 공백이 들어가지 않았는지 확인하세요.
4단계. 엑셀로 조회하기
Windows용 엑셀(2013 이상)이라면 함수 두 개로 조회할 수 있습니다.
- WEBSERVICE(주소): 관세청 응답(XML)을 그대로 가져옵니다.
- FILTERXML(응답, "//태그명"): 응답에서 필요한 항목만 뽑습니다.
B/L 번호를 여러 줄로 적어 두고 수식을 아래로 복사하면 여러 건을 한 번에 확인할 수 있습니다. 다만 Mac용·웹용 엑셀에서는 이 함수가 동작하지 않습니다.
5단계. 결과 읽는 법
결과에서 먼저 볼 항목은 진행상태(prgsStts)와 통관진행상태(csclPrgsStts)입니다. 반입신고·수입신고수리·반출신고 같은 처리 이력과 화물이 있는 장치장(shedNm)도 함께 나옵니다.
- ✔ 메시지가 [N00]으로 시작하면 같은 B/L에 화물이 여러 건이라는 뜻입니다. 목록에 나온 화물관리번호로 다시 조회하세요.
- ✔ 관세청 데이터 보관 정책에 따라 최근 3년 이내 화물만 조회됩니다.
참고. API 없이 한 건만 볼 때
한두 건만 확인할 때는 로그인 없이 UNI-PASS '정보조회 → 통관물류정보 → 수입화물 진행정보' 화면에서 B/L 번호와 년도를 넣고 조회해도 됩니다. 매일 여러 건을 확인해야 한다면 API가 훨씬 편합니다.
💬 사내 시스템이나 ERP에 화물 조회를 연결하고 싶은데 어디서부터 해야 할지 막막하다면, 아인합동관세사무소로 문의해 주세요. 수입 화물 관리 방식에 맞춰 안내해 드립니다.
첨부
- 관세청 「UNI-PASS OpenAPI 연계가이드 v4.1」 원문 (MYC_OpenAPI 연계가이드_v4.1.docx)
- 최신판은 UNI-PASS OpenAPI 사용관리 화면의 '연계가이드 다운로드' 버튼으로도 받을 수 있습니다.
출처
- 자료: 관세청 UNI-PASS OpenAPI 연계가이드 v4.1, 2.1 서비스 신청 · 3.2.1 화물통관 진행정보(API001)
- 화면: 관세청 UNI-PASS (unipass.customs.go.kr), 2026. 10. 캡처. 개인정보와 인증키는 가렸습니다.
유의사항
관세청 화면 구성과 서비스 내용은 바뀔 수 있습니다. 이 글은 일반 안내이며 개별 시스템 연계는 관세청 기술지원센터 안내를 함께 확인하세요. (작성 2026. 10.)
상담 안내
화물 조회 자동화나 수입 화물 관리가 궁금하다면 아인합동관세사무소에 문의하세요.
- 작성: 정석현 대표관세사
- 휴대전화: 010-7906-5432
- 이메일: jsh@aincustoms.com
- 사무소: 02-518-5435 · aincustoms.com
카드뉴스 이미지 전체는 네이버 블로그 원문에서 볼 수 있습니다.