API für Versandangebote

POST /v1/fulfillment/shipping/quotes schätzt den internationalen Versand anhand von Zielort, Gewicht, Maßen, Artikelattributen und Diensten.

Verwenden Sie die Einzelpaket-Kurzform, wenn die Lageraufteilung unbekannt ist. Verwenden Sie packages[], wenn Paketanzahl und Maße je Paket bereits bekannt sind.

Dieser Endpunkt verwendet dieselbe Terminologie für Kanal, Region, Dienst, Abrechnung und Geld wie die API für Versandkanäle.

Angebote sind Budgets, keine festgeschriebenen Preise. Wiegung im Lager, Volumenmessung, Umverpackung und Leistungsprüfung können den Endbetrag ändern. Ein Angebot mit COMPLETE ist weiterhin keine Preissperre.

Kompatibilitätsalias: POST /v1/fulfillment/shipments/freight/estimate (gleiches Verhalten). Bevorzugen Sie /v1/fulfillment/shipping/quotes.

Geld und Einheiten {#units}

• Alle Geldwerte amount sind ganzzahlige CNY-Fen. 5000 bedeutet ¥50.00.
• Das Top-Level-Feld monetary_unit ist immer CNY_minor.
• Geldobjekte verwenden { "amount": 5000, "currency": "CNY" }.
• Das Anfragegewicht ist immer KG. Paketmaße sind immer CM.
• Identifizieren Sie Kanäle und Dienste über den stabilen code, nicht über name.

Anfrage-Header {#request}

POST /v1/fulfillment/shipping/quotes
Authorization: Bearer hio_live_xxx
Content-Type: application/json
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 den JSON-Body oder in die Query-Zeichenfolge.

Zwei Anfrageformate {#request-formats}

Kombinieren Sie die Felder der Einzelpaket-Kurzform (weight_kg, length_cm, width_cm, height_cm) nicht mit packages[]. Die API lehnt eine gemischte Anfrage mit 400 VALIDATION_ERROR ab.

Format A — Einzelpaket-Kurzform {#format-a}

Verwenden Sie dieses Format, wenn Sie Zielort und geschätztes Gesamtgewicht kennen, aber nicht, wie das Lager die Kartons aufteilen wird.

Minimale Anfrage:

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

Einzelpaket mit Maßen:

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

• weight_kg ist das geschätzte Sendungsgewicht in KG.
• length_cm, width_cm und height_cm sind CM. Geben Sie alle drei an oder lassen Sie alle drei weg.
• Bevorzugen Sie dieses Format, wenn die endgültige Lageraufteilung unbekannt ist. Fehlende Maße können bei volumetrischen Kanälen PARTIAL oder REVIEW_REQUIRED erzeugen.

Format B — bekannte Pakete {#format-b}

Verwenden Sie packages[], wenn Sie Kartonanzahl und Daten jedes Kartons bereits kennen.

Ein deklariertes Paket:

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

Mehrere Pakete:

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

Regeln für packages[] (OpenAPI):

• 1–200 Pakete.
• Ein Element ist ein explizites Einzelpaket. Mehrere Elemente sind eine explizite Mehrpaketsendung.
• reference ist optional, muss aber innerhalb der Anfrage eindeutig sein.
• packages[].weight ist erforderlich. packages[].weight.unit muss KG sein.
• packages[].dimensions ist optional. Wenn vorhanden, sind length, width, height und unit alle erforderlich. unit muss CM sein.

Das Gateway mappt Format A auf ein einzelnes Lagerpaket. Format B wird validiert und wie deklariert gemappt. Endgültige Aufteilung und gemessene Maße werden weiterhin nach der Lagerbearbeitung bestimmt.

Gemeinsame Anfragefelder {#shared-fields}

Beide Formate können Folgendes enthalten.

destination

declared_value

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

Deklarierter Wert auf Sendungsebene in ganzzahligen CNY-Fen. Lassen Sie das Feld weg, wenn unbekannt. Senden Sie nicht 0, um „unbekannt“ auszudrücken.

attributes

Array stabiler Artikelattribut-Codes aus GET /v1/fulfillment/shipments/item-attributes. Eindeutige Zeichenfolgen, maximal 100.

Angebote werden zuerst auf Kanäle beschränkt, die für destination.country_code gelten; Kanäle anderer Länder werden weggelassen. Jeder verbleibende Kanal bewertet die deklarierten Attribute separat. Nicht unterstützte Attribute führen zu UNAVAILABLE mit ATTRIBUTE_NOT_SUPPORTED, während andere passende Kanäle weiterhin Angebote liefern können.

services

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

Jedes Element erfordert code und quantity. OpenAPI: quantity ist eine Ganzzahl von 1 bis 999. Codes müssen innerhalb jeder Gruppe eindeutig sein.

channel_codes

Stabile Kanalcodes, die die Angebotsmenge einschränken. Lassen Sie das Feld weg, um alle Kandidatenkanäle anzubieten. Senden Sie kein leeres Array. Ein unbekannter oder nicht zugänglicher Code liefert 400 INVALID_SHIPPING_CHANNEL für die gesamte Anfrage.

Vollständiges Anfragebeispiel {#complete-request}

Format A mit Zielort, Maßen, deklariertem Wert, Attributen, Diensten und einem Kanalfilter:

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

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

Felder auf oberster Ebene

completeness

Angebotsstatus {#quote-status}

Entscheiden Sie nicht allein anhand von available. Lesen Sie immer quote_status.

• total ist das vollständige Budget, wenn bekannt.
• known_total ist die Summe der Gebühren, die jetzt berechnet werden können.
• Wenn total null ist, behandeln Sie known_total nicht als vollständiges Angebot.
• unavailable_reason.code dient der programmatischen Verarbeitung.
• unavailable_reason.message ist nur zur Anzeige.

UNAVAILABLE bei einem Angebot ist kein HTTP-Fehler.

Angebotsobjekt {#quotes}

Gewichte und Abrechnungsmenge {#weights}

• actual — deklariertes oder gemessenes Gewicht.
• volumetric — Volumengewicht.
• chargeable — für die Fracht verwendetes Gewicht.
• billing_quantity — Menge, die der Kanal abrechnet (kann Gewicht, Volumen oder Dichte sein).
• pricing_selector — wie diese Menge eine Tarifzeile ausgewählt hat. Typen entsprechen dem Katalog WEIGHT / VOLUME / DENSITY.
• Mehrpaket-Kanäle können pro Karton runden und anschließend summieren. Wenn pricing_selector.scope PER_PACKAGE ist, lesen Sie jedes packages[].pricing_selector.

Gebühren {#charges}

Eingangs- und Ausgangsleistungen

inbound_services und outbound_services sind verschiedene Stufen der Lager-Zusatzleistungen. Eingangsleistungen werden beim Wareneingang erbracht, z. B. Paketfotos, Videoaufnahmen oder Prüfung. Ausgangsleistungen werden bei der Versandvorbereitung erbracht, z. B. Verstärkung, Vakuumverpackung oder Holzrahmen-/Holzkistenverpackung. Leistungen aus beiden Stufen können für dasselbe Paket bzw. dieselbe Sendung anfallen und berechnet werden.

Die Beträge im Versandangebot sind nur Schätzungen; die Angebotsabfrage selbst erzeugt keine zusätzliche Servicegebühr. Maßgeblich sind die tatsächlich ausgeführten Leistungen und deren endgültige Preisberechnung und Abrechnung. Verwenden Sie beide Gruppen zur Kostenschätzung und gleichen Sie jede Schätzung mit der entsprechenden tatsächlichen Gebühr ab. Addieren Sie die Schätzung einer einzelnen Leistung nicht erneut zu deren endgültiger Gebühr.

Beispiel in CNY-Untereinheiten: Paketfotos 50 Fen (¥0,50), Prüfung 100 Fen (¥1,00), Vakuumverpackung 150 Fen (¥1,50) und Paketverstärkung 200 Fen (¥2,00). Alle vier können gleichzeitig vorkommen, da es sich um unterschiedliche Leistungen in verschiedenen Fulfillment-Stufen handelt.

Jede Gruppe enthält typischerweise:

channel_rules kann auch aggregation und cap enthalten. Verwenden Sie die Gruppensumme — ersetzen Sie sie nicht durch das Aufsummieren der Rohregelpositionen.

SUM_ALL summiert alle Treffer. HIGHEST_ONLY wählt nach absteigendem Betrag nur den höchsten; gleich teure Regeln sind gleichwertig. cap=null bedeutet ohne Obergrenze. reason ist nur zur Anzeige bestimmt. Verwenden Sie für Programmlogik condition_match, matched_conditions, rule_type, charge_mode, charge_value, outcome und missing_fields. PENDING_INPUT, REVIEW_REQUIRED und andere unberechnete Regeln sind von der bekannten Summe ausgeschlossen. amount=null ist nicht null Euro, und ein konfigurierter charge_value ist keine tatsächliche Gebühr.

Gebührenpositionen

display_charges kann nur für die Frontend-Darstellung existieren.

Nichtverfügbarkeitsgründe {#unavailable-reasons}

Häufige Werte von 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

Nicht verfügbare Kanäle bleiben in quotes[], damit Sie erklären können, warum sie abgelehnt wurden.

Katalogterminologie {#catalog-terminology}

Artikelattribute {#item-attributes}

GET /v1/fulfillment/shipments/item-attributes liefert die gültigen Codes für attributes[] in Angeboten.

Fehler {#errors}

Es gibt keinen eigenen öffentlichen Code AUTHENTICATION_ERROR, WAREHOUSE_AUTH_REQUIRED oder WAREHOUSE_SERVICE_UNAVAILABLE. Verwenden Sie 401 INVALID_API_KEY, 403 WAREHOUSE_AUTH_INVALID und 502 WAREHOUSE_UPSTREAM_ERROR.

Ein Kanal, der diese Sendung nicht befördern kann, ist ein UNAVAILABLE-Angebot, kein HTTP-Fehler.

Verwandt {#related}

• Versandkanäle — Fähigkeiten, Abdeckung und Dienstcodes
• Sendungen — eine Sendung erstellen, nachdem Pakete eingegangen sind
• Fulfillment-Übersicht