API عروض أسعار الشحن

يقدّر POST /v1/fulfillment/shipping/quotes الشحن الدولي انطلاقاً من الوجهة والوزن والأبعاد وسمات الصنف والخدمات.

استخدم الاختصار لطرد واحد عندما يكون تقسيم المستودع غير معروف. استخدم packages[] عندما يكون عدد الطرود وقياسات كل طرد معروفة مسبقاً.

تستخدم نقطة النهاية هذه المصطلحات نفسها للقناة والمنطقة والخدمة والفوترة والمال كما في API قنوات الشحن.

POSThttps://api.hiobuy.com/v1/fulfillment/shipping/quotes

عروض الأسعار ميزانيات وليست أسعاراً مقفلة. وزن المستودع وقياس الحجم وإعادة التغليف ومراجعة الخدمات قد تغيّر المبلغ النهائي. عرض السعر COMPLETE ما زال ليس قفلاً للسعر.

اسم مستعار للتوافق: POST /v1/fulfillment/shipments/freight/estimate (السلوك نفسه). فضّل /v1/fulfillment/shipping/quotes.

المال والوحدات {#units}

  • كل قيم المال amount أعداد صحيحة بوحدة fen لـ CNY. 5000 تعني ¥50.00.
  • monetary_unit في المستوى الأعلى دائماً CNY_minor.
  • كائنات المال تستخدم { "amount": 5000, "currency": "CNY" }.
  • وزن الطلب دائماً KG. أبعاد الطرد دائماً CM.
  • عرّف القنوات والخدمات بـ code المستقر، وليس name.

ترويسات الطلب {#request}

POST /v1/fulfillment/shipping/quotes
Authorization: Bearer hio_live_xxx
Content-Type: application/json
Language: en

لغة العرض هي ترويسة Language فقط. القيم المدعومة: en (الافتراضي)، en-US، zh، zh-CN، zh-TW، cn، hk. لا تضع language في جسم JSON أو سلسلة الاستعلام.

صيغتان للطلب {#request-formats}

لا تجمع حقول اختصار الطرد الواحد (weight_kg، length_cm، width_cm، height_cm) مع packages[]. ترفض الواجهة الطلب المختلط بـ 400 VALIDATION_ERROR.

الصيغة A — اختصار طرد واحد {#format-a}

استخدمها عندما تعرف الوجهة والوزن الإجمالي التقديري، لكنك لا تعرف كيف سيقسّم المستودع الصناديق.

طلب أدنى:

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

طرد واحد مع الأبعاد:

{
  "destination": {
    "country_code": "KR",
    "postal_code": "04524"
  },
  "weight_kg": 2.05,
  "length_cm": 30,
  "width_cm": 20,
  "height_cm": 10,
  "attributes": []
}
  • weight_kg هو وزن الشحنة التقديري بوحدة KG.
  • length_cm وwidth_cm وheight_cm بوحدة CM. قدّم الثلاثة كلها أو احذف الثلاثة كلها.
  • فضّل هذه الصيغة عندما يكون التقسيم النهائي في المستودع غير معروف. غياب الأبعاد قد ينتج PARTIAL أو REVIEW_REQUIRED للقنوات الحجمية.

الصيغة B — طرود معروفة {#format-b}

استخدم packages[] عندما تعرف مسبقاً عدد الصناديق وبيانات كل صندوق.

طرد مصرَّح به واحد:

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

عدة طرود:

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

قواعد packages[] (OpenAPI):

  • من 1 إلى 200 طرد.
  • عنصر واحد هو طرد واحد صريح. عدة عناصر هي شحنة متعددة الطرود صريحة.
  • reference اختياري، لكن يجب أن يكون فريداً داخل الطلب.
  • packages[].weight مطلوب. يجب أن يكون packages[].weight.unit هو KG.
  • packages[].dimensions اختياري. عند وجوده، length وwidth وheight وunit كلها مطلوبة. يجب أن يكون unit هو CM.

يربط Gateway الصيغة A بطرد مستودع واحد. تُتحقق الصيغة B وتُربط كما صُرِّح بها. التقسيم النهائي والأبعاد المقاسة تُحدَّد بعد معالجة المستودع.

حقول الطلب المشتركة {#shared-fields}

يجوز لكلتا الصيغتين تضمين ما يلي.

destination

الحقلمطلوبالوصف
country_codeنعمISO 3166-1 alpha-2، حرفان
subdivision_codeلامثلاً US-CA. يجب أن يطابق بادئة البلد country_code.
regionلااسم عرض التقسيم الإداري. يتقدّم subdivision_code الصالح.
postal_codeلاسلسلة. احتفظ بالأصفار البادئة.

declared_value

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

القيمة المصرَّح بها على مستوى الشحنة بوحدة fen لـ CNY كعدد صحيح. احذف الحقل عندما تكون غير معروفة. لا ترسل 0 لتعني غير معروف.

attributes

مصفوفة رموز سمات صنف مستقرة من GET /v1/fulfillment/shipments/item-attributes. سلاسل فريدة، بحد أقصى 100.

تقتصر عروض الأسعار أولاً على القنوات المناسبة لـ destination.country_code، وتُحذف قنوات الدول الأخرى. تقيّم كل قناة متبقية السمات المعلنة بشكل مستقل. تؤدي السمة غير المدعومة إلى UNAVAILABLE مع ATTRIBUTE_NOT_SUPPORTED، بينما قد تعيد القنوات الأخرى المناسبة عروضاً عادية.

services

{
  "services": {
    "channel": [
      {
        "code": "LINE_INSURANCE",
        "quantity": 1
      }
    ],
    "outbound": [
      {
        "code": "VACUUM_PACKING",
        "quantity": 1
      }
    ],
    "inbound": [
      {
        "code": "PHOTO",
        "quantity": 3
      }
    ]
  }
}
المجموعةالمعنى
channelخدمات القيمة المضافة للقناة. الرموز من القنوات value_added_services[].code.
outboundمعالجة المستودع الصادرة
inboundمعالجة المستودع الواردة

كل عنصر يتطلب code وquantity. OpenAPI: quantity عدد صحيح من 1 إلى 999. يجب أن تكون الرموز فريدة داخل كل مجموعة.

channel_codes

رموز قنوات مستقرة تقيّد مجموعة عروض الأسعار. احذفها لتسعير كل القنوات المرشحة. لا ترسل مصفوفة فارغة. رمز غير معروف أو غير قابل للوصول يعيد 400 INVALID_SHIPPING_CHANNEL للطلب بأكمله.

مثال طلب كامل {#complete-request}

الصيغة A مع الوجهة والأبعاد والقيمة المصرَّح بها والسمات والخدمات ومرشح قناة:

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

الاستجابة {#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."
}

الحقول العليا

الحقلالوصف
successtrue عند تقدير ناجح، بما في ذلك عندما تكون بعض العروض UNAVAILABLE.
estimate_typeDECLARED — استناداً إلى البيانات المصرَّح بها، وليس قياس المستودع.
completenessمدى اكتمال الإدخال. ليس ضماناً للتسليم.
warningsتحذيرات على مستوى الشحنة.
quotesنتائج لكل قناة: الكاملة أولاً، ثم الجزئية/المراجعة، ثم غير المتاحة.
monetary_unitدائماً CNY_minor.
generated_atطابع زمني للاستجابة.
request_idللربط مع x-request-id.
disclaimerإخلاء مسؤولية التقدير بصيغة مقروءة.

completeness

الحقلالمعنى
levelتغطية الإدخال الإجمالية، مثلاً HIGH.
destinationمدى اكتمال الوجهة (COMPLETE عند وجود البلد).
package_dimensionsما إذا قُدِّم الطول/العرض/الارتفاع.
package_splitDECLARED عندما أرسلت packages[]؛ الاختصار يفترض طرداً واحداً.
declared_valuePROVIDED أو محذوف/غير معروف.
attributesما إذا صُرِّح بسمات الصنف.
servicesREQUESTED_ONLY عندما أرسلت خدمات مختارة؛ يجوز للمستودع إضافة المزيد.

حالة عرض السعر {#quote-status}

لا تقرر من available وحده. اقرأ دائماً quote_status.

quote_statusavailabletotalالمعنى
COMPLETEtrueكائن مالميزانية كاملة يمكنك عرضها. ما زالت غير مقفلة.
PARTIALtrueعادةً nullمدخلات ناقصة. اقرأ التحذيرات وأضف الأبعاد أو الرمز البريدي أو القيمة المصرَّح بها.
REVIEW_REQUIREDtrueعادةً nullيلزم قياس المستودع أو مراجعة بشرية.
UNAVAILABLEfalsenullلا يمكن لهذه القناة تقديم عرض. طلب HTTP نجح مع ذلك.
  • total هو الميزانية الكاملة عندما تكون معروفة.
  • known_total هو مجموع الرسوم التي يمكن حسابها الآن.
  • عندما يكون total هو null، لا تعامل known_total كعرض سعر كامل.
  • unavailable_reason.code للمعالجة البرمجية.
  • unavailable_reason.message للعرض فقط.

UNAVAILABLE على عرض واحد ليس خطأ HTTP.

كائن عرض السعر {#quotes}

الحقلالوصف
channel{ code, name, description, tags, capabilities } — الهوية نفسها كما في كتالوج القنوات.
channel.capabilities.delivery_methodsمصفوفة اختيارية متوافقة مع الإصدارات السابقة لرموز التسليم الثابتة: DOOR_DELIVERY وPICKUP وPOST_OFFICE_PICKUP. قد تظهر مع أي حالة عرض، ويمكن للعملاء الحاليين تجاهلها.
availableما إذا أنتجت هذه القناة تقديراً قابلاً للاستخدام. اقرنه بـ quote_status.
quote_statusCOMPLETE · PARTIAL · REVIEW_REQUIRED · UNAVAILABLE.
unavailable_reason{ code, message } أو null.
attribute_evaluationنتيجة اختيارية لكل قناة: SUPPORTED أو UNSUPPORTED أو NOT_DECLARED، مع قوائم السمات المعلنة والمقبولة وغير المدعومة.
matched_region{ code, name, match_type } أو null.
packagesالطرود المصرَّح بها أو المربوطة مع أوزان كل طرد.
weightsactual / volumetric / chargeable على مستوى الشحنة بوحدة KG.
billing_quantityالكمية التي تفوترها القناة فعلياً، بوحدة KG أو M3 أو KG_PER_M3.
pricing_selectorكيف أصابت تلك الكمية نطاقاً في بطاقة الأسعار (type، value، unit، scope).
transit_timeزمن عبور مرجعي.
chargesمجموعات الرسوم. انظر أدناه.
display_chargesصفوف اختيارية للواجهة فقط. إذا كانت included_in_total هي false، لا تضفها إلى total.
total / known_totalالميزانية الكاملة مقابل الرسوم المعروفة حالياً.
warningsتحذيرات على مستوى القناة.
service_adjustment_possibletrue إذا كانت معالجة المستودع قد تغيّر الخدمات والرسوم بعد.

الأوزان وكمية الفوترة {#weights}

  • actual — الوزن المصرَّح به أو المقاس.
  • volumetric — الوزن الحجمي.
  • chargeable — الوزن المستخدم للشحن.
  • billing_quantity — الكمية التي تفوترها القناة (قد تكون وزناً أو حجماً أو كثافة).
  • pricing_selector — كيف اختارت تلك الكمية صف سعر. الأنواع تطابق الكتالوج WEIGHT / VOLUME / DENSITY.
  • قد تقرّب القنوات متعددة الطرود لكل صندوق ثم تجمع. عندما يكون pricing_selector.scope هو PER_PACKAGE، اقرأ كل packages[].pricing_selector.

الرسوم {#charges}

المجموعةالمعنى
base_freightالشحن الدولي الأساسي
channel_servicesخدمات القناة الإلزامية والمختارة من المطوّر
channel_rulesالحجم الزائد والوزن الزائد والقيمة المصرَّح بها وقواعد المسار الأخرى
outbound_servicesخدمات ذات قيمة مضافة أثناء تجهيز الشحنة / المعالجة الصادرة
inbound_servicesخدمات ذات قيمة مضافة أثناء الاستلام / المعالجة الواردة في المستودع
adjustmentsالتعديلات

خدمات الإدخال والإخراج

يمثّل inbound_services وoutbound_services مرحلتين مختلفتين من خدمات المستودع ذات القيمة المضافة. تُنفّذ خدمات الإدخال أثناء استلام المستودع، مثل صور الطرد أو تسجيل الفيديو أو الفحص. وتُنفّذ خدمات الإخراج أثناء تجهيز الشحنة، مثل تدعيم الطرد أو التغليف بالتفريغ أو التغليف بإطار/صندوق خشبي. ويمكن تطبيق خدمات المرحلتين واحتسابها بصورة مشروعة للطرد أو الشحنة نفسها.

المبالغ الظاهرة في Shipping Quote تقديرية فقط؛ ولا يؤدي طلب عرض السعر بحد ذاته إلى إنشاء رسوم خدمة إضافية. تُحدَّد الرسوم النهائية وفق الخدمات المنفذة فعلياً وتسعيرها وتسويتها النهائية. استخدم المجموعتين لتقدير إجمالي تكلفة التنفيذ، ثم طابق كل تقدير مع رسمه الفعلي المقابل. لا تضف تقدير الخدمة الفردية مرة أخرى فوق رسمها النهائي.

مثال بوحدات CNY الصغرى: صور الطرد 50 فن (¥0.50)، الفحص 100 فن (¥1.00)، التغليف بالتفريغ 150 فن (¥1.50)، وتدعيم الطرد 200 فن (¥2.00). يمكن أن تظهر البنود الأربعة معاً لأنها خدمات مختلفة تُنفّذ في مراحل تنفيذ مختلفة.

تتضمن كل مجموعة عادةً:

الحقلالمعنى
amountإجمالي المجموعة بوحدة fen، أو null إذا كان غير معروف
currencyCNY
known_amountمجموع العناصر التي يمكن حسابها الآن
calculation_statusمثلاً CALCULATED
itemsبنود السطر

قد تتضمن channel_rules أيضاً aggregation وcap. استخدم المجموع الفرعي للمجموعة — لا تستبدله بجمع بنود القواعد الخام.

يجمع SUM_ALL كل الرسوم المطابقة. يختار HIGHEST_ONLY أعلى مبلغ فقط بعد الترتيب التنازلي، وتعد القواعد المتساوية في السعر متكافئة. يعني cap=null عدم وجود سقف. reason للعرض فقط. استخدم في منطق البرنامج condition_match وmatched_conditions وrule_type وcharge_mode وcharge_value وoutcome وmissing_fields. تستبعد قواعد PENDING_INPUT وREVIEW_REQUIRED وغيرها من القواعد غير المحسوبة من المجموع المعروف. amount=null لا يعني صفراً، وcharge_value المهيأ ليس رسماً فعلياً.

بنود الرسوم

الحقلالمعنى
codeرمز رسوم أو خدمة مستقر
nameاسم العرض المترجم
categoryفئة الرسوم
sourceMANDATORY · DEVELOPER_SELECTED · RULE_ENGINE
pricing_basisكيف سُعِّر السطر
quantityالكمية القابلة للفوترة للسطر
unit_priceسعر الوحدة بوحدة fen عندما يكون معروفاً
amountإجمالي السطر. null تعني غير معروف، وليست صفراً.
estimatedما إذا كان السطر ما زال تقديراً
calculation_statusحالة الحساب
affected_by_packagesما إذا كان عدد الطرود/حجمها يمكن أن يغيّر هذا السطر
included_in_totalإذا كانت false، لا تضفه مرة أخرى إلى total

قد توجد display_charges للعرض الأمامي فقط.

أسباب عدم التوفر {#unavailable-reasons}

قيم 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

تبقى القنوات غير المتاحة في quotes[] حتى تتمكن من شرح سبب رفضها.

مصطلحات الكتالوج {#catalog-terminology}

قنوات الشحنواجهة البرمجة هذهالمعنى
items[].code/name/description/tagsquotes[].channel.*القناة نفسها
regions[].code/name/match_typequotes[].matched_region.*المنطقة التي اختارها عرض السعر
value_added_services[].codeservices.channel[].code وcode للرسومرمز الخدمة المستقر
billing.quantity_unitbilling_quantity.unit / pricing_selector.unitوحدة الفوترة
rule_summary.aggregationcharges.channel_rules.aggregationتجميع القواعد
rule_summary.capcharges.channel_rules.capالسقف بعد التجميع؛ null يعني بلا سقف

سمات الصنف {#item-attributes}

يعيد GET /v1/fulfillment/shipments/item-attributes رموز attributes[] الصالحة لعروض الأسعار.

الأخطاء {#errors}

HTTPerror.codeمتى
400VALIDATION_ERRORبنية غير صالحة، أو صيغ طلب مختلطة، أو وحدات KG/CM، أو رموز مكررة، أو channel_codes فارغ
400INVALID_SHIPPING_CHANNELقيمة channel_codes مطلوبة غير معروفة أو غير مرئية للتطبيق
401INVALID_API_KEYرمز Bearer مفقود أو غير صالح
403FULFILLMENT_MODE_NOT_SUPPORTEDالتطبيق يستخدم self fulfillment
403WAREHOUSE_AUTH_INVALIDتفويض المستودع مفقود أو مرفوض أو منتهٍ
422INVALID_COUNTRY_CODEبلد الوجهة غير صالح
422INVALID_ITEM_ATTRIBUTEرمز سمة غير صالح
502WAREHOUSE_UPSTREAM_ERRORفشلت خدمة المستودع؛ أعد المحاولة مع backoff

لا يوجد رمز عام مستقل AUTHENTICATION_ERROR أو WAREHOUSE_AUTH_REQUIRED أو WAREHOUSE_SERVICE_UNAVAILABLE. استخدم 401 INVALID_API_KEY و403 WAREHOUSE_AUTH_INVALID و502 WAREHOUSE_UPSTREAM_ERROR.

القناة التي لا تستطيع حمل هذه الشحنة هي عرض سعر UNAVAILABLE، وليست إخفاق HTTP.

Get Support

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

Email support