국제 풀필먼트 개요

/v1/fulfillment/*는 화물이 HIOBuy 창고에 입고된 이후의 국제 물류를 다룹니다. 국내 구매는 대행 구매 주문을 보세요.

앱에 창고 풀필먼트가 필요합니다（포털 인가）. 자체 풀필먼트 앱은 403 FULFILLMENT_MODE_NOT_SUPPORTED를 받습니다.

금액 단위 {#monetary-unit}

금액이 있는 풀필먼트 경로의 표준 JSON 응답에는 최상위 monetary_unit: "CNY_minor"가 포함됩니다. 모든 { amount, currency }의 amount는 CNY fen입니다（1위안 = 100 fen）. 풀필먼트 응답 모델을 보세요.

API 가용성 {#availability}

경로	상태
`/v1/fulfillment/inbounds/create`	창고 모드에서 Live（창고 `simple-store`）；샌드박스는 mock
`/v1/fulfillment/packages`	창고 모드에서 Live（`packages/index`）；샌드박스는 mock
`/v1/fulfillment/packages/{package_id}`	창고 모드에서 Live（`packages/detail/{id}`）；샌드박스는 mock
`/v1/fulfillment/packages/{package_id}/tracking`	창고 모드에서 Live（`packages/logs/{id}`）；샌드박스는 mock
`/v1/fulfillment/unclaimed-packages`	창고 모드에서 Live（목록 + 수령）；샌드박스는 mock
`/v1/fulfillment/returns`	Mock — 반송 생성 / 목록 / 확인 / 취소
`/v1/fulfillment/locations`	창고 모드에서 Live（`warehouse`）；샌드박스는 mock
`/v1/fulfillment/value-added-services`	창고 모드에서 Live（`services`）；샌드박스는 mock
`/v1/fulfillment/service-requests`	Mock — 생성 / 목록 / 상세 / 확인
`/v1/fulfillment/shipments/{id}/intercept`	창고 모드에서 Live（`shipments/set-exceptional`）；샌드박스는 mock
`/v1/fulfillment/shipments`	창고 모드에서 Live（`shipments/index`）；샌드박스는 mock
`/v1/fulfillment/shipping/channels`	창고 모드에서 채널 카탈로그 Live；샌드박스는 mock
`/v1/fulfillment/shipping/quotes`	창고 모드에서 견적 Live；샌드박스는 mock
`/v1/fulfillment/shipments/*`	사용 가능（구성되면 창고 HTTP, 아니면 mock）
`/v1/fulfillment/balance`	사용 가능
`/v1/shipments`（레거시）	사용 중단

엔드투엔드 흐름 {#end-to-end-flow}

대행 구매 주문 생성 → 판매자가 창고로 발송
또는 이미 관리 중인 화물의 입고 예고
패키지 상세 / 추적 → 창고 측정 / 예외 / VAS / 풀필먼트 타임라인
또는 주문 상세 → 대행 구매 입고 후 tracking_numbers[]
배송 채널에서 기능을 확인한 뒤 운임 견적 → quotes[].channel.code 선택
출고 생성 → id / order_sn（PENDING）
창고 포장 및 최종 측정 → boxes[], 최종 무게 / 치수, 최종 운임
출고가 결제 가능（WAIT_PAYMENT）→ 상세를 보세요. 너무 이른 결제는 409 SHIPMENT_NOT_READY_FOR_PAYMENT
출고 결제 → 지갑에서 차감
목록 / 상세 → 경량 행, 또는 상자 / 포장 파일 / timeline / 퍼스트마일·라스트마일 번호
선택: 가로채기（WAIT_SHIP / SHIPPED를 보류할 때）
국제 추적 → 스캔 이벤트

창고 풀필먼트가 처음이신가요? WH-DEV 테스트 가이드로 창고 포장과 정산을 포함한 전체 흐름을 확인하세요.

WH-DEV 테스트 시작 →

엔드포인트 안내

주제	경로	문서
입고 예고	`POST .../inbounds/create`	입고 예고
패키지 상세 / 추적 / 미수령	`GET .../packages/*` · `unclaimed-packages`	패키지
반송	`POST/GET .../returns` · confirm/cancel	반송
로케이션	`GET .../locations`	로케이션
부가 서비스	`GET .../value-added-services`	VAS
서비스 요청	`POST/GET .../service-requests` · confirm	서비스 요청
배송 채널	`GET .../shipping/channels`	배송 채널
운임 견적	`POST .../shipping/quotes`	운임 견적
생성 / 결제 / 취소 / 가로채기	`POST .../shipments/create` · `{id}/pay` · `{id}/cancel` · `{id}/intercept`	출고
출고 목록	`GET .../shipments`	출고 · 목록
출고 상세	`GET .../shipments/{id}`	출고 · 상세
국제 추적	`GET .../shipments/{id}/tracking`	추적
지갑 잔액	`GET /v1/fulfillment/balance`	잔액
응답 필드	—	풀필먼트 응답 모델
상품 속성	`GET .../item-attributes`	운임 견적

창고 모드 구매

/v1/orders/* 경로는 그대로입니다. Gateway가 HIOBuy로 전달합니다. 상품 API는 계속 각 마켓플레이스를 직접 호출합니다.

국내 추적: 주문 물류 추적（창고 모드에서는 Gateway가 프록시）.

수명 주기 상태도 {#lifecycle}

상태 흐름은 패키지, 출고, 반송을 보세요.

오류

FULFILLMENT_MODE_NOT_SUPPORTED, SHIPMENT_CREATE_EXCEPTION, SHIPMENT_CREATE_FAILED, PARCEL_NOT_FOUND, EXTERNAL_ORDER_ID_ALREADY_EXISTS, SHIPMENT_NOT_READY_FOR_PAYMENT, SHIPMENT_ALREADY_PAID, INSUFFICIENT_BALANCE, NOT_FOUND（SHIPMENT_NOT_EXISTS）, 가로채기 코드（SHIPMENT_NOT_FOUND, SHIPMENT_NOT_INTERCEPTABLE, SHIPMENT_INTERCEPTION_ALREADY_REQUESTED）— 오류와 출고를 보세요.

Get Support

Need integration help? Contact Developer Support at support@hiobuy.com · Response within 1–2 business days

Email support