API für Versandkanäle

GET /v1/fulfillment/shipping/channels listet die aktiven, preiskonfigurierten internationalen Versandkanäle auf, die über das an Ihre App angebundene Lager verfügbar sind.

Nutzen Sie diesen Endpunkt, um einen Kanalwähler aufzubauen oder Fähigkeiten zu prüfen. Für zielortspezifische Verfügbarkeit und Beträge rufen Sie Versandangebote auf. Tarifkarten erklären hier nur das Preismodell — sie sperren niemals einen Preis.

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

Erfordert Lager-Fulfillment. Eine Sandbox-App mit einem hio_test_*-Schlüssel erhält deterministische Mock-Daten.

Angebote sind Budgets, keine festgeschriebenen Preise. Wiegung im Lager, Volumenmessung, Umverpackung und Leistungsprüfung können den Endbetrag ändern.

Geld und Einheiten {#units}

Alle Geldwerte amount sind ganzzahlige CNY-Fen (Untereinheiten). 1000 bedeutet ¥10.00.
Das Top-Level-Feld monetary_unit ist immer CNY_minor.
Geldobjekte verwenden:

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

KG = Kilogramm, CM = Zentimeter, M3 = Kubikmeter, KG_PER_M3 = Kilogramm pro Kubikmeter.
Identifizieren Sie Kanäle, Regionen und Dienste über den stabilen code, nicht über name.
Die Public API legt keine Lager-Datenbank-IDs, Entwicklercodes oder Lieferanten-URLs offen.

Anfrage {#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

Die Anzeigesprache ist ausschließlich der Header Language. Unterstützte Werte: en (Standard), en-US, zh, zh-CN, zh-TW, cn, hk. Setzen Sie language nicht in die Query-Zeichenfolge oder in den JSON-Body.

Query-Parameter

Parameter	Erforderlich	Standard	Beschreibung
`channel_code`	Nein	—	Exakter stabiler Kanalcode (max. 64 Zeichen)
`country_code`	Nein	—	ISO-3166-1-alpha-2-Bestimmungsland
`include`	Nein	—	Kommagetrennte Erweiterungen: `regions`, `services`, `rate_cards`
`page`	Nein	`1`	Seitennummer, beginnend bei 1
`page_size`	Nein	`20`	Einträge pro Seite; Maximum 50

`include`-Erweiterungen

Lassen Sie include weg, um eine leichtgewichtige Kanalübersicht zu erhalten.

`include`-Wert	Antwortfeld	Verwenden, wenn
`regions`	`regions`	Abdeckung, Treffertyp und Referenzlaufzeit
`services`	`value_added_services`	Kanal-Mehrwertdienste für Versandangebote
`rate_cards`	`rate_cards`	Referenzpreiszeilen, die das Abrechnungsmodell erklären

Sie können Werte kombinieren, zum Beispiel include=regions,services,rate_cards. Ein unbekannter Wert liefert 400 VALIDATION_ERROR.

rate_cards sind reference_only. Sie dürfen POST /v1/fulfillment/shipping/quotes nicht ersetzen. Nur include=rate_cards fordert Preiszeilen beim Lager an.

Es werden nur Kanäle zurückgegeben, die aktiviert sind und eine gültige Preiskonfiguration besitzen. Ein leeres Array items bedeutet, dass kein Katalogkanal zu den aktuellen Filtern passt.

Antwort {#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 und rate_cards erscheinen nur, wenn der passende include-Wert gesendet wird.

Antwortfelder {#fields}

Feld	Beschreibung
`items[]`	Passende Kanäle. Leer, wenn kein Katalogkanal zu den Filtern passt.
`items[].code`	Stabiler Kanalcode. Verwenden Sie ihn in Angeboten unter `channel_codes` und beim Erstellen einer Sendung.
`items[].name`	Lokalisierter Anzeigename (Header `Language`).
`items[].description`	Lokalisierte Beschreibung.
`items[].status`	Katalogstatus. Zurückgegebene Kanäle sind `ACTIVE`.
`items[].tags`	Stabile Tags wie `GREAT_VALUE`.
`items[].warehouse`	Gebundenes Lager `{ code, name }`. Keine Datenbank-ID.
`items[].capabilities`	Zustellmethoden, Mehrpaket-, Tracking- und Label-Unterstützung.
`items[].requirements`	Hinweise zur Eingabevollständigkeit: `REQUIRED` · `OPTIONAL` · `CONDITIONAL` · `NOT_SUPPORTED`.
`items[].attribute_matching`	`ANY_OF` oder `ALL_REQUIRED` plus `accepted_attributes[].code`.
`items[].billing`	Wie der Kanal eine Sendung bepreist. Siehe unten.
`items[].rule_summary`	Ob Zuschläge oder Einschränkungen existieren; Angebote werten die Regeln aus.
`items[].regions`	Vorhanden bei `include=regions`.
`items[].value_added_services`	Vorhanden bei `include=services`.
`items[].rate_cards`	Vorhanden bei `include=rate_cards`. Immer `reference_only`.
`items[].service_policy`	Das Lager darf Dienste nach Prüfung hinzufügen/entfernen und Preise ändern.
`items[].final_quote_required`	`true`, wenn weiterhin ein sendungsspezifisches Angebot erforderlich ist.
`items[].config_updated_at`	Revisionszeit des Katalogs für diesen Kanal.
`pagination`	`page`, `page_size`, `total`, `has_more`.
`monetary_unit`	Immer `CNY_minor`.
`generated_at`	Antwortzeitstempel (ISO 8601).
`request_id`	Korrelieren Sie mit `x-request-id`.

Abrechnung {#billing}

Feld	Bedeutung
`basis`	`WEIGHT`, `VOLUME` oder `DENSITY`
`calculation_model`	Preismodell der Tarifzeilen
`quantity_unit`	`KG`, `M3` oder `KG_PER_M3`
`supported_range`	Minimale und maximale abrechenbare Menge
`supported_range.out_of_range_behavior`	`UNAVAILABLE` — der Kanal kann ein Paket außerhalb der Spanne nicht befördern. Nicht extrapolieren.
`minimum`	Minimale abrechenbare Menge und ob kleinere Werte aufgerundet werden (`ceil_to_minimum`)
`rounding`	Rundungsschritte für Einzel- und Mehrpaketsendungen
`volumetric_weight`	Volumengewicht-Divisor und Ausnahmeregel
`multi_package`	Abrechnung pro Paket vs. kombiniert sowie Aggregation
`overweight_warning`	Optioneller Übergewichtshinweis

Berechnungsmodelle können FIRST_NEXT_WEIGHT, TIERED_PRICE, UNIT_PRICE_PLUS_GRADE, MULTI_LEVEL_NEXT_WEIGHT und RANGE_FIRST_NEXT_WEIGHT umfassen. Implementieren Sie die Preis-Engine des Lagers nicht aus diesen Zeilen nach.

Regionen {#regions}

Feld	Bedeutung
`code` / `name`	Stabiler Regionscode und lokalisierter Name
`match_type`	`COUNTRY_REGION` oder `POSTAL_CODE`
`countries`	Von dieser Region abgedeckte ISO-Ländercodes
`postal_code_required`	Wenn `true`, senden Sie `postal_code` an Versandangebote
`reference_transit_time`	Anzeigetext plus optionale min./max. Werktage
`areas`	Optionale feinere Gebietsliste. Der Katalog legt die vollständige Postleitzahl-Regeldatenbank nicht offen.

Mehrwertdienste {#value-added-services}

Verwenden Sie value_added_services[].code in services.channel[] bei Versandangeboten.

Feld	Bedeutung
`code`	Stabiler Dienstcode
`request_mode`	`MANDATORY` (immer angewendet) oder `OPTIONAL` (vom Entwickler gewählt)
`pricing_type`	Festpreis vs. berechnet (zum Beispiel `CALCULATED`)
`pricing_scope`	Wo der Preis gilt (zum Beispiel `REGION`)
`pricing_basis`	Wie die Gebühr berechnet wird

BASIS_POINT ist ein Prozent-Basispunkt: 500 bedeutet 5 %. Das Lager darf Dienste während der Bearbeitung hinzufügen, entfernen oder anpassen — siehe service_policy und may_be_adjusted.

Tarifkarten {#rate-cards}

Feld	Bedeutung
`region_code`	Region, zu der diese Karte gehört
`billing_basis`	Gleiches Vokabular wie `billing.basis`
`calculation_model`	Gleiches Vokabular wie `billing.calculation_model`
`quantity_unit`	`KG`, `M3` oder `KG_PER_M3`
`price_rows`	Referenzbänder zur Erklärung des Modells
`reference_only`	Immer `true` — kein Live-Angebot

Caching {#caching}

config_updated_at ändert sich, wenn Kanaldetails, Regionen, Tarifkarten, Regeln oder Dienste geändert werden. Cachen Sie den leichtgewichtigen Katalog kurz, laden Sie Erweiterungen neu, wenn sich dieser Zeitstempel ändert, und rufen Sie vor dem Erstellen einer Sendung immer Versandangebote auf. Es gibt keine festgeschriebene Preisversion.

Fehler {#errors}

Kanalbezogene Nichteignung ist kein HTTP-Fehler. Ein leeres Array items ist ein erfolgreicher Katalogtreffer ohne Treffer.

HTTP	`error.code`	Wann
400	`VALIDATION_ERROR`	Ungültige Paginierung, Ländersyntax oder `include`-Wert
401	`INVALID_API_KEY`	Fehlendes oder ungültiges Bearer-Token
400	`INVALID_SHIPPING_CHANNEL`	Reserviert für Angebots-/Sendungsaufrufe, die einen unbekannten Kanal nennen. Diese Liste gibt einfach ein leeres Array `items` zurück.
403	`FULFILLMENT_MODE_NOT_SUPPORTED`	Die App verwendet Self-Fulfillment
403	`WAREHOUSE_AUTH_INVALID`	Die Lagerautorisierung fehlt, wurde abgelehnt oder ist abgelaufen
422	`INVALID_COUNTRY_CODE`	Das Bestimmungsland ist ungültig oder nicht unterstützt
502	`WAREHOUSE_UPSTREAM_ERROR`	Der Lagerdienst ist fehlgeschlagen; mit Backoff erneut versuchen

Es gibt keinen eigenen öffentlichen Code AUTHENTICATION_ERROR, WAREHOUSE_AUTH_REQUIRED oder WAREHOUSE_SERVICE_UNAVAILABLE. Autorisierungsfehler verwenden 401 INVALID_API_KEY; fehlende Lagerbindung verwendet 403 WAREHOUSE_AUTH_INVALID; Lagerausfälle verwenden 502 WAREHOUSE_UPSTREAM_ERROR.

Siehe Fehler und Authentifizierung.

Beispiele {#examples}

Leichtgewichtiger Katalog:

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

Kanäle, die die Vereinigten Staaten bedienen können, einschließlich Referenzpreisen:

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"

Weiter: ein zielortspezifisches Versandangebot anfordern.

Get Support

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

Email support