API каналов доставки

GET /v1/fulfillment/shipping/channels возвращает активные, с настроенной тарификацией международные каналы доставки, доступные через склад, привязанный к вашему приложению.

Используйте этот эндпоинт, чтобы построить выбор канала или проверить возможности. Для доступности и сумм по конкретному направлению вызывайте расчёт стоимости доставки. Тарифные карты здесь только объясняют модель ценообразования — они никогда не фиксируют цену.

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

Требуется складской фулфилмент. Песочное приложение с ключом hio_test_* получает детерминированные mock-данные.

Предложения — это бюджеты, а не зафиксированные цены. Взвешивание на складе, обмер объёма, переупаковка и проверка услуг могут изменить итоговую сумму.

Деньги и единицы {#units}

Все денежные значения amount — целые фэни CNY (минорные единицы). 1000 означает ¥10.00.
Поле верхнего уровня monetary_unit всегда равно CNY_minor.
Денежные объекты имеют вид:

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

KG = килограмм, CM = сантиметр, M3 = кубический метр, KG_PER_M3 = килограмм на кубический метр.
Идентифицируйте каналы, регионы и услуги по стабильному code, а не по name.
Public API не раскрывает идентификаторы складской БД, коды разработчика и 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. Не передавайте language в строке запроса или в JSON-теле.

Параметры запроса

Параметр	Обязательно	По умолчанию	Описание
`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 }`. Не идентификатор БД.
`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}

Используйте value_added_services[].code в services.channel[] при расчёте стоимости доставки.

Поле	Значение
`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