관세율 조회 API

HSK 코드와 국가 정보를 기준으로 한국 수입 시 적용 가능한 관세율을 조회합니다.

  • REST 인증 API로 발급받은 accessToken 쿠키가 필요합니다.
  • 원산지, 수출국, 수입국은 ISO 3166-1 alpha-2 국가코드(예: US, KR)로 전달합니다.
  • 수입국은 현재 KR만 지원합니다.
  • hsCode는 한국 HSK 코드 10자리 숫자만 허용합니다.
  • itemInfo는 관세율 판단 근거 생성에 사용할 품목 설명이며 필수값입니다.
  • 유효하지 않은 HSK 코드이거나 한국 HS 코드 마스터에 없는 경우 오류를 반환합니다.
  • 단일 관세율은 appliedTariffRate에 소수점 둘째 자리 숫자로 반환합니다.
  • 범위 관세율은 appliedTariffRate를 null로 반환하고 appliedTariffRateRangeStart, appliedTariffRateRangeEnd에 시작/종료값을 반환합니다.
  • 관세율 단위는 appliedTariffRateUnit 필드로 분리해서 반환합니다.

API Endpoint

POST/v1/rest/tariffs/lookup
Cookie Auth RequiredRequest: application/jsonResponse: application/json

API 한눈에 보기

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

Samples included

Request Fields

5

Required Fields

5

Response Fields

11

Available Code Samples

cURL / fetch / Request / Response

• 국가 코드는 ISO 3166-1 alpha-2 형식입니다. 예: KR, JP, US

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

구현 체크리스트 (Implementation Checklist)

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

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

운영 확인 항목

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

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

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

Request Body

5 fields5 required

originCountryCode

required
string

원산지 국가 코드(ISO 3166-1 alpha-2)

exampleUS

departureCountryCode

required
string

수출 국가 코드(ISO 3166-1 alpha-2)

exampleUS

arrivalCountryCode

required
string

수입 국가 코드(ISO 3166-1 alpha-2)

exampleKR

hsCode

required
string

HSK 코드(한국 HS 코드 10자리)

example6104630000

itemInfo

required
string

관세율 판단 근거 생성에 사용할 품목 설명

example여성용 합성섬유 니트 바지

Response

4 fields1 nested

success

boolean

API 성공 여부

exampletrue

message

string

전달 메세지

exampleAPI가 정상 처리되었습니다

errorCode

number

int32

에러 코드

example0

data

OBJECT하위 7개

관세율 조회 API Response Data

example{}

이 필드는 객체 구조입니다. 하위 필드는 섹션에서 확인합니다.

Response

/

data

data 하위 필드

7 fields

관세율 조회 API Response Data

OBJECT

appliedTariffCode

string

적용 관세 코드

exampleA

appliedTariffRate

number

적용 관세율

example8

appliedTariffRateRangeStart

number

적용 관세율 범위 시작값

example21.17

appliedTariffRateRangeEnd

number

적용 관세율 범위 종료값

example43.6

appliedTariffRateUnit

string

적용 관세율 단위

example%

appliedTariffReasoning

string

적용 관세 판단 근거

example원산지 US, 수출국 US, 수입국 KR 기준으로 적용 가능한 협정세율이 없어 기본세율을 적용했습니다.

appliedTariffReasoningEn

string

적용 관세 판단 근거(영문)

exampleThe base tariff rate was applied because no preferential agreement rate was a...

예시 코드 및 샘플

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

curl -X POST "$BASE_URL/v1/rest/tariffs/lookup" \
  -H "Content-Type: application/json" -H "lang: ko" \
  -H "Cookie: accessToken=발급받은_토큰값" \
  -d '{"originCountryCode":"US","departureCountryCode":"US","arrivalCountryCode":"KR","hsCode":"6104630000","itemInfo":"여성용 합성섬유 니트 바지"}'
const response = await fetch(`${BASE_URL}/v1/rest/tariffs/lookup`, {
  "method": "POST",
  "headers": {
    "Content-Type": "application/json",
    "lang": "ko",
    "Cookie": "accessToken=발급받은_토큰값"
  },
  "body": "{\"originCountryCode\":\"US\",\"departureCountryCode\":\"US\",\"arrivalCountryCode\":\"KR\",\"hsCode\":\"6104630000\",\"itemInfo\":\"여성용 합성섬유 니트 바지\"}"
});

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

const data = await response.json();
{
  "originCountryCode": "US",
  "departureCountryCode": "US",
  "arrivalCountryCode": "KR",
  "hsCode": "6104630000",
  "itemInfo": "여성용 합성섬유 니트 바지"
}
{
  "success": true,
  "message": "API가 정상 처리되었습니다",
  "errorCode": 0,
  "data": {
    "appliedTariffCode": "A",
    "appliedTariffRate": 8,
    "appliedTariffRateRangeStart": 21.17,
    "appliedTariffRateRangeEnd": 43.6,
    "appliedTariffRateUnit": "%",
    "appliedTariffReasoning": "원산지 US, 수출국 US, 수입국 KR 기준으로 적용 가능한 협정세율이 없어 기본세율을 적용했습니다.",
    "appliedTariffReasoningEn": "The base tariff rate was applied because no preferential agreement rate was available for origin US, departure US, and arrival KR."
  }
}