바로가기 메뉴
본문 바로가기
메뉴 바로가기
페이지 하단 바로가기

개발가이드

HOME 개발가이드

OpenAPI 서비스 개요

개요
인터넷 이용자가 웹 검색 결과 및 사용자인터페이스(UI) 등을 제공받는 데 그치지 않고 직접 응용 프로그램과 서비스를 개발할 수 있도록 공개된 API입니다.
KTNET에서 제공하는 API 서비스를 활용하여 KTNET 간이수출신고가 자동으로 연계가 됩니다.


사전준비사항
Open API 서비스를 이용하기 위해서는 아래 절차에 따라 인증키 신청을 하시기 바랍니다.
1. 회원가입
2. Key발급
3. 신고인기본값 설정

1. 전자상거래 무역포탈 Developers에 회원가입

2. Key발급
- 우측 상단 메뉴,OOO님(클릭) > "API인증번호" 링크 클릭> Key발급 화면 출력

3. 신고인기본값 설정
- 우측 상단 메뉴,OOO님(클릭) > "내정보관리" 링크 클릭 > 기본값 조회 팝업 출력

서비스 API 참조

요청 정보

API종류 URL 프로토콜 메서드 등 항목으로 구성된 서비스API 참조 관련 표입니다.
API 종류 수출신고정정(amend) URL /api/export/amend.do
프로토콜 HTTPS 버전 1.0
HTTP 메서드 POST 월 최대거리 건수 300,000
일 최대호출 건수 10,000 회당 처리 건 999
공개 여부 공개 사용자 유형 판매자(셀러)
URL 호출(테스트) https://testcbtapi.utradehub.or.kr/api/export/declaration.do
URL 호출(운영) https://cbtapi.utradehub.or.kr/api/export/declaration.do

요청 변수(샘플데이터)

json key 데이터 타입 설명 샘플 항목으로 구성된 요청 json 데이터 파라미터 정의 표입니다.
JSON Key 반복 필수 데이터타입 설명 샘플
DocCount N M INTEGER 정정신청서 개수 1
DocList Y M LIST 정정신청서. DocCount만큼 반복
SellerPartyId N M VARCHAR(35) 사용자ID (몰관리자 or 판매자) KTNETSELLER
SellerPartyRegistNo N M VARCHAR(10) 판매자 사업자등록번호 1208102922
OrderNo N M VARCHAR(50) 주문번호 100000852
RequestType N M VARCHAR(1) 요청구분구분 N : 신규 N
ApplicationType N M VARCHAR(1) 신청구분 A:정정 C:적재기간 연장 A
AmendReasonCode N M VARCHAR(2) 정정사유코드 11 화주업무 오류 12 관세사기재 오류 13 관세사계산 오류 14 세번분류 오류 21 L/C일부취소 22 계약변경 23 선적지연 24 선복량부족 25 보세운송사항 변경 26 수출승인. 추천내용등 변경 27 확정수량신고 28 확정가격신고 90 기타 11
ReasonsAttributableCode N M VARCHAR(1) 귀책사유코드 A:관세사 등 C:해외거래처/구매자 D:세관(담당자 등) E:수출화주/수출대행자 F:제조자 Z:기타 사유 C
AmendReason N M VARCHAR(200) 정정사유 반품
ExportDeclarationNo N M VARCHAR(15) 수출신고번호 8454520000071X
CustomsCode N O VARCHAR(3) 세관 041
CustomsDeptCode N O VARCHAR(2) 10
ApplicationDate N O VARCHAR(8) 신고일자 20151225
※ 이하 생략

API테스트

1. 요청데이터에 값 입력

2. "전송"버튼 클릭 후 응답 데이터 확인

<정상응답>

{
  "TotalCount": 1,
  "ErrorCount": 0,
  "ResultList": [
    {
      "SellerPartyId": "BIGDAE42",
      "OrgSeq": 0,
      "ResultTypeCode": "220",
      "ErrorDescription": "",
      "OrderNo": "101000856",
      "RequestNo": "20200309123106_101000856"
    }
  ]
}						
<오류응답>

{
  "TotalCount": 1,
  "ErrorCount": 1,
  "ResultList": [
    {
      "SellerPartyId": "BIGDAE42",
      "OrgSeq": 0,
      "ResultTypeCode": "-1",
      "ErrorDescription": "주문번호와  수출신고번호를 다시 확인해 주십시요."
    }
  ]
}

						

응답코드

json key 데이터 타입 설명 샘플 항목으로 구성된 요청 json 데이터 파라미터 정의 표입니다.
코드 코드상태 설명
220 SUCCESS 정상적으로 전송
421 잘못된 요청 api_consumer_key 또는 MallID인증정보 미존재 시
422 잘못된 요청 항목오류로 요청구조 오류, 필수항목 누락 등
500 내부 시스템 처리 오류 내부 시스템에서 발생한 오류
-1 Business 처리 오류 업무정합성 검증 오류

API 구현예제


import java.io.*;
import java.net.HttpURLConnection;
import java.net.URL;

public class APIExam {

    public static void main(String[] args) {
        try {
            String lineEnd = "\r\n";

            String apiURL = "https://testcbtapi.utradehub.or.kr/api/export/expFulfillmentStatus.do";
            String body = "{" +
                    "\"DocCount\": 1," +
                    "\"DocList\": [" +
                    "{" +
                    "\"SellerPartyId\": \"BIGDAE42\"," +
                    "\"InquiryNo\": \"771113332535\"," +
                    "\"InquiryTypeCode\": \"BL\"" +
                    "}" +
                    "]" +
                    "}";

            body = new String(body.getBytes("utf-8"));
            System.out.println(body);
            URL url = new URL(apiURL);
            HttpURLConnection con = (HttpURLConnection)url.openConnection();
            con.setRequestMethod("POST");
            con.setRequestProperty("api_consumer_key", "인증키");
            con.setRequestProperty("Content-Type", "application/json; utf-8");

            con.setDoOutput(true);
            DataOutputStream wr = new DataOutputStream(con.getOutputStream());
            wr.write(body.getBytes("utf-8"));
            wr.flush();
            wr.close();

            int responseCode = con.getResponseCode();
            BufferedReader br;
            if(responseCode==220) { // 정상 호출
                br = new BufferedReader(new InputStreamReader(con.getInputStream(), "UTF-8"));
            } else {  // 에러 발생
                br = new BufferedReader(new InputStreamReader(con.getErrorStream(), "UTF-8"));
            }

            String inputLine;
            StringBuffer response = new StringBuffer();
            while ((inputLine = br.readLine()) != null) {
                response.append(inputLine);
            }
            br.close();
            System.out.println(response.toString());

        } catch (Exception e) {
            System.out.println(e);
        }
    }

}