Developer Docs

ASAP REST API

기업 계정 인증 후 배송 접수, 수정, 취소, 조회와 요금 조회를 연동하기 위한 외부 REST API 문서입니다. 연동 계정 신청부터 운영 전환 체크리스트까지 연계사가 바로 구현할 수 있는 기준을 함께 제공합니다.

Endpoints

Base URL

https://api.asapx.ai

Dev URL

https://dev-api.asapx.ai

Language

lang: ko | en

Auth Cookie

accessToken

Updated

2026-06-17

Quick Start Guide

연계사는 아래 순서대로 테스트하면 인증, 요금 조회, 배송 접수, 사후 조회까지 한 흐름으로 검증할 수 있습니다.

REST API 사용 신청

REST API 연동 계정과 사용 권한은 info@asapx.ai로 신청합니다. 기업계정 회원가입에 필요한 희망 아이디, 담당자명, 이메일, 연락처를 함께 전달합니다.

REST API 사용 신청 메일 작성하기

인증 토큰 발급

POST /v1/rest/auth 호출 후 Set-Cookie로 전달되는 accessToken을 이후 요청 Cookie 헤더에 포함합니다.

요금 조회

POST /v1/rest/pricing으로 국가 코드와 물품 중량/부피를 전달하고 options[].transportType, estimatedAmount를 확인합니다.

배송 접수

POST /v1/rest/delivery에서 요금 조회 결과로 선택한 transportType과 estimatedAmount를 deliveryGlobal에 전달합니다.

운영 검증

GET /v1/rest/delivery로 접수 결과를 확인하고, 수정/취소 가능 상태와 실패 응답을 함께 테스트합니다.

공통 요청 규칙 (Global Request Headers)

인증 (Authentication)

Cookie: accessToken=...

언어 (Language)

lang: ko 또는 lang: en

본문 (Content-Type)

Content-Type: application/json

코드표 및 조건부 입력

API별 필드 설명과 함께, 연계사가 구현 중 반복해서 확인하는 코드값과 조건부 입력 규칙을 모았습니다.

transportType

• 1: 항공(퍼스트)

• 2: 항공(비즈니스-DHL)

• 3: 항공(이코노미-UPS)

• 4: 해운

• 5: 항공(FEDEX)

• 6: 항공(EMS)

• 7: 항공(ASAP)

volumeInputType

• 1: width/depth/height로 CBM 계산

• 2: cbm 값을 직접 전달

countryCode

• ISO 3166-1 alpha-2 형식

• 예: KR, JP, US

• KR -> KR은 국내 배송, 그 외 조합은 해외 배송

공통 헤더

• Content-Type: application/json

• lang: ko 또는 lang: en

• Cookie: accessToken=발급받은_토큰값

응답 처리 기준

REST API는 HTTP status를 우선 기준으로 처리합니다. 응답 body의 errorCode는 상세 원인 파악을 위한 ASAP 내부 코드입니다.

HTTP status first

성공 판정

HTTP status가 2xx이고 body.code가 0이면 정상 처리로 간주합니다. 응답 data가 비어 있을 수 있으므로 code를 우선 확인합니다.

요청 오류

400 계열은 필수값 누락, 형식 오류, 상태 제한 등 클라이언트 보정 대상입니다. errorCode와 message를 사용자/운영 로그에 함께 남깁니다.

인증 오류

401/403은 accessToken 만료, 권한 미부여, 쿠키 누락을 먼저 확인합니다. 토큰 재발급 후 동일 요청을 재시도합니다.

서버 오류

5xx는 즉시 무한 재시도하지 않고 지수 백오프를 적용합니다. 반복 발생 시 요청 시각, path, HTTP status, errorCode로 문의합니다.

200

• 성공

201

Created

• 배송 접수 성공

400

Bad Request

• 요청 값 검증 실패

• 필수값 누락

• 날짜/형식 오류

401

Unauthorized

• 인증 정보 없음

• accessToken 없음/만료/유효하지 않음

403

Forbidden

• 본인 배송이 아님

• REST API 사용 권한 없음

• 기업 계정이 아님

• 비활성/승인 전 계정

404

Not Found

• 배송 없음

• 계정 없음

409

Conflict

• 현재 상태에서 처리 불가

• 접수 신청 상태가 아니라 수정 불가

• 이미 취소된 배송

• 결제 완료/추가결제 상태라 취소 불가

500

Internal Server Error

• 서버 내부 오류

• 처리 결과 확인 불가

ASAP errorCode 목록

0

SUCCESS

요청이 정상 처리되었습니다.

1000

NO_DATA_ERROR

조회 대상 데이터가 존재하지 않습니다.

1001

REQUIRE_SIGNIN_ERROR

로그인이 필요하거나 인증 정보가 없습니다.

1002

REQUIRE_SIGNUP_ERROR

회원가입 또는 계정 정보가 필요합니다.

1003

USER_ACTIVATE_ERROR

비활성 또는 승인 전 계정입니다.

1004

TOKEN_NOT_FOUND_ERROR

accessToken이 전달되지 않았습니다.

1005

TOKEN_INVALID_ERROR

accessToken이 만료되었거나 유효하지 않습니다.

1006

USER_PERMISSION_ERROR

요청 권한이 없습니다.

1009

ARGUMENT_NOT_VALID_ERROR

요청 값 검증에 실패했습니다.

1016

ETC_ERROR

기타 서버 처리 오류입니다.

오류 응답 예시

400 Bad Request

{
  "code": 1009,
  "name": "ARGUMENT_NOT_VALID_ERROR",
  "message": "요청 값 검증에 실패했습니다.",
  "details": [
    "phoneNum은 숫자만 전달합니다.",
    "deliveryItems는 최소 1개 이상 필요합니다."
  ]
}

401 Unauthorized

{
  "code": 1005,
  "name": "TOKEN_INVALID_ERROR",
  "message": "accessToken이 만료되었거나 유효하지 않습니다."
}

409 Conflict

{
  "code": 1016,
  "name": "ETC_ERROR",
  "message": "현재 배송 상태에서는 요청을 처리할 수 없습니다."
}

운영 연동 기준

운영 전환 전에는 성공 케이스뿐 아니라 타임아웃, 인증 만료, 중복 접수, 취소 불가 상태를 함께 검증해야 합니다.

Timeout / Retry

네트워크 오류나 5xx 응답은 동일 요청을 즉시 무한 재시도하지 말고, 지수 백오프와 운영자 확인 절차를 적용합니다.

중복 접수 방지

배송 접수 응답의 deliveryId 또는 접수번호를 저장하고, 클라이언트 타임아웃 시 조회 API로 결과를 먼저 확인합니다.

개인정보 보호

이름, 연락처, 이메일, 주소는 운영 로그와 실패 알림에 원문으로 남기지 않도록 마스킹 정책을 적용합니다.

운영 문의

연동 승인, 계정 권한, 장애 문의는 ASAP 담당 채널을 통해 API 요청 시각, path, HTTP status, errorCode를 함께 전달합니다.

Authentication

API 호출에 필요한 세션을 발급하고 종료합니다.

Delivery

배송 접수, 수정, 취소, 상세 조회를 처리합니다.

REST 배송 접수 API입니다.

요청 Content-Type은 application/json만 지원합니다.
REST 접수/수정 API에서는 첨부파일을 받지 않습니다.
deliveryItems는 최소 1개 이상 필요하며, 배송 1건에 여러 물품을 등록할 수 있습니다.
departureDeliveryAddress.countryCode와 arrivalDeliveryAddress.countryCode는 ISO 3166-1 alpha-2 국가코드(KR, JP, US 등)를 전달합니다.
배송 타입은 국가코드 기준으로 백엔드에서 자동 판별합니다. KR -> KR은 국내 배송, 그 외는 해외 배송으로 처리합니다.
returnDeliveryAddress, deliveryPayment은 백엔드에서 자동 세팅합니다.
longitude/latitude가 누락되면 백엔드에서 주소 기반 보정을 시도하고, 보정 실패 시 에러를 반환합니다.
해외 배송 접수 시 deliveryGlobal.transportType에는 요금 조회에서 선택한 options[].transportType을 전달합니다.
해외 배송 접수 시 deliveryGlobal.amount에는 요금 조회에서 선택한 options[].estimatedAmount를 전달합니다.

Request Body

11 fields7 required4 nested

etd

nullable

string

date-time

픽업 요청 일시. null 또는 생략 시 기존 배송 접수 로직 기준으로 처리됩니다.

example2026-05-27T00:00:00+09:00

eta

nullable

string

date-time

도착 희망 일시. 필수 값이 아니며, 전달하지 않으면 도착 희망일 없이 접수됩니다.

example2026-05-27T00:00:00+09:00

memo

nullable

string

배송 관련 메모. 운송 요청사항, 취급 주의사항 등을 전달합니다.

example샘플 배송 메모

deliveryItems

required

ARRAY하위 18개

물품 정보 리스트. 최소 1개 이상 필요하며, 배송 1건에 여러 물품을 등록할 수 있습니다.

example[]

info

required

string

대표 품목명. 목록/알림/결제명 요약에서 대표 물품명으로 사용될 수 있습니다.

example사과

detailInfo

nullable

string

품목 상세 설명. 규격, 브랜드, 보관 조건 등 운영자가 확인해야 하는 상세 내용을 입력합니다.

example청송 사과 10kg

packageType

required

string

포장 형태명. 예: 박스, 팔레트, 봉투. 텍스트 값으로 저장됩니다.

example박스

count

required

number

int32

물품 수량. 숫자만 입력하며 '개', '박스' 같은 단위 문자는 제외합니다.

example1

volumeInputType

required

number

int32

부피 입력 방식. 1: width/depth/height로 CBM 계산, 2: cbm 값을 직접 사용합니다.

example1

weight

required

number

물품 실중량(kg). 요금 조회 시 전체 물품 weight 합계가 총 실중량으로 계산됩니다.

example1

width

number

가로 길이(cm). volumeInputType이 1이면 CBM 계산에 사용됩니다.

example30

depth

number

세로 길이(cm). volumeInputType이 1이면 CBM 계산에 사용됩니다.

example40

height

number

높이(cm). volumeInputType이 1이면 CBM 계산에 사용됩니다.

example25

cbm

number

CBM 값. volumeInputType이 2이면 이 값을 직접 사용하고, volumeInputType이 1이면 width * depth * height / 1,000,000으로 계산됩니다.

example0.03

coldChainFlag

required

number

int32

콜드체인 필요 여부. 1: 필요, 2: 불필요. 1인 경우 minTemperature 또는 maxTemperature를 함께 전달합니다.

example2

minTemperature

nullable

number

허용 최저온도(섭씨). coldChainFlag가 1인 경우 냉장/냉동 조건 판단에 사용합니다.

example-15.5

maxTemperature

nullable

number

허용 최고온도(섭씨). coldChainFlag가 1인 경우 냉장/냉동 조건 판단에 사용합니다.

example8

hazardousFlag

required

number

int32

위험물 포함 여부. 1: 포함, 2: 미포함. 위험물 포함 시 운영 검토 대상입니다.

example2

incoterms

nullable

string

인코텀즈. 해외 배송일 때 거래 조건 확인용으로 사용합니다. 허용 예: EXW, FCA, FAS, FOB, CFR, CIF, CPT, CIP, DAP, DPU, DDP.

exampleFOB

customsSupport

nullable

number

int32

통관 및 관세 지원 서비스 신청 여부. 1: 신청, 2: 미신청.

example1

insuranceSupport

nullable

number

int32

보험 서비스 신청 여부. 1: 신청, 2: 미신청.

example1

hsCode

nullable

string

HS Code. 해외 배송 통관/관세 조회에 사용하는 품목 분류 코드입니다.

example080810

name

required

string

접수자 이름. 결제 payerName 자동 세팅에도 사용됩니다.

example홍길동

required

string

접수자 이메일. 배송 접수자 연락 정보로 저장됩니다.

exampleasap@asapx.ai

phoneNum

required

string

접수자 연락처. 숫자만 입력하며 하이픈(-)은 제외합니다.

example01000000000

division

nullable

string

접수자 계정 구분. 지점명, 부서명 등 외부사 내부 구분값을 전달할 수 있습니다.

example샘플 지점

departureDeliveryAddress

required

OBJECT하위 11개

배송 주소 등록 Request Data. 국가 코드는 ISO 3166-1 alpha-2로 전달하며, 위경도 누락 시 백엔드에서 주소 기반 보정을 시도합니다.

example{}

arrivalDeliveryAddress

required

OBJECT하위 11개

배송 주소 등록 Request Data. 국가 코드는 ISO 3166-1 alpha-2로 전달하며, 위경도 누락 시 백엔드에서 주소 기반 보정을 시도합니다.

example{}

deliveryGlobal

required

OBJECT하위 2개

배송 접수 해외 운송 옵션 Request Data. 요금 조회에서 선택한 옵션 값을 전달합니다.

example{}

Response

4 fields1 nested

success

boolean

API 성공 여부

exampletrue

message

string

전달 메세지

exampleAPI가 정상 처리되었습니다

errorCode

number

int32

에러 코드

example0

data

OBJECT하위 2개

배송 접수 API Response Data

example{}

예시 코드 및 샘플

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

curl -X POST "$BASE_URL/v1/rest/delivery" \
  -H "Content-Type: application/json" -H "lang: ko" \
  -H "Cookie: accessToken=발급받은_토큰값" \
  -d '{"etd":"2026-07-01T09:00:00Z","eta":"2026-07-03T18:00:00Z","memo":"샘플 배송 메모","deliveryItems":[{"info":"사과","detailInfo":"사과","packageType":"박스","count":1,"volumeInputType":1,"weight":1,"width":1,"depth":1,"height":1,"cbm":0.001,"coldChainFlag":2,"hazardousFlag":1,"incoterms":"FOB","customsSupport":1,"insuranceSupport":1,"hsCode":"080810"}],"name":"홍길동","email":"asap@asapx.ai","phoneNum":"01000000000","division":"샘플 지점","departureDeliveryAddress":{"name":"홍길동","phoneNum":"01000000000","email":"asap@asapx.ai","postalCode":"00000","countryCode":"KR","stateOrProvince":"서울","city":"강남구","streetAddress":"샘플로 1","detailAddress":"101호","longitude":126.978,"latitude":37.5665},"arrivalDeliveryAddress":{"name":"홍길동","phoneNum":"01000000000","email":"asap@asapx.ai","postalCode":"0000000","countryCode":"JP","stateOrProvince":"Tokyo","city":"Shibuya","streetAddress":"1-1-1 Shibuya","detailAddress":"Sample Building 101","longitude":139.7016,"latitude":35.658},"deliveryGlobal":{"transportType":7,"amount":25200}}'

const response = await fetch(`${BASE_URL}/v1/rest/delivery`, {
  "method": "POST",
  "headers": {
    "Content-Type": "application/json",
    "lang": "ko",
    "Cookie": "accessToken=발급받은_토큰값"
  },
  "body": "{\"etd\":\"2026-07-01T09:00:00Z\",\"eta\":\"2026-07-03T18:00:00Z\",\"memo\":\"샘플 배송 메모\",\"deliveryItems\":[{\"info\":\"사과\",\"detailInfo\":\"사과\",\"packageType\":\"박스\",\"count\":1,\"volumeInputType\":1,\"weight\":1,\"width\":1,\"depth\":1,\"height\":1,\"cbm\":0.001,\"coldChainFlag\":2,\"hazardousFlag\":1,\"incoterms\":\"FOB\",\"customsSupport\":1,\"insuranceSupport\":1,\"hsCode\":\"080810\"}],\"name\":\"홍길동\",\"email\":\"asap@asapx.ai\",\"phoneNum\":\"01000000000\",\"division\":\"샘플 지점\",\"departureDeliveryAddress\":{\"name\":\"홍길동\",\"phoneNum\":\"01000000000\",\"email\":\"asap@asapx.ai\",\"postalCode\":\"00000\",\"countryCode\":\"KR\",\"stateOrProvince\":\"서울\",\"city\":\"강남구\",\"streetAddress\":\"샘플로 1\",\"detailAddress\":\"101호\",\"longitude\":126.978,\"latitude\":37.5665},\"arrivalDeliveryAddress\":{\"name\":\"홍길동\",\"phoneNum\":\"01000000000\",\"email\":\"asap@asapx.ai\",\"postalCode\":\"0000000\",\"countryCode\":\"JP\",\"stateOrProvince\":\"Tokyo\",\"city\":\"Shibuya\",\"streetAddress\":\"1-1-1 Shibuya\",\"detailAddress\":\"Sample Building 101\",\"longitude\":139.7016,\"latitude\":35.658},\"deliveryGlobal\":{\"transportType\":7,\"amount\":25200}}"
});

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

const data = await response.json();

{
  "etd": "2026-07-01T09:00:00Z",
  "eta": "2026-07-03T18:00:00Z",
  "memo": "샘플 배송 메모",
  "deliveryItems": [
    {
      "info": "사과",
      "detailInfo": "사과",
      "packageType": "박스",
      "count": 1,
      "volumeInputType": 1,
      "weight": 1,
      "width": 1,
      "depth": 1,
      "height": 1,
      "cbm": 0.001,
      "coldChainFlag": 2,
      "hazardousFlag": 1,
      "incoterms": "FOB",
      "customsSupport": 1,
      "insuranceSupport": 1,
      "hsCode": "080810"
    }
  ],
  "name": "홍길동",
  "email": "asap@asapx.ai",
  "phoneNum": "01000000000",
  "division": "샘플 지점",
  "departureDeliveryAddress": {
    "name": "홍길동",
    "phoneNum": "01000000000",
    "email": "asap@asapx.ai",
    "postalCode": "00000",
    "countryCode": "KR",
    "stateOrProvince": "서울",
    "city": "강남구",
    "streetAddress": "샘플로 1",
    "detailAddress": "101호",
    "longitude": 126.978,
    "latitude": 37.5665
  },
  "arrivalDeliveryAddress": {
    "name": "홍길동",
    "phoneNum": "01000000000",
    "email": "asap@asapx.ai",
    "postalCode": "0000000",
    "countryCode": "JP",
    "stateOrProvince": "Tokyo",
    "city": "Shibuya",
    "streetAddress": "1-1-1 Shibuya",
    "detailAddress": "Sample Building 101",
    "longitude": 139.7016,
    "latitude": 35.658
  },
  "deliveryGlobal": {
    "transportType": 7,
    "amount": 25200
  }
}

{
  "success": true,
  "message": "API가 정상 처리되었습니다",
  "errorCode": 0,
  "data": {
    "deliveryId": 1,
    "deliveryNo": "ASAP202607010001"
  }
}

REST 배송 수정 API입니다.

접수 신청 상태의 배송건만 수정할 수 있습니다.
요청 Content-Type은 application/json입니다.
REST 수정 API에서는 첨부파일을 받지 않습니다.
전달하지 않은 필드는 기존 값을 유지합니다.
deliveryItems[].deliveryItemId가 있으면 기존 물품 수정, 없으면 신규 물품 추가로 처리합니다.
deleteDeliveryItemIdList로 물품을 삭제할 수 있으며, 삭제 후 물품이 0개가 되면 에러를 반환합니다.

Request Body

13 fields1 required4 nested

deliveryId

required

number

int64

수정할 배송 ID(인덱스). 배송 조회 응답의 deliveryId 값을 전달합니다.

example1

deliveryType

nullable

number

int32

배송 타입. 1: 해외 배송, 2: 국내 배송. 생략 시 기존 배송 타입을 유지합니다.

example1

name

nullable

string

접수자 이름. 생략 시 기존 값을 유지합니다.

example홍길동

nullable

string

접수자 이메일. 생략 시 기존 값을 유지합니다.

exampleasap@asapx.ai

phoneNum

nullable

string

접수자 연락처. 숫자만 입력하며 하이픈(-)은 제외합니다. 생략 시 기존 값을 유지합니다.

example01000000000

division

nullable

string

접수자 계정 구분. 지점명, 부서명 등 외부사 내부 구분값을 전달할 수 있습니다. 생략 시 기존 값을 유지합니다.

example샘플 지점

etd

nullable

string

date-time

픽업 요청 일시. 생략 시 기존 값을 유지합니다.

example2026-05-27T00:00:00+09:00

eta

nullable

string

도착 희망 일시. 생략 시 기존 값을 유지하고, 빈 문자열 입력 시 null로 초기화합니다.

example2026-07-03T18:00:00

deliveryItems

nullable

ARRAY하위 18개

물품 정보 리스트. deliveryItemId가 있으면 기존 물품 수정, 없으면 신규 물품 추가로 처리합니다. 생략 시 물품 정보는 변경하지 않습니다.

example[]

deliveryItemId

nullable

number

int64

배송 물품 ID(인덱스). 값이 있으면 해당 물품 수정, 없으면 신규 물품 추가로 처리합니다.

example1

info

nullable

string

대표 품목명. 생략 시 기존 값을 유지합니다.

example사과

detailInfo

nullable

string

품목 상세 설명. 생략 시 기존 값을 유지합니다.

example청송 사과 10kg

packageType

nullable

string

포장 형태명. 예: 박스, 팔레트, 봉투. 생략 시 기존 값을 유지합니다.

example박스

count

nullable

number

int32

물품 수량. 숫자만 입력하며 단위 문자는 제외합니다. 생략 시 기존 값을 유지합니다.

example1

volumeInputType

nullable

number

int32

부피 입력 방식. 1: width/depth/height로 CBM 계산, 2: cbm 값을 직접 사용합니다. 생략 시 기존 값을 유지합니다.

example1

weight

nullable

number

물품 실중량(kg). 생략 시 기존 값을 유지합니다.

example1

width

nullable

number

가로 길이(cm). volumeInputType이 1이면 CBM 계산에 사용됩니다. 생략 시 기존 값을 유지합니다.

example30

depth

nullable

number

세로 길이(cm). volumeInputType이 1이면 CBM 계산에 사용됩니다. 생략 시 기존 값을 유지합니다.

example40

height

nullable

number

높이(cm). volumeInputType이 1이면 CBM 계산에 사용됩니다. 생략 시 기존 값을 유지합니다.

example25

cbm

number

CBM 값. volumeInputType이 2이면 이 값을 직접 사용합니다. 생략 시 기존 값을 유지합니다.

example0.03

coldChainFlag

nullable

number

int32

콜드체인 필요 여부. 1: 필요, 2: 불필요. 생략 시 기존 값을 유지합니다.

example2

minTemperature

nullable

number

허용 최저온도(섭씨). coldChainFlag가 1인 경우 냉장/냉동 조건 판단에 사용합니다.

example-15.5

maxTemperature

nullable

number

허용 최고온도(섭씨). coldChainFlag가 1인 경우 냉장/냉동 조건 판단에 사용합니다.

example8

hazardousFlag

nullable

number

int32

위험물 포함 여부. 1: 포함, 2: 미포함. 생략 시 기존 값을 유지합니다.

example2

incoterms

nullable

string

인코텀즈. 해외 배송 거래 조건 확인용입니다. 허용 예: EXW, FCA, FAS, FOB, CFR, CIF, CPT, CIP, DAP, DPU, DDP.

exampleFOB

customsSupport

nullable

number

int32

통관 및 관세 지원 서비스 신청 여부. 1: 신청, 2: 미신청. 생략 시 기존 값을 유지합니다.

example1

insuranceSupport

nullable

number

int32

보험 서비스 신청 여부. 1: 신청, 2: 미신청. 생략 시 기존 값을 유지합니다.

example1

deleteDeliveryItemIdList

nullable

ARRAY

삭제할 배송 물품 ID 리스트. 삭제 후 물품이 0개가 되면 수정할 수 없습니다.

example[]

departureDeliveryAddress

nullable

OBJECT하위 11개

배송 주소 수정 Request Data. 전달한 필드만 수정 대상이며, 국가 코드가 전달되면 국가 마스터 기준으로 처리합니다.

example{}

arrivalDeliveryAddress

nullable

OBJECT하위 11개

배송 주소 수정 Request Data. 전달한 필드만 수정 대상이며, 국가 코드가 전달되면 국가 마스터 기준으로 처리합니다.

example{}

deliveryGlobal

nullable

OBJECT하위 1개

배송 수정 국가 이동 Request Data. 해외 배송 운송 구간을 수정할 때 사용합니다.

example{}

Response

4 fields1 nested

success

boolean

API 성공 여부

exampletrue

message

string

전달 메세지

exampleAPI가 정상 처리되었습니다

errorCode

number

int32

에러 코드

example0

data

OBJECT하위 1개

배송 수정 API Response Data

example{}

예시 코드 및 샘플

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

curl -X PATCH "$BASE_URL/v1/rest/delivery" \
  -H "Content-Type: application/json" -H "lang: ko" \
  -H "Cookie: accessToken=발급받은_토큰값" \
  -d '{"deliveryId":1,"eta":"2026-07-03T18:00:00","deliveryItems":[{"deliveryItemId":10,"info":"사과","detailInfo":"청송 사과 10kg","packageType":"박스","count":1,"volumeInputType":1,"weight":10,"width":30,"depth":40,"height":25,"coldChainFlag":2,"hazardousFlag":2,"incoterms":"FOB","customsSupport":1,"insuranceSupport":1,"hsCode":"080810"}],"deleteDeliveryItemIdList":[]}'

const response = await fetch(`${BASE_URL}/v1/rest/delivery`, {
  "method": "PATCH",
  "headers": {
    "Content-Type": "application/json",
    "lang": "ko",
    "Cookie": "accessToken=발급받은_토큰값"
  },
  "body": "{\"deliveryId\":1,\"eta\":\"2026-07-03T18:00:00\",\"deliveryItems\":[{\"deliveryItemId\":10,\"info\":\"사과\",\"detailInfo\":\"청송 사과 10kg\",\"packageType\":\"박스\",\"count\":1,\"volumeInputType\":1,\"weight\":10,\"width\":30,\"depth\":40,\"height\":25,\"coldChainFlag\":2,\"hazardousFlag\":2,\"incoterms\":\"FOB\",\"customsSupport\":1,\"insuranceSupport\":1,\"hsCode\":\"080810\"}],\"deleteDeliveryItemIdList\":[]}"
});

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

const data = await response.json();

{
  "deliveryId": 1,
  "eta": "2026-07-03T18:00:00",
  "deliveryItems": [
    {
      "deliveryItemId": 10,
      "info": "사과",
      "detailInfo": "청송 사과 10kg",
      "packageType": "박스",
      "count": 1,
      "volumeInputType": 1,
      "weight": 10,
      "width": 30,
      "depth": 40,
      "height": 25,
      "coldChainFlag": 2,
      "hazardousFlag": 2,
      "incoterms": "FOB",
      "customsSupport": 1,
      "insuranceSupport": 1,
      "hsCode": "080810"
    }
  ],
  "deleteDeliveryItemIdList": []
}

{
  "success": true,
  "message": "API가 정상 처리되었습니다",
  "errorCode": 0,
  "data": {
    "deliveryId": 1
  }
}

REST 배송 상세 조회 API입니다.

deliveryId를 query parameter로 전달합니다.
본인 계정으로 접수한 배송만 조회할 수 있습니다.
물품 정보는 deliveryItems 배열로 반환합니다.

Query Parameters

1 fields1 required

deliveryId

required

number

int64

배송 ID(인덱스)

example1

Response

4 fields1 nested

success

boolean

API 성공 여부

exampletrue

message

string

전달 메세지

exampleAPI가 정상 처리되었습니다

errorCode

number

int32

에러 코드

example0

data

OBJECT하위 17개

REST 배송 상세 조회 Response Data. REST 접수에서 전달한 값과 백엔드 생성 식별/상태 값만 반환합니다.

example{}

deliveryId

number

int64

배송 ID(인덱스)

example1

deliveryType

number

int32

배송 타입. 1: 해외 배송, 2: 국내 배송

example1

deliveryNo

string

배송 접수 번호

exampleKR0001JP

deliveryStatus

number

int32

배송 상태

example1

paymentStatus

number

int32

결제 상태

example1

etd

nullable

string

date-time

픽업 요청 일시

example2026-05-27T00:00:00+09:00

eta

nullable

string

date-time

도착 희망 일시

example2026-05-27T00:00:00+09:00

memo

nullable

string

배송 관련 메모

example샘플 배송 메모

name

string

접수자 이름

example홍길동

string

접수자 이메일

exampleasap@asapx.ai

phoneNum

string

접수자 연락처

example01000000000

division

nullable

string

접수자 계정 구분

example샘플 지점

createdTime

string

date-time

접수일시

example2026-05-27T00:00:00+09:00

deliveryItems

ARRAY하위 19개

물품 정보 리스트

example[]

departureDeliveryAddress

OBJECT하위 11개

REST 배송 상세 조회 주소 Response Data

example{}

arrivalDeliveryAddress

OBJECT하위 11개

REST 배송 상세 조회 주소 Response Data

example{}

deliveryGlobal

nullable

OBJECT하위 2개

REST 배송 상세 조회 해외 운송 Response Data

example{}

예시 코드 및 샘플

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

curl -X GET "$BASE_URL/v1/rest/delivery?deliveryId=1" \
  -H "lang: ko" \
  -H "Cookie: accessToken=발급받은_토큰값"

const response = await fetch(`${BASE_URL}/v1/rest/delivery`, {
  "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();

{
  "success": true,
  "message": "API가 정상 처리되었습니다",
  "errorCode": 0,
  "data": {
    "deliveryId": 1,
    "deliveryType": 1,
    "deliveryNo": "KR0001JP",
    "deliveryStatus": 1,
    "paymentStatus": 1,
    "etd": "2026-05-27T00:00:00+09:00",
    "eta": "2026-05-27T00:00:00+09:00",
    "memo": "샘플 배송 메모",
    "name": "홍길동",
    "email": "asap@asapx.ai",
    "phoneNum": "01000000000",
    "division": "샘플 지점",
    "createdTime": "2026-05-27T00:00:00+09:00",
    "deliveryItems": [
      {
        "deliveryItemId": 1,
        "info": "사과",
        "detailInfo": "청송 사과 10kg",
        "packageType": "박스",
        "count": 1,
        "volumeInputType": 1,
        "weight": 10,
        "width": 30,
        "depth": 40,
        "height": 25,
        "cbm": 0.03,
        "coldChainFlag": 2,
        "minTemperature": -15.5,
        "maxTemperature": 8,
        "hazardousFlag": 2,
        "incoterms": "FOB",
        "customsSupport": 1,
        "insuranceSupport": 1,
        "hsCode": "080810"
      }
    ],
    "departureDeliveryAddress": {
      "name": "홍길동",
      "phoneNum": "01000000000",
      "email": "asap@asapx.ai",
      "postalCode": "00000",
      "countryCode": "KR",
      "stateOrProvince": "서울",
      "city": "강남구",
      "streetAddress": "샘플로 1",
      "detailAddress": "101호",
      "longitude": 126.978,
      "latitude": 37.5665
    },
    "arrivalDeliveryAddress": {
      "name": "홍길동",
      "phoneNum": "01000000000",
      "email": "asap@asapx.ai",
      "postalCode": "00000",
      "countryCode": "KR",
      "stateOrProvince": "서울",
      "city": "강남구",
      "streetAddress": "샘플로 1",
      "detailAddress": "101호",
      "longitude": 126.978,
      "latitude": 37.5665
    },
    "deliveryGlobal": {
      "transportType": 7,
      "amount": 25200
    }
  }
}

HSK Code

HS Code 6자리 기준으로 HSK 코드 후보를 조회합니다.

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

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

Query Parameters

1 fields1 required

hsCode

required

string

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

example300212

Response

4 fields1 nested

success

boolean

API 성공 여부

exampletrue

message

string

전달 메세지

exampleAPI가 정상 처리되었습니다

errorCode

number

int32

에러 코드

example0

data

OBJECT하위 1개

HSK 코드 조회 API Response Data

example{}

예시 코드 및 샘플

같은 요청을 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();

{
  "success": true,
  "message": "HSK 코드가 정상적으로 조회되었습니다.",
  "errorCode": 0,
  "data": {
    "hsCodeList": [
      {
        "hsCode": "3002122000",
        "name": "사람의 피, 치료용ㆍ예방용ㆍ진단용으로 조제한 동물의 피, 면역혈청ㆍ그 밖의 혈액 분획물과 면역물품(생물공학적 방법에 따라 변성되거나 얻어진 것인지에 상관없다), 백신ㆍ독소ㆍ미생물 배양체(효모는 제외한다)와 이와 유사한 물품, 세포 배양체(변성된 것인지에 상관없다) (3002) --> 면역혈청, 그 밖의 혈액 분획물과 면역물품(생물공학적 방법에 따라 변성되거나 얻어진 것인지에 상관없다) (3002.1) --> 면역혈청과 그 밖의 혈액 분획물 (3002.12) --> 면역혈청 (3002.12-2000)",
        "nameOrigin": "Human blood; animal blood prepared for therapeutic, prophylactic or diagnostic uses; antisera, other blood fractions and immunological products, whether or not modified or obtained by means of biotechnological processes; vaccines, toxins, cultures of micro-organisms(excluding yeasts) and similar products; cell cultures, whether or not modified. (3002) --> Antisera, other blood fractions and immunological products, whether or not modified or obtained by means of biotechnological processes : (3002.1) --> Antisera and other blood fractions (3002.12) --> Antisera (3002.12-2000)",
        "details": [
          {
            "hsCode": "3002",
            "name": "사람의 피, 치료용ㆍ예방용ㆍ진단용으로 조제한 동물의 피, 면역혈청ㆍ그 밖의 혈액 분획물과 면역물품(생물공학적 방법에 따라 변성되거나 얻어진 것인지에 상관없다), 백신ㆍ독소ㆍ미생물 배양체(효모는 제외한다)와 이와 유사한 물품, 세포 배양체(변성된 것인지에 상관없다)",
            "nameOrigin": "Human blood; animal blood prepared for therapeutic, prophylactic or diagnostic uses; antisera, other blood fractions and immunological products, whether or not modified or obtained by means of biotechnological processes; vaccines, toxins, cultures of micro-organisms(excluding yeasts) and similar products; cell cultures, whether or not modified."
          },
          {
            "hsCode": "30021",
            "name": "면역혈청, 그 밖의 혈액 분획물과 면역물품(생물공학적 방법에 따라 변성되거나 얻어진 것인지에 상관없다)",
            "nameOrigin": "Antisera, other blood fractions and immunological products, whether or not modified or obtained by means of biotechnological processes :"
          },
          {
            "hsCode": "300212",
            "name": "면역혈청과 그 밖의 혈액 분획물",
            "nameOrigin": "Antisera and other blood fractions"
          },
          {
            "hsCode": "3002122000",
            "name": "면역혈청",
            "nameOrigin": "Antisera"
          }
        ]
      },
      {
        "hsCode": "3002123000",
        "name": "사람의 피, 치료용ㆍ예방용ㆍ진단용으로 조제한 동물의 피, 면역혈청ㆍ그 밖의 혈액 분획물과 면역물품(생물공학적 방법에 따라 변성되거나 얻어진 것인지에 상관없다), 백신ㆍ독소ㆍ미생물 배양체(효모는 제외한다)와 이와 유사한 물품, 세포 배양체(변성된 것인지에 상관없다) (3002) --> 면역혈청, 그 밖의 혈액 분획물과 면역물품(생물공학적 방법에 따라 변성되거나 얻어진 것인지에 상관없다) (3002.1) --> 면역혈청과 그 밖의 혈액 분획물 (3002.12) --> 그 밖의 혈액 분획물 (3002.12-3000)",
        "nameOrigin": "Human blood; animal blood prepared for therapeutic, prophylactic or diagnostic uses; antisera, other blood fractions and immunological products, whether or not modified or obtained by means of biotechnological processes; vaccines, toxins, cultures of micro-organisms(excluding yeasts) and similar products; cell cultures, whether or not modified. (3002) --> Antisera, other blood fractions and immunological products, whether or not modified or obtained by means of biotechnological processes : (3002.1) --> Antisera and other blood fractions (3002.12) --> Other blood fractions (3002.12-3000)",
        "details": [
          {
            "hsCode": "3002",
            "name": "사람의 피, 치료용ㆍ예방용ㆍ진단용으로 조제한 동물의 피, 면역혈청ㆍ그 밖의 혈액 분획물과 면역물품(생물공학적 방법에 따라 변성되거나 얻어진 것인지에 상관없다), 백신ㆍ독소ㆍ미생물 배양체(효모는 제외한다)와 이와 유사한 물품, 세포 배양체(변성된 것인지에 상관없다)",
            "nameOrigin": "Human blood; animal blood prepared for therapeutic, prophylactic or diagnostic uses; antisera, other blood fractions and immunological products, whether or not modified or obtained by means of biotechnological processes; vaccines, toxins, cultures of micro-organisms(excluding yeasts) and similar products; cell cultures, whether or not modified."
          },
          {
            "hsCode": "30021",
            "name": "면역혈청, 그 밖의 혈액 분획물과 면역물품(생물공학적 방법에 따라 변성되거나 얻어진 것인지에 상관없다)",
            "nameOrigin": "Antisera, other blood fractions and immunological products, whether or not modified or obtained by means of biotechnological processes :"
          },
          {
            "hsCode": "300212",
            "name": "면역혈청과 그 밖의 혈액 분획물",
            "nameOrigin": "Antisera and other blood fractions"
          },
          {
            "hsCode": "3002123000",
            "name": "그 밖의 혈액 분획물",
            "nameOrigin": "Other blood fractions"
          }
        ]
      }
    ]
  }
}

Pricing

배송 조건 기준으로 예상 요금을 조회합니다.

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로 전달합니다.

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[]

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{}

예시 코드 및 샘플

같은 요청을 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"
      }
    ]
  }
}

Tariff

HSK 코드와 국가 코드 기준으로 관세율 정보를 조회합니다.

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

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

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{}

예시 코드 및 샘플

같은 요청을 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."
  }
}