배송 수정 API

REST 배송 수정 API입니다.

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

API Endpoint

PATCH/v1/rest/delivery
Cookie Auth RequiredRequest: application/jsonResponse: */*

API 한눈에 보기

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

Samples included

Request Fields

54

Required Fields

1

Response Fields

5

Available Code Samples

cURL / fetch / Request / Response

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

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

구현 체크리스트 (Implementation Checklist)

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

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

✓수정은 접수 신청 상태에서만 가능하므로, 실패 시 상세 조회로 현재 상태를 확인합니다.

운영 확인 항목

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

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

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

Request Body

13 fields1 required4 nested

deliveryId

required
number

int64

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

example1

deliveryType

nullable
number

int32

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

example1

name

nullable
string

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

example홍길동

email

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

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

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

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

Request Body

/

deliveryItems[]

deliveryItems[] 하위 필드

18 fields

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

ARRAY

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

Request Body

/

departureDeliveryAddress

departureDeliveryAddress 하위 필드

11 fields

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

OBJECT

name

nullable
string

주소지 담당자 또는 수취/발송인 이름. 생략 시 기존 값을 유지합니다.

example홍길동

phoneNum

nullable
string

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

example01000000000

email

nullable
string

주소지 담당자 이메일. 생략 시 기존 값을 유지합니다.

exampleasap@asapx.ai

postalCode

nullable
string

우편 번호. 생략 시 기존 값을 유지합니다.

example00000

countryCode

nullable
string

ISO 3166-1 alpha-2 국가 코드. 예: KR, JP, US. 생략 시 기존 국가를 유지합니다.

exampleKR

stateOrProvince

nullable
string

시/도 또는 주. 생략 시 기존 값을 유지합니다.

example서울

city

nullable
string

시/군/구 또는 도시명. 생략 시 기존 값을 유지합니다.

example강남구

streetAddress

nullable
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. 전달한 필드만 수정 대상이며, 국가 코드가 전달되면 국가 마스터 기준으로 처리합니다.

OBJECT

name

nullable
string

주소지 담당자 또는 수취/발송인 이름. 생략 시 기존 값을 유지합니다.

example홍길동

phoneNum

nullable
string

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

example01000000000

email

nullable
string

주소지 담당자 이메일. 생략 시 기존 값을 유지합니다.

exampleasap@asapx.ai

postalCode

nullable
string

우편 번호. 생략 시 기존 값을 유지합니다.

example00000

countryCode

nullable
string

ISO 3166-1 alpha-2 국가 코드. 예: KR, JP, US. 생략 시 기존 국가를 유지합니다.

exampleKR

stateOrProvince

nullable
string

시/도 또는 주. 생략 시 기존 값을 유지합니다.

example서울

city

nullable
string

시/군/구 또는 도시명. 생략 시 기존 값을 유지합니다.

example강남구

streetAddress

nullable
string

도로명 주소 또는 해외 street address. 생략 시 기존 값을 유지합니다.

example샘플로 1

detailAddress

nullable
string

상세 주소. 생략 시 기존 값을 유지합니다.

example101호

longitude

nullable
number

경도. 수정 요청에서는 전달한 좌표를 그대로 반영하며, 생략 시 기존 값을 유지합니다.

example126.978

latitude

nullable
number

위도. 수정 요청에서는 전달한 좌표를 그대로 반영하며, 생략 시 기존 값을 유지합니다.

example37.5665

Request Body

/

deliveryGlobal

deliveryGlobal 하위 필드

1 fields

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

OBJECT

transportType

number

int32

국제 운송 수단. 1: 항공(퍼스트), 2: 항공(비즈니스-DHL), 3: 항공(이코노미-UPS), 4: 해운, 5: 항공(FEDEX), 6: 항공(EMS), 7: 항공(ASAP). 생략 시 기존 값을 유지합니다.

example1

Response

4 fields1 nested

success

boolean

API 성공 여부

exampletrue

message

string

전달 메세지

exampleAPI가 정상 처리되었습니다

errorCode

number

int32

에러 코드

example0

data

OBJECT하위 1개

배송 수정 API Response Data

example{}

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

Response

/

data

data 하위 필드

1 fields

배송 수정 API Response Data

OBJECT

deliveryId

number

int64

배송 ID(인덱스)

example1

예시 코드 및 샘플

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