HSK 코드 조회 API

한국 HS 코드 6자리를 기준으로 하위 HSK 코드 목록을 조회합니다.

  • REST 인증 API로 발급받은 accessToken 쿠키가 필요합니다.
  • hsCode query parameter는 숫자 6자리만 허용합니다.
  • 응답의 hsCodeList에는 조회된 HSK 코드 후보 목록이 포함됩니다.
  • 조회 조건에 해당하는 HSK 코드가 없으면 hsCodeList는 빈 배열로 반환됩니다.
  • 각 항목의 name, nameOrigin은 전체 계층 경로를 포함한 품명입니다.
  • details는 HS 코드 계층 구조를 순서대로 제공하며, 각 계층의 hsCode, name, nameOrigin을 포함합니다.

API Endpoint

GET/v1/rest/hsk-codes
Cookie Auth RequiredResponse: application/json

API 한눈에 보기

구현 전에 확인할 요청/응답 규모와 코드값 힌트입니다.

Samples included

Request Fields

1

Required Fields

1

Response Fields

0

Available Code Samples

cURL / fetch

• 인증 후 Cookie: accessToken=발급받은_토큰값 헤더가 필요합니다.

구현 체크리스트 (Implementation Checklist)

✓요청 헤더에 Cookie: accessToken=발급받은_토큰값을 포함합니다.

✓Content-Type과 lang 헤더를 실제 운영 환경에서도 동일하게 전달합니다.

운영 확인 항목

!요청 시각, path, HTTP status, errorCode를 로그에 보관합니다.

!개인정보 필드는 로그와 실패 알림에서 완벽히 마스킹 처리합니다.

!4xx 에러는 요청 데이터 자가 보정, 5xx 에러는 임시 지수 백오프 적용 대상으로 삼습니다.

Query Parameters

1 fields1 required

hsCode

required
string

조회할 한국 HS 코드 6자리 숫자

example300212

예시 코드 및 샘플

같은 요청을 cURL, JavaScript fetch, JSON 샘플로 확인할 수 있습니다.

curl -X GET "$BASE_URL/v1/rest/hsk-codes?hsCode=300212" \
  -H "lang: ko" \
  -H "Cookie: accessToken=발급받은_토큰값"
const response = await fetch(`${BASE_URL}/v1/rest/hsk-codes`, {
  "method": "GET",
  "headers": {
    "lang": "ko",
    "Cookie": "accessToken=발급받은_토큰값"
  }
});

if (!response.ok) {
  const error = await response.json();
  throw new Error(`ASAP API error: ${response.status} ${error.message ?? ''}`);
}

const data = await response.json();