API de cotizaciones de envío

POST /v1/fulfillment/shipping/quotes estima el envío internacional a partir de un destino, peso, dimensiones, atributos de artículos y servicios.

Utilice el atajo de paquete único cuando el fraccionamiento en almacén sea desconocido. Utilice packages[] cuando ya conozca el número de paquetes y las medidas de cada uno.

Este endpoint usa la misma terminología de canal, región, servicio, facturación y dinero que la API de canales de envío.

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. Una cotización COMPLETE sigue sin ser un bloqueo de precio.

Alias de compatibilidad: POST /v1/fulfillment/shipments/freight/estimate (mismo comportamiento). Prefiera /v1/fulfillment/shipping/quotes.

Dinero y unidades {#units}

• Todos los valores monetarios amount son enteros en fen de CNY. 5000 significa ¥50.00.
• El monetary_unit de primer nivel es siempre CNY_minor.
• Los objetos monetarios usan { "amount": 5000, "currency": "CNY" }.
• El peso de la solicitud es siempre KG. Las dimensiones de paquete son siempre CM.
• Identifique canales y servicios por code estable, no por name.

Encabezados de solicitud {#request}

POST /v1/fulfillment/shipping/quotes
Authorization: Bearer hio_live_xxx
Content-Type: application/json
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 el cuerpo JSON ni en la cadena de consulta.

Dos formatos de solicitud {#request-formats}

No combine los campos del atajo de paquete único (weight_kg, length_cm, width_cm, height_cm) con packages[]. La API rechaza una solicitud mixta con 400 VALIDATION_ERROR.

Formato A — atajo de paquete único {#format-a}

Utilice este formato cuando conozca el destino y el peso total estimado, pero no cómo el almacén fraccionará las cajas.

Solicitud mínima:

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

Paquete único con dimensiones:

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

• weight_kg es el peso estimado del envío en KG.
• length_cm, width_cm y height_cm están en CM. Proporcione los tres u omita los tres.
• Prefiera este formato cuando el fraccionamiento final en almacén sea desconocido. Dimensiones faltantes pueden producir PARTIAL o REVIEW_REQUIRED en canales volumétricos.

Formato B — paquetes conocidos {#format-b}

Utilice packages[] cuando ya conozca el número de cajas y los datos de cada caja.

Paquete declarado único:

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

Varios paquetes:

{
  "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"
      }
    }
  ]
}

Reglas de packages[] (OpenAPI):

• 1–200 paquetes.
• Un elemento es un paquete único explícito. Varios elementos constituyen un envío multi-paquete explícito.
• reference es opcional, pero debe ser único dentro de la solicitud.
• packages[].weight es obligatorio. packages[].weight.unit debe ser KG.
• packages[].dimensions es opcional. Cuando está presente, length, width, height y unit son todos obligatorios. unit debe ser CM.

El Gateway mapea el formato A a un paquete de almacén único. El formato B se valida y se mapea tal como se declaró. El fraccionamiento final y las dimensiones medidas se determinan todavía después del procesamiento en almacén.

Campos de solicitud compartidos {#shared-fields}

Ambos formatos pueden incluir lo siguiente.

destination

declared_value

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

Valor declarado a nivel de envío en fen de CNY enteros. Omita el campo cuando sea desconocido. No envíe 0 para significar desconocido.

attributes

Array de códigos de atributos de artículo estables de GET /v1/fulfillment/shipments/item-attributes. Cadenas únicas, máximo 100.

Las cotizaciones se limitan primero a los canales aplicables a destination.country_code; se omiten los canales de otros países. Cada canal restante evalúa por separado los atributos declarados. Un atributo no admitido produce UNAVAILABLE con ATTRIBUTE_NOT_SUPPORTED, mientras que otros canales aplicables aún pueden devolver cotizaciones.

services

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

Cada elemento exige code y quantity. OpenAPI: quantity es un entero de 1 a 999. Los códigos deben ser únicos dentro de cada grupo.

channel_codes

Códigos de canal estables que restringen el conjunto de cotizaciones. Omita para cotizar todos los canales candidatos. No envíe un array vacío. Un código desconocido o inaccesible devuelve 400 INVALID_SHIPPING_CHANNEL para toda la solicitud.

Ejemplo de solicitud completa {#complete-request}

Formato A con destino, dimensiones, valor declarado, atributos, servicios y un filtro de canal:

{
  "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"
  ]
}

Respuesta {#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."
}

Campos de primer nivel

completeness

Estado de la cotización {#quote-status}

No decida solo a partir de available. Lea siempre quote_status.

• total es el presupuesto completo cuando se conoce.
• known_total es la suma de los cargos que se pueden calcular ahora.
• Cuando total es null, no trate known_total como una cotización completa.
• unavailable_reason.code es para el manejo programático.
• unavailable_reason.message es solo para visualización.

UNAVAILABLE en una cotización no es un error HTTP.

Objeto de cotización {#quotes}

Pesos y cantidad facturable {#weights}

• actual — peso declarado o medido.
• volumetric — peso volumétrico.
• chargeable — peso usado para el flete.
• billing_quantity — cantidad que el canal factura (puede ser peso, volumen o densidad).
• pricing_selector — cómo esa cantidad seleccionó una fila tarifaria. Los tipos coinciden con el catálogo WEIGHT / VOLUME / DENSITY.
• Los canales multi-paquete pueden redondear por caja y luego sumar. Cuando pricing_selector.scope es PER_PACKAGE, lea cada packages[].pricing_selector.

Cargos {#charges}

Servicios de entrada y salida

inbound_services y outbound_services corresponden a etapas distintas de los servicios de valor añadido del almacén. Los servicios de entrada se realizan durante la recepción, como fotos del paquete, grabación de vídeo o inspección. Los servicios de salida se realizan al preparar el envío, como refuerzo, envasado al vacío o embalaje con marco/caja de madera. Ambas etapas pueden aplicarse y cobrarse legítimamente al mismo paquete o envío.

Los importes de la cotización son solo estimaciones; solicitar una cotización no crea un cargo de servicio adicional. Los cargos definitivos dependen de los servicios realmente realizados y de su precio y liquidación finales. Use ambos grupos para estimar el coste total y concilie cada estimación con su cargo real correspondiente. No vuelva a sumar la estimación de un servicio individual sobre su cargo final.

Ejemplo en unidades menores de CNY: fotos del paquete 50 fen (¥0,50), inspección 100 fen (¥1,00), envasado al vacío 150 fen (¥1,50) y refuerzo del paquete 200 fen (¥2,00). Los cuatro pueden coexistir porque son servicios distintos realizados en etapas diferentes.

Cada grupo suele incluir:

channel_rules también puede incluir aggregation y cap. Use el subtotal del grupo: no lo sustituya sumando las líneas de reglas en bruto.

SUM_ALL suma todos los cargos coincidentes. HIGHEST_ONLY selecciona solo el mayor tras ordenar por importe descendente; las reglas con el mismo precio son equivalentes. cap=null significa sin límite. reason es solo para mostrar. Para lógica use condition_match, matched_conditions, rule_type, charge_mode, charge_value, outcome y missing_fields. Las reglas PENDING_INPUT, REVIEW_REQUIRED y otras no calculadas se excluyen del total conocido. amount=null no es cero y un charge_value configurado no es un cargo real.

Ítems de cargo

display_charges puede existir solo para la presentación frontend.

Motivos de no disponibilidad {#unavailable-reasons}

Valores comunes de unavailable_reason.code:

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

Los canales no disponibles permanecen en quotes[] para que pueda explicar por qué se rechazaron.

Terminología del catálogo {#catalog-terminology}

Atributos de artículo {#item-attributes}

GET /v1/fulfillment/shipments/item-attributes devuelve los códigos attributes[] válidos para las cotizaciones.

Errores {#errors}

No hay un código público distinto AUTHENTICATION_ERROR, WAREHOUSE_AUTH_REQUIRED ni WAREHOUSE_SERVICE_UNAVAILABLE. Use 401 INVALID_API_KEY, 403 WAREHOUSE_AUTH_INVALID y 502 WAREHOUSE_UPSTREAM_ERROR.

Un canal que no puede transportar este envío es una cotización UNAVAILABLE, no un fallo HTTP.

Relacionado {#related}

• Canales de envío — capacidades, cobertura y códigos de servicio
• Envíos — crear un envío después de que los paquetes estén en entrada
• Resumen de fulfillment