API báo giá vận chuyển

POST /v1/fulfillment/shipping/quotes ước tính vận chuyển quốc tế từ điểm đến, cân nặng, kích thước, thuộc tính hàng và dịch vụ.

Dùng cú pháp tắt một kiện khi chưa biết cách kho tách thùng. Dùng packages[] khi đã biết số kiện và số đo từng kiện.

Endpoint này dùng cùng thuật ngữ kênh, khu vực, dịch vụ, tính cước và tiền tệ với API kênh vận chuyển.

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. Báo giá COMPLETE vẫn không phải khóa giá.

Bí danh tương thích: POST /v1/fulfillment/shipments/freight/estimate (cùng hành vi). Ưu tiên /v1/fulfillment/shipping/quotes.

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

• Mọi giá trị tiền amount đều là số nguyên fen CNY. 5000 nghĩa là ¥50.00.
• monetary_unit cấp cao nhất luôn là CNY_minor.
• Đối tượng tiền dùng { "amount": 5000, "currency": "CNY" }.
• Cân nặng yêu cầu luôn là KG. Kích thước kiện luôn là CM.
• Nhận diện kênh và dịch vụ bằng code ổn định, không dùng name.

Header yêu cầu {#request}

POST /v1/fulfillment/shipping/quotes
Authorization: Bearer hio_live_xxx
Content-Type: application/json
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 JSON body hoặc query string.

Hai định dạng yêu cầu {#request-formats}

Không kết hợp các trường cú pháp tắt một kiện (weight_kg, length_cm, width_cm, height_cm) với packages[]. API từ chối yêu cầu hỗn hợp bằng 400 VALIDATION_ERROR.

Định dạng A — cú pháp tắt một kiện {#format-a}

Dùng khi bạn biết điểm đến và cân nặng tổng ước tính, nhưng chưa biết kho sẽ tách thùng thế nào.

Yêu cầu tối thiểu:

{
  "destination": {
    "country_code": "KR"
  },
  "weight_kg": 2.05
}

Một kiện kèm kích thước:

{
  "destination": {
    "country_code": "KR",
    "postal_code": "04524"
  },
  "weight_kg": 2.05,
  "length_cm": 30,
  "width_cm": 20,
  "height_cm": 10,
  "attributes": []
}

• weight_kg là cân nặng lô hàng ước tính tính bằng KG.
• length_cm, width_cm và height_cm tính bằng CM. Cung cấp cả ba hoặc bỏ cả ba.
• Ưu tiên định dạng này khi chưa biết cách tách thùng cuối cùng tại kho. Thiếu kích thước có thể cho PARTIAL hoặc REVIEW_REQUIRED với kênh tính theo thể tích.

Định dạng B — kiện đã biết {#format-b}

Dùng packages[] khi đã biết số thùng và dữ liệu từng thùng.

Một kiện khai báo:

{
  "destination": {
    "country_code": "KR"
  },
  "packages": [
    {
      "reference": "box-1",
      "weight": {
        "value": 2.05,
        "unit": "KG"
      },
      "dimensions": {
        "length": 30,
        "width": 20,
        "height": 10,
        "unit": "CM"
      }
    }
  ]
}

Nhiều kiện:

{
  "destination": {
    "country_code": "KR",
    "postal_code": "04524"
  },
  "packages": [
    {
      "reference": "box-1",
      "weight": {
        "value": 1.25,
        "unit": "KG"
      },
      "dimensions": {
        "length": 30,
        "width": 20,
        "height": 10,
        "unit": "CM"
      }
    },
    {
      "reference": "box-2",
      "weight": {
        "value": 0.8,
        "unit": "KG"
      },
      "dimensions": {
        "length": 20,
        "width": 15,
        "height": 8,
        "unit": "CM"
      }
    }
  ]
}

Quy tắc packages[] (OpenAPI):

• 1–200 kiện.
• Một phần tử là một kiện đơn tường minh. Nhiều phần tử là lô hàng nhiều kiện tường minh.
• reference tùy chọn, nhưng phải duy nhất trong yêu cầu.
• packages[].weight bắt buộc. packages[].weight.unit phải là KG.
• packages[].dimensions tùy chọn. Khi có, length, width, height và unit đều bắt buộc. unit phải là CM.

Gateway ánh xạ định dạng A thành một kiện kho. Định dạng B được xác thực và ánh xạ như đã khai báo. Cách tách cuối cùng và kích thước đo được vẫn do xử lý tại kho quyết định.

Trường yêu cầu dùng chung {#shared-fields}

Cả hai định dạng đều có thể gồm các trường sau.

destination

declared_value

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

Giá trị khai báo cấp lô hàng bằng fen CNY nguyên. Bỏ trường khi chưa biết. Không gửi 0 để nghĩa là chưa biết.

attributes

Mảng mã thuộc tính hàng ổn định từ GET /v1/fulfillment/shipments/item-attributes. Chuỗi duy nhất, tối đa 100.

Báo giá trước tiên chỉ giữ các kênh áp dụng cho destination.country_code; kênh của quốc gia khác sẽ bị loại bỏ. Mỗi kênh còn lại đánh giá riêng các thuộc tính đã khai báo. Thuộc tính không được hỗ trợ khiến kênh trả UNAVAILABLE với ATTRIBUTE_NOT_SUPPORTED, trong khi các kênh phù hợp khác vẫn có thể trả báo giá.

services

{
  "services": {
    "channel": [
      {
        "code": "LINE_INSURANCE",
        "quantity": 1
      }
    ],
    "outbound": [
      {
        "code": "VACUUM_PACKING",
        "quantity": 1
      }
    ],
    "inbound": [
      {
        "code": "PHOTO",
        "quantity": 3
      }
    ]
  }
}

Mỗi mục cần code và quantity. OpenAPI: quantity là số nguyên từ 1 đến 999. Mã phải duy nhất trong từng nhóm.

channel_codes

Mã kênh ổn định giới hạn tập báo giá. Bỏ để báo giá mọi kênh ứng viên. Không gửi mảng rỗng. Mã không xác định hoặc không truy cập được trả về 400 INVALID_SHIPPING_CHANNEL cho toàn bộ yêu cầu.

Ví dụ yêu cầu đầy đủ {#complete-request}

Định dạng A với điểm đến, kích thước, giá trị khai báo, thuộc tính, dịch vụ và bộ lọc kênh:

{
  "destination": {
    "country_code": "US",
    "subdivision_code": "US-CA",
    "region": "California",
    "postal_code": "90001"
  },
  "weight_kg": 2.05,
  "length_cm": 30,
  "width_cm": 20,
  "height_cm": 10,
  "declared_value": {
    "amount": 5000,
    "currency": "CNY"
  },
  "attributes": [
    "GENERAL_CARGO"
  ],
  "services": {
    "channel": [
      {
        "code": "LINE_INSURANCE",
        "quantity": 1
      }
    ],
    "outbound": [
      {
        "code": "VACUUM_PACKING",
        "quantity": 1
      }
    ],
    "inbound": [
      {
        "code": "PHOTO",
        "quantity": 3
      }
    ]
  },
  "channel_codes": [
    "US-SEA"
  ]
}

Phản hồi {#response}

{
  "success": true,
  "estimate_type": "DECLARED",
  "completeness": {
    "level": "HIGH",
    "destination": "COMPLETE",
    "package_dimensions": "COMPLETE",
    "package_split": "DECLARED",
    "declared_value": "PROVIDED",
    "attributes": "DECLARED",
    "services": "REQUESTED_ONLY"
  },
  "warnings": [
    {
      "code": "WAREHOUSE_REVIEW_REQUIRED",
      "message": "Final charges require warehouse measurement, packing and service review.",
      "affects": [
        "FINAL_CHARGES"
      ]
    }
  ],
  "quotes": [
    {
      "channel": {
        "code": "US-SEA",
        "name": "US Ocean",
        "description": "General cargo line",
        "tags": [
          "GREAT_VALUE"
        ],
        "capabilities": {
          "delivery_methods": [
            "DOOR_DELIVERY",
            "PICKUP"
          ]
        }
      },
      "available": true,
      "quote_status": "COMPLETE",
      "unavailable_reason": null,
      "attribute_evaluation": {
        "status": "SUPPORTED",
        "declared_attributes": [
          {
            "code": "GENERAL",
            "name": "General cargo"
          }
        ],
        "accepted_attributes": [
          {
            "code": "GENERAL",
            "name": "General cargo"
          }
        ],
        "unsupported_attributes": []
      },
      "matched_region": {
        "code": "US-WEST",
        "name": "US West",
        "match_type": "COUNTRY_REGION"
      },
      "packages": [
        {
          "reference": "box-1",
          "weight": {
            "value": 2.05,
            "unit": "KG"
          },
          "dimensions": {
            "length": 30,
            "width": 20,
            "height": 10,
            "unit": "CM"
          },
          "weights": {
            "actual": {
              "value": 2.05,
              "unit": "KG"
            },
            "volumetric": {
              "value": 1,
              "unit": "KG"
            },
            "chargeable": {
              "value": 2.5,
              "unit": "KG"
            }
          }
        }
      ],
      "weights": {
        "actual": {
          "value": 2.05,
          "unit": "KG"
        },
        "volumetric": {
          "value": 1,
          "unit": "KG"
        },
        "chargeable": {
          "value": 2.5,
          "unit": "KG"
        }
      },
      "billing_quantity": {
        "value": 2.5,
        "unit": "KG"
      },
      "pricing_selector": {
        "type": "WEIGHT",
        "value": 2.5,
        "unit": "KG",
        "scope": "SHIPMENT"
      },
      "transit_time": {
        "text": "15-18 business days",
        "min_business_days": 15,
        "max_business_days": 18
      },
      "charges": {
        "base_freight": {
          "amount": 10000,
          "currency": "CNY"
        },
        "channel_services": {
          "amount": 550,
          "currency": "CNY",
          "known_amount": 550,
          "calculation_status": "CALCULATED",
          "items": []
        },
        "channel_rules": {
          "amount": 0,
          "currency": "CNY",
          "known_amount": 0,
          "calculation_status": "CALCULATED",
          "items": [],
          "aggregation": "SUM_ALL",
          "cap": null
        },
        "outbound_services": {
          "amount": 800,
          "currency": "CNY",
          "known_amount": 800,
          "calculation_status": "CALCULATED",
          "items": []
        },
        "inbound_services": {
          "amount": 300,
          "currency": "CNY",
          "known_amount": 300,
          "calculation_status": "CALCULATED",
          "items": []
        },
        "adjustments": {
          "amount": 0,
          "currency": "CNY",
          "known_amount": 0,
          "calculation_status": "CALCULATED",
          "items": []
        }
      },
      "display_charges": {
        "addition": {
          "amount": 0,
          "currency": "CNY",
          "included_in_total": false
        },
        "floor": {
          "amount": 0,
          "currency": "CNY",
          "included_in_total": false
        }
      },
      "total": {
        "amount": 11650,
        "currency": "CNY"
      },
      "known_total": {
        "amount": 11650,
        "currency": "CNY"
      },
      "warnings": [],
      "service_adjustment_possible": true
    }
  ],
  "monetary_unit": "CNY_minor",
  "generated_at": "2026-09-07T08:00:00Z",
  "request_id": "req_xxx",
  "disclaimer": "Estimated charges based on declared data."
}

Trường cấp cao

completeness

Trạng thái báo giá {#quote-status}

Không quyết định chỉ từ available. Luôn đọc quote_status.

• total là ngân sách đầy đủ khi đã biết.
• known_total là tổng phí có thể tính ngay.
• Khi total là null, không coi known_total là báo giá đầy đủ.
• unavailable_reason.code dùng cho xử lý chương trình.
• unavailable_reason.message chỉ để hiển thị.

UNAVAILABLE trên một báo giá không phải lỗi HTTP.

Đối tượng báo giá {#quotes}

Cân nặng và số lượng tính cước {#weights}

• actual — cân nặng khai báo hoặc đo được.
• volumetric — cân nặng thể tích.
• chargeable — cân nặng dùng tính cước vận chuyển.
• billing_quantity — số lượng kênh tính cước (có thể là cân nặng, thể tích hoặc mật độ).
• pricing_selector — cách số lượng đó chọn hàng bảng giá. Kiểu khớp catalog WEIGHT / VOLUME / DENSITY.
• Kênh nhiều kiện có thể làm tròn theo thùng rồi cộng. Khi pricing_selector.scope là PER_PACKAGE, đọc từng packages[].pricing_selector.

Phí {#charges}

Dịch vụ nhập kho và xuất kho

inbound_services và outbound_services thuộc hai giai đoạn khác nhau của dịch vụ giá trị gia tăng tại kho. Dịch vụ nhập kho được thực hiện khi kho tiếp nhận hàng, chẳng hạn chụp ảnh kiện hàng, quay video hoặc kiểm tra. Dịch vụ xuất kho được thực hiện khi chuẩn bị lô hàng, chẳng hạn gia cố kiện hàng, đóng gói hút chân không hoặc đóng khung/thùng gỗ. Các dịch vụ ở cả hai giai đoạn có thể cùng áp dụng và được tính phí hợp lệ cho một kiện hàng hoặc lô hàng.

Số tiền trong Shipping Quote chỉ là ước tính; việc yêu cầu báo giá không tạo ra một khoản phí dịch vụ bổ sung. Phí cuối cùng được xác định theo dịch vụ thực tế đã thực hiện cùng mức giá và quyết toán cuối cùng. Hãy dùng cả hai nhóm để ước tính tổng chi phí fulfillment và đối chiếu từng khoản ước tính với phí thực tế tương ứng. Không cộng lại khoản ước tính của cùng một dịch vụ lên trên phí cuối cùng của dịch vụ đó.

Ví dụ theo đơn vị nhỏ nhất CNY: ảnh kiện hàng 50 fen (¥0,50), kiểm tra 100 fen (¥1,00), đóng gói hút chân không 150 fen (¥1,50), gia cố kiện hàng 200 fen (¥2,00). Cả bốn khoản có thể cùng tồn tại vì đây là các dịch vụ khác nhau ở các giai đoạn fulfillment khác nhau.

Mỗi nhóm thường gồm:

channel_rules cũng có thể gồm aggregation và cap. Dùng tổng phụ của nhóm — không thay bằng cách cộng các mục quy tắc thô.

SUM_ALL cộng mọi phí khớp. HIGHEST_ONLY chỉ chọn mức cao nhất sau khi sắp xếp giảm dần; các quy tắc cùng giá là tương đương. cap=null nghĩa là không giới hạn. reason chỉ dùng để hiển thị. Với logic chương trình, dùng condition_match, matched_conditions, rule_type, charge_mode, charge_value, outcome và missing_fields. PENDING_INPUT, REVIEW_REQUIRED và các quy tắc chưa tính khác không được đưa vào tổng đã biết. amount=null không phải là 0 và charge_value đã cấu hình không phải khoản phí thực tế.

Mục phí

display_charges có thể chỉ tồn tại cho trình bày frontend.

Lý do không khả dụng {#unavailable-reasons}

Các giá trị unavailable_reason.code thường gặp:

OUTSIDE_PRICING_RANGE
POSTAL_CODE_REQUIRED
POSTAL_CODE_NOT_SUPPORTED
DESTINATION_NOT_SUPPORTED
ATTRIBUTE_NOT_SUPPORTED
SERVICE_NOT_SUPPORTED
DIMENSIONS_REQUIRED
DECLARED_VALUE_REQUIRED
MULTI_PACKAGE_NOT_SUPPORTED
PRICING_MODE_UNSUPPORTED
CHANNEL_RULE_REJECTED
CHANNEL_PRICING_ERROR

Kênh không khả dụng vẫn nằm trong quotes[] để bạn giải thích lý do bị từ chối.

Thuật ngữ catalog {#catalog-terminology}

Thuộc tính hàng {#item-attributes}

GET /v1/fulfillment/shipments/item-attributes trả về các mã attributes[] hợp lệ cho báo giá.

Lỗi {#errors}

Không có mã công khai riêng AUTHENTICATION_ERROR, WAREHOUSE_AUTH_REQUIRED hay WAREHOUSE_SERVICE_UNAVAILABLE. Dùng 401 INVALID_API_KEY, 403 WAREHOUSE_AUTH_INVALID và 502 WAREHOUSE_UPSTREAM_ERROR.

Kênh không thể nhận lô hàng này là báo giá UNAVAILABLE, không phải thất bại HTTP.

Liên quan {#related}

• Kênh vận chuyển — khả năng, phủ sóng và mã dịch vụ
• Lô hàng — tạo lô hàng sau khi kiện đã nhập kho
• Tổng quan fulfillment