API des canaux d’expédition

GET /v1/fulfillment/shipping/channels liste les canaux d’expédition internationaux actifs et configurés en tarif disponibles via l’entrepôt lié à votre app.

Utilisez cet endpoint pour construire un sélecteur de canal ou inspecter les capacités. Pour la disponibilité et les montants selon la destination, appelez Devis d’expédition. Les grilles tarifaires n’expliquent ici que le modèle de tarification — elles ne verrouillent jamais un prix.

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

Requiert le fulfillment entrepôt. Une app sandbox avec une clé hio_test_* reçoit des données mock déterministes.

Les devis sont des budgets, pas des prix verrouillés. Le pesage en entrepôt, la mesure du volume, le reconditionnement et la revue des services peuvent modifier le montant final.

Argent et unités {#units}

Tous les amount monétaires sont des fen CNY entiers (unités mineures). 1000 signifie ¥10.00.
Le monetary_unit de premier niveau est toujours CNY_minor.
Les objets monétaires utilisent :

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

KG = kilogramme, CM = centimètre, M3 = mètre cube, KG_PER_M3 = kilogramme par mètre cube.
Identifiez les canaux, régions et services par code stable, pas par name.
L’API publique n’expose pas les identifiants de base de données de l’entrepôt, les codes développeur ni les URL de fournisseurs.

Requête {#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

La langue d’affichage est uniquement l’en-tête Language. Valeurs prises en charge : en (défaut), en-US, zh, zh-CN, zh-TW, cn, hk. Ne placez pas language dans la chaîne de requête ni dans le corps JSON.

Paramètres de requête

Paramètre	Obligatoire	Défaut	Description
`channel_code`	Non	—	Code de canal stable exact (64 caractères max)
`country_code`	Non	—	Pays de destination ISO 3166-1 alpha-2
`include`	Non	—	Expansions séparées par des virgules : `regions`, `services`, `rate_cards`
`page`	Non	`1`	Numéro de page, à partir de 1
`page_size`	Non	`20`	Éléments par page ; maximum 50

Expansions `include`

Omettez include pour un résumé de canal léger.

Valeur `include`	Champ de réponse	Utilisez lorsque
`regions`	`regions`	Couverture, type de correspondance et délai de transit de référence
`services`	`value_added_services`	Services à valeur ajoutée du canal pour les devis
`rate_cards`	`rate_cards`	Lignes de prix de référence qui expliquent le modèle de facturation

Vous pouvez combiner les valeurs, par exemple include=regions,services,rate_cards. Une valeur inconnue renvoie 400 VALIDATION_ERROR.

Les rate_cards sont reference_only. Ils ne doivent pas remplacer POST /v1/fulfillment/shipping/quotes. Seul include=rate_cards demande à l’entrepôt les lignes de prix.

Seuls les canaux activés et dotés d’une configuration tarifaire valide sont renvoyés. Un tableau items vide signifie qu’aucun canal du catalogue ne correspond aux filtres actuels.

Réponse {#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 et rate_cards n’apparaissent que lorsque la valeur include correspondante est envoyée.

Champs de réponse {#fields}

Champ	Description
`items[]`	Canaux correspondants. Vide lorsqu’aucun canal du catalogue ne correspond aux filtres.
`items[].code`	Code de canal stable. Utilisez-le dans `channel_codes` des devis et à la création d’expédition.
`items[].name`	Nom d’affichage localisé (en-tête `Language`).
`items[].description`	Description localisée.
`items[].status`	Statut du catalogue. Les canaux renvoyés sont `ACTIVE`.
`items[].tags`	Étiquettes stables telles que `GREAT_VALUE`.
`items[].warehouse`	Entrepôt lié `{ code, name }`. Ce n’est pas un identifiant de base de données.
`items[].capabilities`	Méthodes de livraison, multi-colis, suivi et prise en charge des étiquettes.
`items[].requirements`	Indications de complétude des données d’entrée : `REQUIRED` · `OPTIONAL` · `CONDITIONAL` · `NOT_SUPPORTED`.
`items[].attribute_matching`	`ANY_OF` ou `ALL_REQUIRED` plus `accepted_attributes[].code`.
`items[].billing`	Comment le canal tarifie une expédition. Voir ci-dessous.
`items[].rule_summary`	Indique si des surcharges ou des restrictions existent ; les devis évaluent les règles.
`items[].regions`	Présent avec `include=regions`.
`items[].value_added_services`	Présent avec `include=services`.
`items[].rate_cards`	Présent avec `include=rate_cards`. Toujours `reference_only`.
`items[].service_policy`	L’entrepôt peut ajouter/retirer des services et modifier les prix après inspection.
`items[].final_quote_required`	`true` lorsqu’un devis spécifique à l’expédition est encore requis.
`items[].config_updated_at`	Horodatage de révision du catalogue pour ce canal.
`pagination`	`page`, `page_size`, `total`, `has_more`.
`monetary_unit`	Toujours `CNY_minor`.
`generated_at`	Horodatage de la réponse (ISO 8601).
`request_id`	Corréler avec `x-request-id`.

Facturation {#billing}

Champ	Signification
`basis`	`WEIGHT`, `VOLUME`, ou `DENSITY`
`calculation_model`	Modèle de tarification utilisé par les lignes tarifaires
`quantity_unit`	`KG`, `M3`, ou `KG_PER_M3`
`supported_range`	Quantité facturable minimale et maximale
`supported_range.out_of_range_behavior`	`UNAVAILABLE` — le canal ne peut pas transporter un colis hors de la plage. N’extrapolez pas.
`minimum`	Quantité facturable minimale et si les valeurs inférieures sont arrondies vers le haut (`ceil_to_minimum`)
`rounding`	Pas d’arrondi pour colis unique et multi-colis
`volumetric_weight`	Diviseur volumétrique et règle d’exonération
`multi_package`	Facturation par colis vs combinée, et agrégation
`overweight_warning`	Avis optionnel de surpoids

Les modèles de calcul peuvent inclure FIRST_NEXT_WEIGHT, TIERED_PRICE, UNIT_PRICE_PLUS_GRADE, MULTI_LEVEL_NEXT_WEIGHT et RANGE_FIRST_NEXT_WEIGHT. Ne réimplémentez pas le moteur de tarification de l’entrepôt à partir de ces lignes.

Régions {#regions}

Champ	Signification
`code` / `name`	Code de région stable et nom localisé
`match_type`	`COUNTRY_REGION` ou `POSTAL_CODE`
`countries`	Codes pays ISO couverts par cette région
`postal_code_required`	Lorsque `true`, envoyez `postal_code` aux devis
`reference_transit_time`	Texte d’affichage plus jours ouvrés min/max optionnels
`areas`	Liste d’aires plus fine, optionnelle. Le catalogue n’expose pas la base complète des règles postales.

Services à valeur ajoutée {#value-added-services}

Utilisez value_added_services[].code dans services.channel[] sur Devis d’expédition.

Champ	Signification
`code`	Code de service stable
`request_mode`	`MANDATORY` (toujours appliqué) ou `OPTIONAL` (sélectionné par le développeur)
`pricing_type`	Prix fixe vs calculé (par exemple `CALCULATED`)
`pricing_scope`	Où le prix s’applique (par exemple `REGION`)
`pricing_basis`	Comment le frais est calculé

BASIS_POINT est un point de base de pourcentage : 500 signifie 5 %. L’entrepôt peut ajouter, retirer ou ajuster des services pendant le traitement — voir service_policy et may_be_adjusted.

Grilles tarifaires {#rate-cards}

Champ	Signification
`region_code`	Région à laquelle cette grille appartient
`billing_basis`	Même vocabulaire que `billing.basis`
`calculation_model`	Même vocabulaire que `billing.calculation_model`
`quantity_unit`	`KG`, `M3`, ou `KG_PER_M3`
`price_rows`	Tranches de référence utilisées pour expliquer le modèle
`reference_only`	Toujours `true` — ce n’est pas un devis en direct

Mise en cache {#caching}

config_updated_at change lorsque les détails du canal, les régions, les grilles tarifaires, les règles ou les services changent. Mettez le catalogue léger en cache brièvement, rechargez les expansions lorsque cet horodatage change, et appelez toujours Devis d’expédition avant de créer une expédition. Il n’existe pas de version de tarif verrouillée.

Erreurs {#errors}

Une inéligibilité propre à un canal n’est pas une erreur HTTP. Un tableau items vide est un échec de catalogue réussi.

HTTP	`error.code`	Quand
400	`VALIDATION_ERROR`	Pagination, syntaxe de pays ou valeur `include` invalides
401	`INVALID_API_KEY`	Jeton Bearer manquant ou invalide
400	`INVALID_SHIPPING_CHANNEL`	Réservé aux appels de devis/expédition qui nomment un canal inconnu. Cette liste renvoie simplement un tableau `items` vide.
403	`FULFILLMENT_MODE_NOT_SUPPORTED`	L’app utilise le self fulfillment
403	`WAREHOUSE_AUTH_INVALID`	L’autorisation d’entrepôt est manquante, rejetée ou expirée
422	`INVALID_COUNTRY_CODE`	Le pays de destination est invalide ou non pris en charge
502	`WAREHOUSE_UPSTREAM_ERROR`	Le service d’entrepôt a échoué ; réessayez avec backoff

Il n’existe pas de code public distinct AUTHENTICATION_ERROR, WAREHOUSE_AUTH_REQUIRED ou WAREHOUSE_SERVICE_UNAVAILABLE. Les échecs d’authentification utilisent 401 INVALID_API_KEY ; une liaison d’entrepôt manquante utilise 403 WAREHOUSE_AUTH_INVALID ; les pannes d’entrepôt utilisent 502 WAREHOUSE_UPSTREAM_ERROR.

Voir Erreurs et Authentification.

Exemples {#examples}

Catalogue léger :

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

Canaux pouvant desservir les États-Unis, y compris la tarification de référence :

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"

Suite : demander un devis d’expédition spécifique à la destination.

Get Support

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

Email support