배송 접수 API

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

API Endpoint

POST/v1/rest/delivery
Cookie Auth RequiredRequest: application/jsonResponse: application/json

API 한눈에 보기

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

Samples included

Request Fields

53

Required Fields

29

Response Fields

6

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 헤더를 실제 운영 환경에서도 동일하게 전달합니다.

✓배송 접수 전 요금 조회 API를 먼저 호출하고 선택 옵션을 deliveryGlobal에 전달합니다.

✓연락처는 하이픈 없이 숫자만 전달하고, deliveryItems는 최소 1개 이상 포함합니다.

✓접수 성공 후 deliveryId 또는 접수번호를 저장해 중복 접수 여부와 후속 조회에 사용합니다.

운영 확인 항목

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

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

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

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

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

name

required
string

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

example홍길동

email

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

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

Request Body

/

deliveryItems[]

deliveryItems[] 하위 필드

18 fields

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

ARRAY

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

Request Body

/

departureDeliveryAddress

departureDeliveryAddress 하위 필드

11 fields

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

OBJECT

name

required
string

주소지 담당자 또는 수취/발송인 이름

example홍길동

phoneNum

required
string

주소지 담당자 연락처. 숫자만 입력하며 하이픈(-)은 제외합니다.

example01000000000

email

required
string

주소지 담당자 이메일

exampleasap@asapx.ai

postalCode

nullable
string

우편 번호. 국가별 형식 그대로 전달 가능하며, 모르는 경우 생략할 수 있습니다.

example00000

countryCode

required
string

ISO 3166-1 alpha-2 국가 코드. 예: KR, JP, US. 국가 마스터 기준으로 처리합니다.

exampleKR

stateOrProvince

required
string

시/도 또는 주. 국내는 시/도, 해외는 state/province 값을 전달합니다.

example서울

city

required
string

시/군/구 또는 도시명. 해외 주소는 city 값을 전달합니다.

example강남구

streetAddress

required
string

도로명 주소 또는 해외 street address. 위경도 보정 시 주요 검색 주소로 사용됩니다.

example샘플로 1

detailAddress

nullable
string

상세 주소. 건물명, 호수, 층수 등을 전달합니다.

example101호

longitude

nullable
number

경도. 프론트에서 확보한 좌표가 있으면 전달하고, 누락 시 백엔드에서 주소 기반 보정을 시도합니다.

example126.978

latitude

nullable
number

위도. 프론트에서 확보한 좌표가 있으면 전달하고, 누락 시 백엔드에서 주소 기반 보정을 시도합니다.

example37.5665

Request Body

/

arrivalDeliveryAddress

arrivalDeliveryAddress 하위 필드

11 fields

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

OBJECT

name

required
string

주소지 담당자 또는 수취/발송인 이름

example홍길동

phoneNum

required
string

주소지 담당자 연락처. 숫자만 입력하며 하이픈(-)은 제외합니다.

example01000000000

email

required
string

주소지 담당자 이메일

exampleasap@asapx.ai

postalCode

nullable
string

우편 번호. 국가별 형식 그대로 전달 가능하며, 모르는 경우 생략할 수 있습니다.

example00000

countryCode

required
string

ISO 3166-1 alpha-2 국가 코드. 예: KR, JP, US. 국가 마스터 기준으로 처리합니다.

exampleKR

stateOrProvince

required
string

시/도 또는 주. 국내는 시/도, 해외는 state/province 값을 전달합니다.

example서울

city

required
string

시/군/구 또는 도시명. 해외 주소는 city 값을 전달합니다.

example강남구

streetAddress

required
string

도로명 주소 또는 해외 street address. 위경도 보정 시 주요 검색 주소로 사용됩니다.

example샘플로 1

detailAddress

nullable
string

상세 주소. 건물명, 호수, 층수 등을 전달합니다.

example101호

longitude

nullable
number

경도. 프론트에서 확보한 좌표가 있으면 전달하고, 누락 시 백엔드에서 주소 기반 보정을 시도합니다.

example126.978

latitude

nullable
number

위도. 프론트에서 확보한 좌표가 있으면 전달하고, 누락 시 백엔드에서 주소 기반 보정을 시도합니다.

example37.5665

Request Body

/

deliveryGlobal

deliveryGlobal 하위 필드

2 fields

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

OBJECT

transportType

nullable
number

int32

요금 조회에서 선택한 options[].transportType 값. 1: 항공(퍼스트), 2: 항공(비즈니스-DHL), 3: 항공(이코노미-UPS), 4: 해운, 5: 항공(FEDEX), 6: 항공(EMS), 7: 항공(ASAP). 생략 시 기존 REST 기본값을 사용합니다.

example7

amount

required
number

요금 조회에서 선택한 options[].estimatedAmount 값

example25200

Response

4 fields1 nested

success

boolean

API 성공 여부

exampletrue

message

string

전달 메세지

exampleAPI가 정상 처리되었습니다

errorCode

number

int32

에러 코드

example0

data

OBJECT하위 2개

배송 접수 API Response Data

example{}

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

Response

/

data

data 하위 필드

2 fields

배송 접수 API Response Data

OBJECT

deliveryId

number

int64

배송 ID(인덱스)

example1

deliveryNo

string

배송 접수 번호

exampleASAP202607010001

예시 코드 및 샘플

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