배송 채널 API

GET /v1/fulfillment/shipping/channels는 앱에 연결된 창고를 통해 이용할 수 있는 활성·요금 설정 완료 국제 배송 채널을 목록으로 반환합니다.

채널 선택기를 만들거나 지원 기능을 확인할 때 사용합니다. 목적지별 가능 여부와 금액은 운임 견적을 호출하세요. 여기의 요율표는 과금 모델을 설명할 뿐이며 가격을 확정하지 않습니다.

GEThttps://open.hiobuy.com/v1/fulfillment/shipping/channels

창고 풀필먼트가 필요합니다. hio_test_* 키의 샌드박스 앱은 결정적 모의 데이터를 받습니다.

견적은 예산이지 확정 가격이 아닙니다. 창고 계량, 부피 측정, 재포장, 서비스 검토에 따라 최종 금액이 바뀔 수 있습니다.

금액과 단위 {#units}

금액 amount 값은 모두 정수 CNY fen(보조 단위)입니다. 1000은 ¥10.00을 의미합니다.
최상위 monetary_unit은 항상 CNY_minor입니다.
금액 객체 형식:

{
  "amount": 1000,
  "currency": "CNY"
}

KG = 킬로그램, CM = 센티미터, M3 = 세제곱미터, KG_PER_M3 = 세제곱미터당 킬로그램.
채널, 권역, 서비스는 name이 아니라 안정적인 code로 식별하세요.
Public API는 창고 데이터베이스 ID, 개발자 코드, 공급업체 URL을 노출하지 않습니다.

요청 {#request}

GET /v1/fulfillment/shipping/channels?country_code=US&include=regions,services,rate_cards&page=1&page_size=20
Authorization: Bearer hio_live_xxx
Language: en

표시 언어는 Language 헤더만 사용합니다. 지원 값: en(기본값), en-US, zh, zh-CN, zh-TW, cn, hk. 쿼리 문자열이나 JSON 본문에 language를 넣지 마세요.

쿼리 파라미터

파라미터	필수	기본값	설명
`channel_code`	아니요	—	안정적인 채널 코드 정확 일치(최대 64자)
`country_code`	아니요	—	ISO 3166-1 alpha-2 목적지 국가
`include`	아니요	—	쉼표로 구분한 확장: `regions`, `services`, `rate_cards`
`page`	아니요	`1`	페이지 번호. 1부터 시작
`page_size`	아니요	`20`	페이지당 항목 수. 최대 50

`include` 확장

include를 생략하면 경량 채널 요약이 됩니다.

`include` 값	응답 필드	사용 시점
`regions`	`regions`	커버리지, 매칭 유형, 참고 운송 소요 시간
`services`	`value_added_services`	견적용 채널 부가 서비스
`rate_cards`	`rate_cards`	과금 모델을 설명하는 참고 요금 행

값을 조합할 수 있습니다. 예: include=regions,services,rate_cards. 알 수 없는 값은 400 VALIDATION_ERROR를 반환합니다.

rate_cards는 reference_only입니다. POST /v1/fulfillment/shipping/quotes를 대체해서는 안 됩니다. 창고에 요금 행을 요청하는 것은 include=rate_cards일 때만입니다.

활성화되어 있고 동시에 유효한 요금 설정이 있는 채널만 반환됩니다. 빈 items 배열은 현재 필터에 맞는 카탈로그 채널이 없음을 의미합니다.

응답 {#response}

{
  "items": [
    {
      "code": "US-SEA",
      "name": "US Ocean",
      "description": "General cargo line",
      "status": "ACTIVE",
      "tags": [
        "GREAT_VALUE"
      ],
      "warehouse": {
        "code": "SZ",
        "name": "Shenzhen Warehouse"
      },
      "capabilities": {
        "delivery_methods": [
          "DOOR_DELIVERY"
        ],
        "multi_package_supported": true,
        "tracking_supported": true,
        "shipping_label_supported": false
      },
      "requirements": {
        "weight": "REQUIRED",
        "dimensions": "CONDITIONAL",
        "postal_code": "OPTIONAL",
        "declared_value": "OPTIONAL",
        "customs_code": "OPTIONAL",
        "personal_customs_code": "OPTIONAL",
        "recipient_identity": "OPTIONAL"
      },
      "attribute_matching": {
        "mode": "ANY_OF",
        "accepted_attributes": [
          {
            "code": "GENERAL",
            "name": "General cargo"
          }
        ]
      },
      "billing": {
        "basis": "WEIGHT",
        "calculation_model": "FIRST_NEXT_WEIGHT",
        "quantity_unit": "KG",
        "supported_range": {
          "minimum": {
            "value": 0.5,
            "unit": "KG"
          },
          "maximum": {
            "value": 30,
            "unit": "KG"
          },
          "out_of_range_behavior": "UNAVAILABLE"
        },
        "minimum": {
          "value": 0.5,
          "unit": "KG",
          "ceil_to_minimum": true
        },
        "rounding": {
          "single_package_step": {
            "value": 0.5,
            "unit": "KG"
          },
          "multi_package_step": {
            "value": 0.5,
            "unit": "KG"
          },
          "ignore_below": {
            "value": 0.05,
            "unit": "KG"
          }
        },
        "multi_package": {
          "mode": "PER_BOX",
          "calculation_scope": "PER_PACKAGE",
          "aggregation": "SUM_PACKAGE_CHARGES",
          "minimum_per_package": {
            "value": 0.5,
            "unit": "KG"
          },
          "minimum_total": {
            "value": 0,
            "unit": "KG"
          }
        },
        "volumetric_weight": {
          "enabled": true,
          "divisor": 6000,
          "average_with_actual": false,
          "exemption": null
        },
        "overweight_warning": {
          "enabled": false,
          "threshold": {
            "value": 0,
            "unit": "KG"
          },
          "notice": null
        }
      },
      "rule_summary": {
        "fee_aggregation": "SUM_ALL",
        "maximum_charge": {
          "amount": 0,
          "currency": "CNY"
        },
        "has_surcharges": true,
        "has_order_restrictions": false,
        "has_dispatch_restrictions": true,
        "evaluated_by_quote": true
      },
      "regions": [
        {
          "code": "US-WEST",
          "name": "US West",
          "status": "ACTIVE",
          "match_type": "COUNTRY_REGION",
          "countries": [
            "US"
          ],
          "postal_code_required": false,
          "reference_transit_time": {
            "text": "15-18 business days",
            "min_business_days": 15,
            "max_business_days": 18
          },
          "areas": []
        }
      ],
      "value_added_services": [
        {
          "code": "LINE_FUEL",
          "name": "Fuel surcharge",
          "request_mode": "MANDATORY",
          "pricing_type": "CALCULATED",
          "pricing_scope": "REGION",
          "pricing_basis": "BASE_FREIGHT_PERCENT",
          "region_prices": [
            {
              "region_code": "US-WEST",
              "value": 500,
              "value_unit": "BASIS_POINT",
              "fixed_charge": {
                "amount": 200,
                "currency": "CNY"
              }
            }
          ],
          "final_quote_required": true,
          "may_be_adjusted": true
        }
      ],
      "rate_cards": [
        {
          "region_code": "US-WEST",
          "billing_basis": "WEIGHT",
          "calculation_model": "FIRST_NEXT_WEIGHT",
          "quantity_unit": "KG",
          "currency": "CNY",
          "reference_only": true,
          "price_rows": [
            {
              "type": "FIRST_WEIGHT",
              "pricing_basis": "WEIGHT",
              "range": {
                "minimum": 0.5,
                "maximum": 0.5,
                "unit": "KG",
                "minimum_inclusive": true,
                "maximum_inclusive": false
              },
              "first_quantity": {
                "value": 0,
                "unit": "KG"
              },
              "step": {
                "value": 0,
                "unit": "KG"
              },
              "charge": {
                "amount": 8000,
                "currency": "CNY"
              }
            }
          ]
        }
      ],
      "service_policy": {
        "warehouse_may_add_services": true,
        "warehouse_may_remove_services": true,
        "prices_may_change_after_inspection": true
      },
      "final_quote_required": true,
      "config_updated_at": "2026-09-07T08:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "page_size": 20,
    "total": 1,
    "has_more": false
  },
  "monetary_unit": "CNY_minor",
  "generated_at": "2026-09-07T09:00:00Z",
  "request_id": "req_xxx"
}

regions, value_added_services, rate_cards는 일치하는 include 값을 보낸 경우에만 나타납니다.

응답 필드 {#fields}

필드	설명
`items[]`	일치하는 채널. 필터에 맞는 카탈로그 채널이 없으면 비어 있습니다.
`items[].code`	안정적인 채널 코드. 견적의 `channel_codes`와 출고 생성에 사용합니다.
`items[].name`	현지화된 표시 이름(`Language` 헤더).
`items[].description`	현지화된 설명.
`items[].status`	카탈로그 상태. 반환되는 채널은 `ACTIVE`입니다.
`items[].tags`	`GREAT_VALUE` 같은 안정 태그.
`items[].warehouse`	연결된 창고 `{ code, name }`. 데이터베이스 ID가 아닙니다.
`items[].capabilities`	배송 방식, 복수 포장, 추적, 라벨 지원.
`items[].requirements`	입력 완비 힌트: `REQUIRED` · `OPTIONAL` · `CONDITIONAL` · `NOT_SUPPORTED`.
`items[].attribute_matching`	`ANY_OF` 또는 `ALL_REQUIRED`와 `accepted_attributes[].code`.
`items[].billing`	채널이 화물을 과금하는 방식. 아래를 참고하세요.
`items[].rule_summary`	추가요금이나 제한 존재 여부. 규칙은 견적에서 평가됩니다.
`items[].regions`	`include=regions`일 때 존재합니다.
`items[].value_added_services`	`include=services`일 때 존재합니다.
`items[].rate_cards`	`include=rate_cards`일 때 존재합니다. 항상 `reference_only`입니다.
`items[].service_policy`	창고가 검수 후 서비스를 추가·제거하고 가격을 변경할 수 있습니다.
`items[].final_quote_required`	출고별 견적이 아직 필요하면 `true`.
`items[].config_updated_at`	이 채널의 카탈로그 개정 시각.
`pagination`	`page`, `page_size`, `total`, `has_more`.
`monetary_unit`	항상 `CNY_minor`.
`generated_at`	응답 시각(ISO 8601).
`request_id`	`x-request-id`와 대조합니다.

과금 {#billing}

필드	의미
`basis`	`WEIGHT`, `VOLUME`, 또는 `DENSITY`
`calculation_model`	요금 행이 사용하는 과금 모델
`quantity_unit`	`KG`, `M3`, 또는 `KG_PER_M3`
`supported_range`	과금 가능 수량의 최소·최대
`supported_range.out_of_range_behavior`	`UNAVAILABLE` — 범위 밖 화물은 이 채널로 운송할 수 없습니다. 외삽하지 마세요.
`minimum`	최소 과금 수량과 그보다 작은 값을 올림할지(`ceil_to_minimum`)
`rounding`	단일 포장 및 복수 포장 반올림 단계
`volumetric_weight`	부피 중량 제수와 면제 규칙
`multi_package`	포장 단위 과금 vs 합산 과금 및 집계
`overweight_warning`	선택적 과중량 안내

과금 모델에는 FIRST_NEXT_WEIGHT, TIERED_PRICE, UNIT_PRICE_PLUS_GRADE, MULTI_LEVEL_NEXT_WEIGHT, RANGE_FIRST_NEXT_WEIGHT가 포함될 수 있습니다. 이 행으로 창고 요금 엔진을 재구현하지 마세요.

권역 {#regions}

필드	의미
`code` / `name`	안정적인 권역 코드와 현지화 이름
`match_type`	`COUNTRY_REGION` 또는 `POSTAL_CODE`
`countries`	이 권역이 커버하는 ISO 국가 코드
`postal_code_required`	`true`이면 견적에 `postal_code`를 보내세요
`reference_transit_time`	표시 텍스트와 선택적 최소·최대 영업일
`areas`	선택적 세부 지역 목록. 카탈로그는 전체 우편 규칙 데이터베이스를 노출하지 않습니다.

부가 서비스 {#value-added-services}

운임 견적의 services.channel[]에는 value_added_services[].code를 사용합니다.

필드	의미
`code`	안정적인 서비스 코드
`request_mode`	`MANDATORY`(항상 적용) 또는 `OPTIONAL`(개발자 선택)
`pricing_type`	정액 vs 산출(예: `CALCULATED`)
`pricing_scope`	가격 적용 범위(예: `REGION`)
`pricing_basis`	요금 계산 방식

BASIS_POINT는 퍼센트 베이시스 포인트입니다. 500은 5%를 의미합니다. 처리 중 창고가 서비스를 추가·제거·조정할 수 있습니다 — service_policy와 may_be_adjusted를 참고하세요.

요율표 {#rate-cards}

필드	의미
`region_code`	이 요율표가 속한 권역
`billing_basis`	`billing.basis`와 같은 어휘
`calculation_model`	`billing.calculation_model`과 같은 어휘
`quantity_unit`	`KG`, `M3`, 또는 `KG_PER_M3`
`price_rows`	모델을 설명하는 참고 구간
`reference_only`	항상 `true` — 실시간 견적이 아님

캐싱 {#caching}

config_updated_at은 채널 상세, 권역, 요율표, 규칙, 서비스가 바뀌면 갱신됩니다. 경량 카탈로그는 짧게 캐시하고, 이 타임스탬프가 바뀌면 확장을 다시 가져오며, 출고 생성 전에는 항상 운임 견적을 호출하세요. 확정된 요금 버전은 없습니다.

오류 {#errors}

채널별 이용 불가는 HTTP 오류가 아닙니다. 빈 items 배열은 카탈로그 미일치의 성공 응답입니다.

HTTP	`error.code`	발생 시점
400	`VALIDATION_ERROR`	페이지네이션, 국가 구문, 또는 `include` 값이 잘못됨
401	`INVALID_API_KEY`	Bearer 토큰이 없거나 유효하지 않음
400	`INVALID_SHIPPING_CHANNEL`	알 수 없는 채널을 지정하는 견적/출고 호출용으로 예약됨. 이 목록은 빈 `items` 배열만 반환합니다.
403	`FULFILLMENT_MODE_NOT_SUPPORTED`	앱이 자체 풀필먼트
403	`WAREHOUSE_AUTH_INVALID`	창고 인가가 없거나 거부되었거나 만료됨
422	`INVALID_COUNTRY_CODE`	목적지 국가가 유효하지 않거나 미지원
502	`WAREHOUSE_UPSTREAM_ERROR`	창고 서비스 실패. 백오프로 재시도

공개용 독립 코드 AUTHENTICATION_ERROR, WAREHOUSE_AUTH_REQUIRED, WAREHOUSE_SERVICE_UNAVAILABLE은 없습니다. 인증 실패는 401 INVALID_API_KEY, 창고 미바인딩은 403 WAREHOUSE_AUTH_INVALID, 창고 장애는 502 WAREHOUSE_UPSTREAM_ERROR입니다.

오류와 인증을 참고하세요.

예제 {#examples}

경량 카탈로그:

curl "https://api.hiobuy.com/v1/fulfillment/shipping/channels?page=1&page_size=20" \
  -H "Authorization: Bearer hio_live_xxx" \
  -H "Language: en"

미국으로 배송할 수 있는 채널(참고 요금 포함):

curl "https://api.hiobuy.com/v1/fulfillment/shipping/channels?country_code=US&include=regions,services,rate_cards" \
  -H "Authorization: Bearer hio_live_xxx" \
  -H "Language: zh-CN"

다음: 목적지별 운임 견적 요청.

Get Support

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

Email support