API de canales de envío

GET /v1/fulfillment/shipping/channels enumera los canales de envío internacionales activos y con tarifa configurada disponibles a través del almacén vinculado a su app.

Utilice este endpoint para construir un selector de canal o inspeccionar las capacidades. Para la disponibilidad y los importes según el destino, llame a Cotizaciones de envío. Las tarifas de referencia solo explican el modelo de precios: nunca bloquean un precio.

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

Requiere fulfillment de almacén. Una app sandbox con una clave hio_test_* recibe datos mock deterministas.

Las cotizaciones son presupuestos, no precios bloqueados. El pesaje en almacén, la medición de volumen, el reembalaje y la revisión de servicios pueden cambiar el importe final.

Dinero y unidades {#units}

Todos los valores monetarios amount son enteros en fen de CNY (unidades menores). 1000 significa ¥10.00.
El monetary_unit de primer nivel es siempre CNY_minor.
Los objetos monetarios usan:

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

KG = kilogramo, CM = centímetro, M3 = metro cúbico, KG_PER_M3 = kilogramo por metro cúbico.
Identifique canales, regiones y servicios por code estable, no por name.
La API pública no expone IDs de base de datos del almacén, códigos de desarrollador ni URL de proveedores.

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

El idioma de visualización es únicamente el encabezado Language. Valores admitidos: en (predeterminado), en-US, zh, zh-CN, zh-TW, cn, hk. No coloque language en la cadena de consulta ni en el cuerpo JSON.

Parámetros de consulta

Parámetro	Obligatorio	Predeterminado	Descripción
`channel_code`	No	—	Código de canal estable exacto (máximo 64 caracteres)
`country_code`	No	—	País de destino ISO 3166-1 alpha-2
`include`	No	—	Expansiones separadas por comas: `regions`, `services`, `rate_cards`
`page`	No	`1`	Número de página, a partir de 1
`page_size`	No	`20`	Elementos por página; máximo 50

Expansiones `include`

Omita include para un resumen de canal ligero.

Valor `include`	Campo de respuesta	Úselo cuando
`regions`	`regions`	Cobertura, tipo de coincidencia y tiempo de tránsito de referencia
`services`	`value_added_services`	Servicios de valor añadido del canal para las cotizaciones
`rate_cards`	`rate_cards`	Filas de precio de referencia que explican el modelo de facturación

Puede combinar valores, por ejemplo include=regions,services,rate_cards. Un valor desconocido devuelve 400 VALIDATION_ERROR.

Los rate_cards son reference_only. No deben sustituir POST /v1/fulfillment/shipping/quotes. Solo include=rate_cards solicita al almacén las filas de precio.

Solo se devuelven los canales habilitados y con una configuración de precio válida. Un array items vacío significa que ningún canal del catálogo coincide con los filtros actuales.

Respuesta {#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 y rate_cards aparecen solo cuando se envía el valor include correspondiente.

Campos de respuesta {#fields}

Campo	Descripción
`items[]`	Canales coincidentes. Vacío cuando ningún canal del catálogo coincide con los filtros.
`items[].code`	Código de canal estable. Úselo en `channel_codes` de las cotizaciones y al crear el envío.
`items[].name`	Nombre de visualización localizado (encabezado `Language`).
`items[].description`	Descripción localizada.
`items[].status`	Estado del catálogo. Los canales devueltos son `ACTIVE`.
`items[].tags`	Etiquetas estables como `GREAT_VALUE`.
`items[].warehouse`	Almacén vinculado `{ code, name }`. No es un ID de base de datos.
`items[].capabilities`	Métodos de entrega, multi-paquete, tracking y soporte de etiquetas.
`items[].requirements`	Indicaciones de completitud de la entrada: `REQUIRED` · `OPTIONAL` · `CONDITIONAL` · `NOT_SUPPORTED`.
`items[].attribute_matching`	`ANY_OF` o `ALL_REQUIRED` más `accepted_attributes[].code`.
`items[].billing`	Cómo el canal tarifica un envío. Véase más abajo.
`items[].rule_summary`	Si existen recargos o restricciones; las cotizaciones evalúan las reglas.
`items[].regions`	Presente con `include=regions`.
`items[].value_added_services`	Presente con `include=services`.
`items[].rate_cards`	Presente con `include=rate_cards`. Siempre `reference_only`.
`items[].service_policy`	El almacén puede añadir/quitar servicios y cambiar precios tras la inspección.
`items[].final_quote_required`	`true` cuando aún se requiere una cotización específica del envío.
`items[].config_updated_at`	Hora de revisión del catálogo para este canal.
`pagination`	`page`, `page_size`, `total`, `has_more`.
`monetary_unit`	Siempre `CNY_minor`.
`generated_at`	Marca de tiempo de la respuesta (ISO 8601).
`request_id`	Correlacione con `x-request-id`.

Facturación {#billing}

Campo	Significado
`basis`	`WEIGHT`, `VOLUME`, o `DENSITY`
`calculation_model`	Modelo de precios usado por las filas tarifarias
`quantity_unit`	`KG`, `M3`, o `KG_PER_M3`
`supported_range`	Cantidad facturable mínima y máxima
`supported_range.out_of_range_behavior`	`UNAVAILABLE` — el canal no puede transportar un paquete fuera del rango. No extrapole.
`minimum`	Cantidad facturable mínima y si los valores menores se redondean hacia arriba (`ceil_to_minimum`)
`rounding`	Pasos de redondeo para paquete único y multi-paquete
`volumetric_weight`	Divisor volumétrico y regla de exención
`multi_package`	Facturación por paquete vs combinada y agregación
`overweight_warning`	Aviso opcional de sobrepeso

Los modelos de cálculo pueden incluir FIRST_NEXT_WEIGHT, TIERED_PRICE, UNIT_PRICE_PLUS_GRADE, MULTI_LEVEL_NEXT_WEIGHT y RANGE_FIRST_NEXT_WEIGHT. No reimplemente el motor de precios del almacén a partir de estas filas.

Regiones {#regions}

Campo	Significado
`code` / `name`	Código de región estable y nombre localizado
`match_type`	`COUNTRY_REGION` o `POSTAL_CODE`
`countries`	Códigos de país ISO cubiertos por esta región
`postal_code_required`	Cuando es `true`, envíe `postal_code` a las cotizaciones
`reference_transit_time`	Texto de visualización más días hábiles mín./máx. opcionales
`areas`	Lista opcional de áreas más granulares. El catálogo no expone la base completa de reglas postales.

Servicios de valor añadido {#value-added-services}

Utilice value_added_services[].code en services.channel[] en Cotizaciones de envío.

Campo	Significado
`code`	Código de servicio estable
`request_mode`	`MANDATORY` (siempre aplicado) o `OPTIONAL` (seleccionado por el desarrollador)
`pricing_type`	Precio fijo vs calculado (por ejemplo `CALCULATED`)
`pricing_scope`	Dónde aplica el precio (por ejemplo `REGION`)
`pricing_basis`	Cómo se calcula el cargo

BASIS_POINT es un punto básico porcentual: 500 significa 5 %. El almacén puede añadir, quitar o ajustar servicios durante el procesamiento — véase service_policy y may_be_adjusted.

Tarifas de referencia {#rate-cards}

Campo	Significado
`region_code`	Región a la que pertenece esta tarjeta
`billing_basis`	Mismo vocabulario que `billing.basis`
`calculation_model`	Mismo vocabulario que `billing.calculation_model`
`quantity_unit`	`KG`, `M3`, o `KG_PER_M3`
`price_rows`	Bandas de referencia usadas para explicar el modelo
`reference_only`	Siempre `true` — no es una cotización en vivo

Caché {#caching}

config_updated_at cambia cuando cambian los detalles del canal, las regiones, las tarifas, las reglas o los servicios. Ponga en caché el catálogo ligero brevemente, vuelva a obtener las expansiones cuando cambie esta marca de tiempo y llame siempre a Cotizaciones de envío antes de crear un envío. No hay una versión de precios bloqueada.

Errores {#errors}

La inelegibilidad específica de un canal no es un error HTTP. Un array items vacío es un fallo de catálogo exitoso.

HTTP	`error.code`	Cuándo
400	`VALIDATION_ERROR`	Paginación, sintaxis de país o valor `include` inválidos
401	`INVALID_API_KEY`	Token Bearer ausente o inválido
400	`INVALID_SHIPPING_CHANNEL`	Reservado para llamadas de cotización/envío que nombran un canal desconocido. Esta lista simplemente devuelve un array `items` vacío.
403	`FULFILLMENT_MODE_NOT_SUPPORTED`	La app usa self fulfillment
403	`WAREHOUSE_AUTH_INVALID`	La autorización del almacén falta, fue rechazada o expiró
422	`INVALID_COUNTRY_CODE`	El país de destino es inválido o no admitido
502	`WAREHOUSE_UPSTREAM_ERROR`	El servicio del almacén falló; reintente con backoff

No hay un código público distinto AUTHENTICATION_ERROR, WAREHOUSE_AUTH_REQUIRED ni WAREHOUSE_SERVICE_UNAVAILABLE. Los fallos de autenticación usan 401 INVALID_API_KEY; la vinculación de almacén ausente usa 403 WAREHOUSE_AUTH_INVALID; las interrupciones del almacén usan 502 WAREHOUSE_UPSTREAM_ERROR.

Véase Errores y Autenticación.

Ejemplos {#examples}

Catálogo ligero:

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

Canales que pueden servir a Estados Unidos, incluida la tarificación de referencia:

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"

Siguiente: solicitar una cotización de envío específica de destino.

Get Support

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

Email support