주문에 딸린 발주(배송) 단위로 운송장·택배사·배송추적 상태와 추적 이력을 조회합니다.
발송처리로 운송장을 넣으면 그 뒤 택배사가 알려주는 단계는 Bootpay가 자동으로 모읍니다. 서비스 서버는 택배사를 직접 조회할 필요 없이 이 API만 읽으면 됩니다.
Basic 인증과 user:order_detail scope가 필요합니다. 구매자 화면에서는 Bootpay-User-JWT 또는 secretKey 인증의 user_id를 지정하면 그 회원의 주문만 조회합니다. 필드와 오류 전체는 주문 API 원문를 확인합니다.
API 엔드포인트
주문 상세로도 같은 값을 볼 수 있습니다
주문 상세 응답의 order_purchases[]가 같은 데이터입니다. 배송만 확인할 때 결제·상품·고객 정보까지 받지 않도록 이 면만 떼어 둔 것입니다.
요청 파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
order_number |
String | 필수 | 주문번호 (URL 경로) |
코드 예제
curl -X GET "https://api.bootapi.com/v1/orders/25071182085082524116/purchases" \
-H "Authorization: Basic {base64(client_key:secret_key)}"bashconst { BootpayCommerce } = require('@bootpay/backend-js')
const commerce = new BootpayCommerce({
client_key: 'your-commerce-client-key',
secret_key: 'your-commerce-secret-key',
mode: 'production'
})
const response = await commerce.get('orders/25071182085082524116/purchases')
console.log(response)javascriptNode.js 배포 버전의 전송 메서드
@bootpay/backend-js@2.13.1에는 order.purchases가 없습니다. 위처럼 SDK 공통 get에 주문번호가 포함된 상대 경로를 전달합니다. 다른 언어는 해당 버전의 메서드를 확인하거나 위 HTTP 계약을 사용합니다.
응답
성공 응답
[
{
"order_purchase_id": "6870824fb0eacea5cd974f12",
"order_purchase_number": "P25071182085082524116",
"status": 4,
"delivery_company_code": "CJGLS",
"tracking_number": "620148310301",
"d_ts": 3,
"sent_at": "2025-07-12T09:10:00Z",
"tracking_histories": [
{
"trakler_status": "in_transit",
"delivery_tracking_status": 3,
"location": "옥천HUB",
"description": "간선상차 · CJ대한통운",
"occurred_at": "2025-07-12T21:40:00Z",
"source": "webhook"
}
]
}
]json필드 설명은 주문 상세와 같습니다.
배송이 없는 주문이면 빈 배열입니다
디지털 상품처럼 이행 단계가 없는 주문은 발주가 만들어지지 않습니다.
추적 단계 읽는 법
d_ts는 택배사가 알려준 단계입니다. 값은 커머스 Enum에서 확인합니다.
| 상황 | 보이는 값 |
|---|---|
| 운송장 등록 전 | d_ts: 0, tracking_histories: [] |
| 등록 직후 | d_ts: 1, 이력은 아직 비어 있습니다 |
| 집화·이동 중 | d_ts: 3, 이력이 최신 순으로 쌓입니다 |
| 배송 완료 | d_ts: 4, 발주 status도 5로 함께 넘어갑니다 |
폴링 주기는 넉넉하게 잡습니다
택배사 단계는 하루에 몇 번 바뀌는 정보입니다. 분 단위로 조회할 이유가 없습니다.
에러 코드
공통 에러
인증·권한 관련 에러는 에러 코드표를 참고합니다.
| 코드 | 메시지 | 대처 방법 |
|---|---|---|
ORDER_ |
주문내역을 찾지 못했습니다. | order_number를 넣었는지 확인합니다 (order_id 아님) |
ORDER_ |
주문 정보를 조회할 권한이 없습니다. | 다른 프로젝트의 주문번호는 아닌지 확인합니다 |



