관세청 Open API 활용 프로젝트 #1 화물통관진행정보조회하기 (1)

 

 

 관세청에서는 민원인들을 위해 민원인들의 정보와 영업비밀을 보호할 수 있는 선에서만 개방된 OpenAPI 서비스를 제공하고 있습니다. 업무상 애플리케이션을 자체 개발해 활용할 수 있도록 다양한 데이터셋을 제공하고 있는데요. 

 

 TradeNPU에도 무역업체들이 공익성이 강한 이러한 데이터들을 쉽고 빠르게 접근해 활용하도록 도울 방법들을 구상 중에 있었습니다.

 그리고, 이제 해당 프로젝트를 착수하여 TradeNPU를 통해 서비스를 제공할 예정인데요.

 관련된 내용을 포스팅을 진행해 보고자 합니다.

 

 

 

 관세청 OpenAPI 신청방법

 

 관세청 OpenAPI 신청을 위해서는 관세청 Unipass 계정이 우선 필요합니다.

 관세청 Unipass 계정을 최초로 만들 때엔 각종의 정보입력을 요구 받게 되는데요.

 세금납부 및 관계업무를 위한 다양한 서비스를 제공 중인 터라, 필수입력이 요구되는 정보가 많으므로 인내심을 가지고 계정생성 작업을 진행합니다.

 

 그리고, 계정이 만들어지면 My 메뉴를 통해 OpenAPI 사용관리 페이지에 접근할 수 있는데요.

 해당 페이지에 접근한 후 활용하고자 하는 DataSet을 제공하는 End-point 에 대해 체크 후 OPEN API 신청 버튼을 누르면 승인처리가 진행되게 됩니다.

 

 

 

 어떠한 End-point에서 내가 원하는 데이터셋을 제공하는지 미리 알아보기 위해서 '연계가이드 다운로드'도 우선 진행합니다.

 

 해당 자료를 통해 API를 통해 데이터를 호출하는 방법과 입력할 parameter 값들의 형식과 종류, 필수여부에 대해 파악할 수 있으며, 어떤 데이터들이 어떤 구조로 호출되는지에 대해 알 수 있으므로, 잘 참조하여 개발을 진행하여야 하겠습니다.

 

 

 

 

 화물통관진행정보조회 연결가이드

 

 

 이제 그러면 타겟하고 있는 '화물통관진행정보조회'의 데이터 호출을 위한 연계가이드를 살펴 보겠습니다.

 승인 받은 End-point에 대해서 호출시 인증키는 기본적으로 parameter로 제공되어야 합니다.

 

 해당 인증키는 위 단락에서 보았던, Open API 승인화면 아래쪽에 표출되는 테이블에서 인증키값을 확인할 수 있습니다.

 각자에게 부여된 것이므로, 보안을 잘 지켜 해당 인증키를 호출 때 사용하도록 코딩해야 하겠습니다.

 

 가이드에서는 아래의 형태로 url을 구성해 호출하도록 설명하고 있습니다.

 

 

https://unipass.customs.go.kr:38010/ext/rest/statsSgnQry/retrieveStatsSgnBrkd?crkyCn= 00 인증키&statsSgnTp=부호코드  

 

 

https://unipass.customs.go.kr:38010/ext/rest/statsSgnQry/retrieveStatsSgnBrkd   ==> 호출대상 End-point URI

Parameter로 crkyCn에 부여받은 인증키값을 대입합니다.

그리고, statsSgnTp에 부호코드를 대입합니다.

 

 

 위는 일반적인 호출 URI 구성을 표현한 것이며,

 타겟하고 있는 화물통관진행정보조회 연결가이드에서는 아래의 URI를 예제로 제시하고 있습니다.

 

https://unipass.customs.go.kr:38010/ext/rest/cargCsclPrgsInfoQry/retrieveCargCsclPrgsInfo?crkyCn=[인증키]&cargMtNo=00ANLU083N59007001

  

 

 위 예제에서는 구체적인 건의 조회를 위해 cargMtNo라는 이름을 가진 parameter를 입력하게 하고 있는데, 15 ~ 19자리로 구성된 화물관리번호를 이 parameter명을 이용해 호출이 가능하다는 의미입니다.

 

 만약, 화물관리번호가 없다면, 다음의 parameter들을 이용해 호출시도가 가능하므로 다음 parameter를 이용하면 되겠습니다.

 

 

 

 

 

 통상, 수출입건을 다룰 때엔, 가장 먼저 House B/L > Master B/L > 화물관리번호 의 선호도를 가지고 조회를 진행하게 되므로, 이 점 반영하면 호출구문이 구성되게 코딩이 진행되면 되겠습니다.

 

 

 

 

 

 

 

또한, 조회결과는 단건 또는 다건으로 나올 수 있는데, 단건이면 바로 상세내용으로 들어가고, 다건이면 목록을 제공한다고 말하고 있습니다.

 

 

 이는 호출된 결과값의 구조를 보면 설명할 수 있는데요.

 단건이면 return되는 XML 결과값 구조상 바로 상세정보 항목들로 진입하는 구조를 띄는 반면, 다건이면 목록 형태로 한번 더 구조를 묶어 내기에 각 건들의 상세정보로 진입하려면 한 단계 더 깊숙이 들어가는 구조로 데이터셋을 제공하겠다는 의미로 받아들이면 되겠습니다.

 

 

 따라서, 단건일 때와 다건일 때의 조건분기를 두어 코딩이 진행되어야 함을 암시하고 있다 하겠습니다.

 

 그리고 다건일 때엔 화물관리번호를 이용해 다시 호출하면 상세내용 조회가 가능한 단건으로 정보 제공을 한다고 언급하고 있습니다.

 

 

 코딩 방식은 취사선택하면 되는데, 다건일 때 (1) 이미 진행한 호출로 한번 더 깊숙히 들어가서 parsing할거냐, 아니면, (2) 개별건에 대해 개별로 추가 호출을 할거냐를 선택하여 코딩을 진행하면 된다고 이해해도 되겠습니다.

 

 

 그리고 응답메시지 상세가 나오는데요.

 각 변수명이 어떤 값을 나타내는지에 대한 설명입니다.

 표출되거나, 가공되어야 할 필수 데이터만 parsing하도록 코딩이 진행되면 되겠습니다.

 

 

 그리고 나서, 호출시 결과값 예시를 아래와 같이 제시하고 있습니다.

 

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>  - <cargCsclPrgsInfoQryRtnVo> 
<ntceInfo/> - <cargCsclPrgsInfoQryVo> 
<csclPrgsStts>수입싞고수리</csclPrgsStts> 
<vydf/> 
<rlseDtyPridPassTpcd>N</rlseDtyPridPassTpcd> 
<prnm>MAG****LAY</prnm> 
<ldprCd>D****K</ldprCd> 
<shipNat>TH</shipNat> 
<blPt>C</blPt> 
<dsprNm>인천공항</dsprNm> 
<etprDt>2****6</etprDt> 
<prgsStCd>CAGE12</prgsStCd> 
<msrm/> 
<wghtUt>KG</wghtUt> 
<dsprCd>ICN</dsprCd> 
<cntrGcnt>0</cntrGcnt> 
<cargTp>수입 일반화물</cargTp> 
<shcoFlcoSgn>XJ</shcoFlcoSgn> 
<pckGcnt>6</pckGcnt> 
<etprCstm>인천세관</etprCstm> 
<shipNm>XJ700</shipNm> 
<hblNo>605118340404</hblNo> 
<prcsDttm>20****044</prcsDttm> 
<entsKoreNm>태화********회사</entsKoreNm> 
<frwrSgn>T**X</frwrSgn> 
<spcnCargCd/> 
<ttwg>1009</ttwg> 
<ldprNm>D****G</ldprNm> 
<dclrDelyAdtxYn>N</dclrDelyAdtxYn> 
<mtTrgtCargYnNm>N</mtTrgtCargYnNm> 
<cargMtNo>18XJ****0002</cargMtNo> 
<cntrNo/> 
<mblNo>94000499505</mblNo> 
<blPtNm>Consol</blPtNm> 
<lodCntyCd>TH</lodCntyCd> 
<prgsStts>반출완료</prgsStts> 
<shcoFlco>타이에어****티드</shcoFlco> 
<pckUt>CT</pckUt> 
<shipNatNm>태국</shipNatNm> 
<agnc/> 
</cargCsclPrgsInfoQryVo> 
<tCnt>8</tCnt> 
<cargCsclPrgsInfoDtlQryVo> 
<shedNm>(주) ****공</shedNm> 
<prcsDttm>201****44</prcsDttm> 
<dclrNo>0407****0162</dclrNo> 
<rlbrDttm>20****54</rlbrDttm> 
<wght>1009</wght> 
<rlbrBssNo>41****3M</rlbrBssNo> 
<bfhnGdncCn/>
<wghtUt>KG</wghtUt> 
<pckGcnt>6</pckGcnt> 
<cargTrcnRelaBsopTpcd>반출싞고</cargTrcnRelaBsopTpcd> 
<pckUt>CT</pckUt> 
<rlbrCn>수입싞고 수리후 반출</rlbrCn> 
<shedSgn>0****1</shedSgn> 
</cargCsclPrgsInfoDtlQryVo> 
</cargCsclPrgsInfoQryRtnVo>

 

 

 이제 XML 호출방법과 결과의 형태도 파악이 완료 되었므로, Parsing을 진행할 코딩을 다음 포스팅에서 진행해 보겠습니다.

 

 

 

 

 

 

NPU(엔피유) 관세사무소

대표관세사 고장주

Tel) 031-986-7190

E-mail) sales@npucus.com

[NPU관세사무소 홈페이지] https://www.npucus.com/

[NPU관세사무소 프로모션 페이지] https://www.tradenpu.com/npu_cus/

[무역비지니스 인텔리전스 서비스 | TradeNPU] https://www.tradenpu.com​

TradeNPU | 무역 사무자동화 디지털 플랫폼

 

[파이썬 실용 예제. 무역과 공공데이터] https://pdatinmylife.tistory.com

​

Certified Customs Broker JangJu Goh

Executive Customs Broker @ NPU Customs Consulting

CEO @ JG TradePlus

​

sales@npucus.com

Trade Compliance / Customs clearance management at foreign company

Working experience of Air export freight forwarding

Data Visualization / Independent development of business automation application – copyright of JGPO_Manager, JG Data Center, AutoCC and etc.

B2B consignment & direct export/import, B2C Overseas Buying Office consulting

Alibaba.com B2B trade / taobao B2C trade / Amazon.com global selling etc. Online trade regulation consulting.

Import license / Quarantine

English communication available

​

[TradeNPU for partnership proposal - JGTP] https://www.tradenpu.com/jgtp/