상세 배송 현황 조회 API

배송 건의 접수 정보와 배송 상태 변경 이력을 조회합니다.

  • REST 인증 API로 발급받은 accessToken 쿠키가 필요합니다.
  • deliveryId를 query parameter로 전달합니다.
  • 본인 계정으로 접수한 배송만 조회할 수 있습니다.
  • 물품 정보는 deliveryItems 배열로 반환합니다.
  • deliveryProgressHistory는 배송 상태 변경 이력을 최신순으로 반환하며, 접수신청(deliveryStatus=1) 이력이 배열 마지막에 포함됩니다.

API Endpoint

GET/v1/rest/delivery/progress
Cookie Auth RequiredResponse: */*

API 한눈에 보기

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

Samples included

Request Fields

1

Required Fields

1

Response Fields

26

Available Code Samples

cURL / fetch / Response

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

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

구현 체크리스트 (Implementation Checklist)

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

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

운영 확인 항목

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

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

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

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하위 12개

REST 상세 배송 현황 조회 Response Data. 배송 접수 정보와 배송 상태 변경 이력을 반환합니다.

example{}

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

Response

/

data

data 하위 필드

12 fields

REST 상세 배송 현황 조회 Response Data. 배송 접수 정보와 배송 상태 변경 이력을 반환합니다.

OBJECT

deliveryNo

string

배송 접수 번호

exampleKR0200US

senderName

nullable
string

발신인

example홍길동

receiverName

nullable
string

수신인

exampleJohn Doe

departureCountryName

nullable
string

출발 국가 이름

example대한민국

departureCountryNameEn

nullable
string

출발 국가 영문 이름

exampleKorea

departureCountryAlpha2Code

nullable
string

출발 국가 2자리 코드

exampleKR

arrivalCountryName

nullable
string

도착 국가 이름

example미국

arrivalCountryNameEn

nullable
string

도착 국가 영문 이름

exampleUnited States of America

arrivalCountryAlpha2Code

nullable
string

도착 국가 2자리 코드

exampleUS

createdTime

nullable
string

date-time

접수일시

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

deliveryItems

ARRAY하위 8개

물품 정보 리스트

example[]

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

deliveryProgressHistory

ARRAY하위 2개

발송물 진행과정. 배송 상태 변경 이력을 최신순으로 반환하며, 접수신청(deliveryStatus=1) 이력이 배열 마지막에 포함됩니다.

example[]

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

Response

/

data.deliveryItems[]

deliveryItems[] 하위 필드

8 fields

물품 정보 리스트

ARRAY

info

nullable
string

품목

example화장품

packageType

nullable
string

포장 형태명

example박스

count

nullable
number

int32

물품 수량

example1

weight

nullable
number

무게(kg)

example15

width

nullable
number

가로(cm)

example11

depth

nullable
number

세로(cm)

example12

height

nullable
number

높이(cm)

example13

cbm

nullable
number

부피(CBM)

example0.125

Response

/

data.deliveryProgressHistory[]

deliveryProgressHistory[] 하위 필드

2 fields

발송물 진행과정. 배송 상태 변경 이력을 최신순으로 반환하며, 접수신청(deliveryStatus=1) 이력이 배열 마지막에 포함됩니다.

ARRAY

deliveryStatus

number

int32

배송 상태. 1: 접수신청, 2: 접수완료, 3: 출발국가 내륙운송, 4: 출발국가 출고지 도착, 5: 국가이동, 6: 도착국가 통관, 7: 도착국가 내륙운송, 8: 배송완료, 9: 배송취소, 10: 반송완료

example5

createdTime

nullable
string

date-time

상태 변경 일시

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

예시 코드 및 샘플

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

curl -X GET "$BASE_URL/v1/rest/delivery/progress?deliveryId=1" \
  -H "lang: ko" \
  -H "Cookie: accessToken=발급받은_토큰값"
const response = await fetch(`${BASE_URL}/v1/rest/delivery/progress`, {
  "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": {
    "deliveryNo": "KR0200US",
    "senderName": "홍길동",
    "receiverName": "John Doe",
    "departureCountryName": "대한민국",
    "departureCountryNameEn": "Korea",
    "departureCountryAlpha2Code": "KR",
    "arrivalCountryName": "미국",
    "arrivalCountryNameEn": "United States of America",
    "arrivalCountryAlpha2Code": "US",
    "createdTime": "2026-05-27T00:00:00+09:00",
    "deliveryItems": [
      {
        "info": "화장품",
        "packageType": "박스",
        "count": 1,
        "weight": 15,
        "width": 11,
        "depth": 12,
        "height": 13,
        "cbm": 0.125
      }
    ],
    "deliveryProgressHistory": [
      {
        "deliveryStatus": 5,
        "createdTime": "2026-05-27T00:00:00+09:00"
      }
    ]
  }
}