REST 요금 조회 API

REST 배송 요금 조회 API입니다.

  • 출발/도착 국가 코드와 물품의 중량/부피 정보만 전달합니다.
  • departureCountryCode, arrivalCountryCode는 ISO 3166-1 alpha-2 코드(KR, JP 등)를 사용합니다.
  • deliveryItems[].weight는 물품별 실중량이며 여러 물품이 있으면 합산합니다.
  • volumeInputType이 1이면 cbm 값은 무시하고 width/depth/height로 CBM을 계산하며, 2이면 cbm 값을 직접 사용합니다.
  • 과금중량은 총 실중량과 총 부피무게 중 큰 값이며, 요금표 조회 시 0.5kg 단위로 올림합니다.
  • 배송 접수 시 요금 조회에서 선택한 options[].transportType을 deliveryGlobal.transportType으로 전달합니다.
  • 배송 접수 시 요금 조회에서 선택한 options[].estimatedAmount를 deliveryGlobal.amount로 전달합니다.

API Endpoint

POST/v1/rest/pricing
Cookie Auth RequiredRequest: application/jsonResponse: */*

API 한눈에 보기

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

Samples included

Request Fields

10

Required Fields

5

Response Fields

10

Available Code Samples

cURL / fetch / Request / Response

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

• 요금 조회 options[].transportType을 배송 접수 deliveryGlobal.transportType으로 전달합니다.

• volumeInputType=1은 치수로 CBM 계산, 2는 cbm 직접 입력입니다.

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

구현 체크리스트 (Implementation Checklist)

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

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

✓departureCountryCode, arrivalCountryCode는 ISO 3166-1 alpha-2 형식으로 전달합니다.

✓응답 options에서 사용자가 선택한 transportType과 estimatedAmount를 배송 접수 요청에 저장합니다.

운영 확인 항목

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

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

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

Request Body

3 fields3 required1 nested

departureCountryCode

required
string

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

exampleKR

arrivalCountryCode

required
string

도착 국가 코드(ISO 3166-1 alpha-2)

exampleJP

deliveryItems

required
ARRAY하위 7개

요금 계산 대상 물품의 중량/부피 정보 리스트

example[]

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

Request Body

/

deliveryItems[]

deliveryItems[] 하위 필드

7 fields

요금 계산 대상 물품의 중량/부피 정보 리스트

ARRAY

weight

required
number

물품 실중량(kg)

example10

count

nullable
number

int32

수량. 생략 시 1로 계산합니다.

example1

volumeInputType

required
number

int32

부피 입력 방식. 1: 치수 입력(width/depth/height로 CBM 계산, cbm 값은 무시), 2: CBM 직접 입력(cbm 값 사용)

example1

width

nullable
number

가로(cm). volumeInputType=1일 때 필요합니다.

example30

depth

nullable
number

세로(cm). volumeInputType=1일 때 필요합니다.

example40

height

nullable
number

높이(cm). volumeInputType=1일 때 필요합니다.

example25

cbm

nullable
number

CBM. volumeInputType=2일 때 필요합니다.

example0.03

Response

4 fields1 nested

success

boolean

API 성공 여부

exampletrue

message

string

전달 메세지

exampleAPI가 정상 처리되었습니다

errorCode

number

int32

에러 코드

example0

data

OBJECT하위 1개

요금 조회 API Response Data. 배송 접수 시 선택한 옵션의 transportType은 deliveryGlobal.transportType, estimatedAmount는 deliveryGlobal.amount로 전달합니다.

example{}

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

Response

/

data

data 하위 필드

1 fields

요금 조회 API Response Data. 배송 접수 시 선택한 옵션의 transportType은 deliveryGlobal.transportType, estimatedAmount는 deliveryGlobal.amount로 전달합니다.

OBJECT

options

ARRAY하위 5개

운송 옵션별 요금 배열. 선택 불가 옵션도 available=false와 unavailableReason으로 함께 반환합니다.

example[]

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

Response

/

data.options[]

options[] 하위 필드

5 fields

운송 옵션별 요금 배열. 선택 불가 옵션도 available=false와 unavailableReason으로 함께 반환합니다.

ARRAY

expressVendor

string

운송 옵션 코드. AIR_FIRST, DHL, UPS, SEA, FEDEX, EMS, ASAP

exampleDHL

transportType

number

int32

국제 운송 수단. 이 옵션을 선택해 접수할 때 deliveryGlobal.transportType으로 전달합니다.

example7

estimatedAmount

number

예상 적용 요금. 이 옵션을 선택해 접수할 때 deliveryGlobal.amount로 전달합니다.

example25200

available

boolean

선택 가능 여부. false이면 estimatedAmount는 null입니다.

exampletrue

unavailableReason

nullable
string

선택 불가 사유

examplestring

예시 코드 및 샘플

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

curl -X POST "$BASE_URL/v1/rest/pricing" \
  -H "Content-Type: application/json" -H "lang: ko" \
  -H "Cookie: accessToken=발급받은_토큰값" \
  -d '{"departureCountryCode":"KR","arrivalCountryCode":"JP","deliveryItems":[{"weight":10,"count":1,"volumeInputType":1,"width":30,"depth":40,"height":25}]}'
const response = await fetch(`${BASE_URL}/v1/rest/pricing`, {
  "method": "POST",
  "headers": {
    "Content-Type": "application/json",
    "lang": "ko",
    "Cookie": "accessToken=발급받은_토큰값"
  },
  "body": "{\"departureCountryCode\":\"KR\",\"arrivalCountryCode\":\"JP\",\"deliveryItems\":[{\"weight\":10,\"count\":1,\"volumeInputType\":1,\"width\":30,\"depth\":40,\"height\":25}]}"
});

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

const data = await response.json();
{
  "departureCountryCode": "KR",
  "arrivalCountryCode": "JP",
  "deliveryItems": [
    {
      "weight": 10,
      "count": 1,
      "volumeInputType": 1,
      "width": 30,
      "depth": 40,
      "height": 25
    }
  ]
}
{
  "success": true,
  "message": "API가 정상 처리되었습니다",
  "errorCode": 0,
  "data": {
    "options": [
      {
        "expressVendor": "DHL",
        "transportType": 7,
        "estimatedAmount": 25200,
        "available": true,
        "unavailableReason": "string"
      }
    ]
  }
}