API kênh vận chuyển

GET /v1/fulfillment/shipping/channels liệt kê các kênh vận chuyển quốc tế đang hoạt động và đã cấu hình giá, khả dụng qua kho được gắn với app của bạn.

Dùng endpoint này để dựng bộ chọn kênh hoặc kiểm tra khả năng. Để biết khả dụng và số tiền theo điểm đến, gọi Báo giá vận chuyển. Bảng giá ở đây chỉ giải thích mô hình tính cước — chúng không bao giờ khóa giá.

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

Yêu cầu fulfillment kho. App sandbox với khóa hio_test_* nhận dữ liệu mock xác định.

Báo giá là ngân sách, không phải giá đã khóa. Cân nặng tại kho, đo thể tích, đóng gói lại và rà soát dịch vụ có thể thay đổi số tiền cuối cùng.

Tiền tệ và đơn vị {#units}

Mọi giá trị tiền amount đều là số nguyên fen CNY (đơn vị nhỏ). 1000 nghĩa là ¥10.00.
monetary_unit cấp cao nhất luôn là CNY_minor.
Đối tượng tiền dùng:

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

KG = kilogram, CM = centimeter, M3 = mét khối, KG_PER_M3 = kilogram trên mét khối.
Nhận diện kênh, khu vực và dịch vụ bằng code ổn định, không dùng name.
Public API không lộ ID cơ sở dữ liệu kho, mã developer, hay URL nhà cung cấp.

Yêu cầu {#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

Ngôn ngữ hiển thị chỉ qua header Language. Giá trị hỗ trợ: en (mặc định), en-US, zh, zh-CN, zh-TW, cn, hk. Không đặt language trong query string hoặc JSON body.

Tham số query

Tham số	Bắt buộc	Mặc định	Mô tả
`channel_code`	Không	—	Mã kênh ổn định chính xác (tối đa 64 ký tự)
`country_code`	Không	—	Quốc gia đích ISO 3166-1 alpha-2
`include`	Không	—	Mở rộng, phân tách bằng dấu phẩy: `regions`, `services`, `rate_cards`
`page`	Không	`1`	Số trang, bắt đầu từ 1
`page_size`	Không	`20`	Số mục mỗi trang; tối đa 50

Mở rộng `include`

Bỏ include để nhận tóm tắt kênh nhẹ.

Giá trị `include`	Trường phản hồi	Dùng khi
`regions`	`regions`	Phủ sóng, kiểu khớp và thời gian vận chuyển tham chiếu
`services`	`value_added_services`	Dịch vụ giá trị gia tăng của kênh cho báo giá
`rate_cards`	`rate_cards`	Hàng giá tham chiếu giải thích mô hình tính cước

Bạn có thể kết hợp giá trị, ví dụ include=regions,services,rate_cards. Giá trị không xác định trả về 400 VALIDATION_ERROR.

rate_cards là reference_only. Chúng không được thay thế POST /v1/fulfillment/shipping/quotes. Chỉ include=rate_cards mới yêu cầu kho trả hàng giá.

Chỉ các kênh được bật và có cấu hình giá hợp lệ mới được trả về. Mảng items rỗng nghĩa là không có kênh catalog nào khớp bộ lọc hiện tại.

Phản hồi {#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 và rate_cards chỉ xuất hiện khi gửi giá trị include tương ứng.

Trường phản hồi {#fields}

Trường	Mô tả
`items[]`	Các kênh khớp. Rỗng khi không có kênh catalog nào khớp bộ lọc.
`items[].code`	Mã kênh ổn định. Dùng trong `channel_codes` của báo giá và khi tạo lô hàng.
`items[].name`	Tên hiển thị đã bản địa hóa (header `Language`).
`items[].description`	Mô tả đã bản địa hóa.
`items[].status`	Trạng thái catalog. Các kênh được trả về là `ACTIVE`.
`items[].tags`	Thẻ ổn định như `GREAT_VALUE`.
`items[].warehouse`	Kho gắn kết `{ code, name }`. Không phải ID cơ sở dữ liệu.
`items[].capabilities`	Phương thức giao, nhiều kiện, tracking và hỗ trợ nhãn.
`items[].requirements`	Gợi ý đầy đủ đầu vào: `REQUIRED` · `OPTIONAL` · `CONDITIONAL` · `NOT_SUPPORTED`.
`items[].attribute_matching`	`ANY_OF` hoặc `ALL_REQUIRED` cùng `accepted_attributes[].code`.
`items[].billing`	Cách kênh tính giá một lô hàng. Xem bên dưới.
`items[].rule_summary`	Có phụ phí hoặc hạn chế hay không; báo giá đánh giá các quy tắc.
`items[].regions`	Có khi `include=regions`.
`items[].value_added_services`	Có khi `include=services`.
`items[].rate_cards`	Có khi `include=rate_cards`. Luôn `reference_only`.
`items[].service_policy`	Kho có thể thêm/gỡ dịch vụ và đổi giá sau khi kiểm tra.
`items[].final_quote_required`	`true` khi vẫn cần báo giá theo từng lô hàng.
`items[].config_updated_at`	Thời điểm revision catalog của kênh này.
`pagination`	`page`, `page_size`, `total`, `has_more`.
`monetary_unit`	Luôn là `CNY_minor`.
`generated_at`	Dấu thời gian phản hồi (ISO 8601).
`request_id`	Đối chiếu với `x-request-id`.

Tính cước {#billing}

Trường	Ý nghĩa
`basis`	`WEIGHT`, `VOLUME`, hoặc `DENSITY`
`calculation_model`	Mô hình giá dùng bởi các hàng bảng giá
`quantity_unit`	`KG`, `M3`, hoặc `KG_PER_M3`
`supported_range`	Số lượng tính cước tối thiểu và tối đa
`supported_range.out_of_range_behavior`	`UNAVAILABLE` — kênh không thể nhận kiện ngoài khoảng. Không ngoại suy.
`minimum`	Số lượng tính cước tối thiểu và liệu giá trị nhỏ hơn có được làm tròn lên (`ceil_to_minimum`)
`rounding`	Bước làm tròn cho một kiện và nhiều kiện
`volumetric_weight`	Hệ số thể tích và quy tắc miễn trừ
`multi_package`	Tính cước theo kiện so với gộp, và cách cộng
`overweight_warning`	Thông báo quá nặng tùy chọn

Mô hình tính toán có thể gồm FIRST_NEXT_WEIGHT, TIERED_PRICE, UNIT_PRICE_PLUS_GRADE, MULTI_LEVEL_NEXT_WEIGHT và RANGE_FIRST_NEXT_WEIGHT. Không tự triển khai lại engine giá của kho từ các hàng này.

Khu vực {#regions}

Trường	Ý nghĩa
`code` / `name`	Mã khu vực ổn định và tên đã bản địa hóa
`match_type`	`COUNTRY_REGION` hoặc `POSTAL_CODE`
`countries`	Mã quốc gia ISO được khu vực này phủ
`postal_code_required`	Khi `true`, gửi `postal_code` tới báo giá
`reference_transit_time`	Văn bản hiển thị kèm min/max ngày làm việc tùy chọn
`areas`	Danh sách khu nhỏ hơn tùy chọn. Catalog không lộ toàn bộ cơ sở dữ liệu quy tắc bưu chính.

Dịch vụ giá trị gia tăng {#value-added-services}

Dùng value_added_services[].code trong services.channel[] trên Báo giá vận chuyển.

Trường	Ý nghĩa
`code`	Mã dịch vụ ổn định
`request_mode`	`MANDATORY` (luôn áp dụng) hoặc `OPTIONAL` (developer chọn)
`pricing_type`	Giá cố định so với tính toán (ví dụ `CALCULATED`)
`pricing_scope`	Nơi giá áp dụng (ví dụ `REGION`)
`pricing_basis`	Cách tính khoản phí

BASIS_POINT là điểm phần trăm: 500 nghĩa là 5%. Kho có thể thêm, gỡ hoặc điều chỉnh dịch vụ trong quá trình xử lý — xem service_policy và may_be_adjusted.

Bảng giá {#rate-cards}

Trường	Ý nghĩa
`region_code`	Khu vực mà bảng giá thuộc về
`billing_basis`	Cùng từ vựng với `billing.basis`
`calculation_model`	Cùng từ vựng với `billing.calculation_model`
`quantity_unit`	`KG`, `M3`, hoặc `KG_PER_M3`
`price_rows`	Các bậc tham chiếu dùng để giải thích mô hình
`reference_only`	Luôn `true` — không phải báo giá trực tiếp

Bộ nhớ đệm {#caching}

config_updated_at thay đổi khi chi tiết kênh, khu vực, bảng giá, quy tắc hoặc dịch vụ thay đổi. Cache catalog nhẹ trong thời gian ngắn, lấy lại các mở rộng khi timestamp này đổi, và luôn gọi Báo giá vận chuyển trước khi tạo lô hàng. Không có phiên bản giá bị khóa.

Lỗi {#errors}

Kênh không đủ điều kiện không phải lỗi HTTP. Mảng items rỗng là catalog miss thành công.

HTTP	`error.code`	Khi nào
400	`VALIDATION_ERROR`	Phân trang, cú pháp quốc gia, hoặc giá trị `include` không hợp lệ
401	`INVALID_API_KEY`	Thiếu hoặc Bearer token không hợp lệ
400	`INVALID_SHIPPING_CHANNEL`	Dành cho cuộc gọi báo giá/lô hàng nêu kênh không xác định. Danh sách này chỉ trả mảng `items` rỗng.
403	`FULFILLMENT_MODE_NOT_SUPPORTED`	App dùng self fulfillment
403	`WAREHOUSE_AUTH_INVALID`	Ủy quyền kho thiếu, bị từ chối hoặc hết hạn
422	`INVALID_COUNTRY_CODE`	Quốc gia đích không hợp lệ hoặc không được hỗ trợ
502	`WAREHOUSE_UPSTREAM_ERROR`	Dịch vụ kho thất bại; thử lại với backoff

Không có mã công khai riêng AUTHENTICATION_ERROR, WAREHOUSE_AUTH_REQUIRED hay WAREHOUSE_SERVICE_UNAVAILABLE. Lỗi xác thực dùng 401 INVALID_API_KEY; thiếu bind kho dùng 403 WAREHOUSE_AUTH_INVALID; sự cố kho dùng 502 WAREHOUSE_UPSTREAM_ERROR.

Xem Lỗi và Xác thực.

Ví dụ {#examples}

Catalog nhẹ:

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

Các kênh có thể phục vụ Hoa Kỳ, gồm giá tham chiếu:

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"

Tiếp theo: yêu cầu báo giá vận chuyển theo điểm đến.

Get Support

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

Email support