واجهة الشراء اليدوي

قناة واحدة، بائع واحد، أمر شراء واحد

يمكن أن يحتوي أمر الشراء على عدة منتجات أو وحدات SKU، لكن يجب أن تنتمي جميع العناصر إلى القناة نفسها والبائع نفسه.

إذا اشترى عميلك منتجات من بائعين أو قنوات مختلفة، فعلى تطبيقك تقسيمها إلى أوامر شراء مستقلة بحسب القناة والبائع قبل استدعاء API الطلبات في HIOBuy.

لا يقسّم HIOBuy أوامر الشراء تلقائيًا، ولا يوفّر API للطلبات المجمّعة لهذا المسار.

تحديد القناة والبائع

• استخدم channel على مستوى الطلب. يجب أن تتطابق القناة في المسار المختصر ومتن الطلب وبنود المنتجات. لا تخلط القنوات داخل lines[] أو items[].
• لتجميع المنتجات في تطبيق العميل، استخدم seller.id الحقيقي من API المنتجات عند توفره: مصدره sellerOpenId في 1688 وshop_id في تفاصيل Taobao. القيم البديلة المولّدة مثل seller_1688_* / seller_taobao_* أو غياب المعرّف أو اسم المنتج أو المتجر ليست أدلة موثوقة على هوية البائع. معرّفات متاجر Taobao ومعرّفات البائعين في استجابة تهيئة الطلب تنتمي إلى أنظمة تعريف مختلفة ولا يجوز مقارنتها مباشرة.
• لا يُضاف حقل بائع إلزامي جديد إلى طلب الإنشاء القياسي. في وضع self، تتحقق البوابة قبل الإنشاء الرسمي من بائع منتجات 1688 باستخدام التفاصيل الأصلية، ومن بائع Taobao باستخدام render_item_list[].seller_id مع التأكد من شمول جميع المنتجات ووحدات SKU المطلوبة. تُرفض العملية إذا كانت الأدلة ناقصة أو ملتبسة.
• في وضع الشراء عبر Warehouse، بما فيه الطلبات اليدوية، يتحقق المستودع من البائع قبل إنشاء الطلب أو بدء الشراء أو الخصم من المحفظة أو إرجاع نجاح جزئي. تفحص البوابة تعارضات القناة في الطلب الأصلي وتمرّر أخطاء المستودع دون تكرار الاستعلامات إلى المنصات. يلزم اختبار قبول مستقل للمستودع؛ نشر البوابة لا يثبت أن مستودعًا خارجيًا نفّذ هذا التحقق.
• تستخدم الطلبات اليدوية channel=manual، ويجب أيضًا أن تتشارك جميع العناصر قيمة source_platform واحدة. الحقل seller_name مجرد تصريح للعرض. على المستودع التحقق من البائع الحقيقي لكل منتج على المنصة أو إرجاع SELLER_ID_UNAVAILABLE. الاسم أو المعرّف الذي يصرّح به المستدعي لا يغني عن التحقق. لا تفعّل إنشاء الطلبات اليدوية قبل قبول عقد التكامل مع المستودع.

الأخطاء وطريقة معالجتها

تستخدم الأخطاء الثلاثة HTTP 400 والفئة VALIDATION_ERROR:

النص الإنجليزي الأصلي الذي تعيده API عند خلط الطلب:

A purchase order must contain products from the same channel and seller. Please split the items into separate orders by channel and seller.

عند رفض التحقق من البائع، يجب ألا يُنشأ أمر شراء أو مهمة شراء، وألا يحدث خصم من المحفظة أو نجاح جزئي. تظل قواعد منع التكرار الحالية سارية. يجب أن تكون لكل عملية شراء فُصلت عمدًا مرجع أعمال/مفتاح مستقل؛ وعند إعادة محاولة عملية لم تتغير، أعد استخدام المفتاح الأصلي.

الشراء وتجميع الشحنات

أوامر الشراء هي مشتريات محلية من بائعين منفردين. يمكن استلام منتجات الأوامر المنفصلة كطرود مستقلة ثم تجميعها في شحنة دولية واحدة، وفق شروط المستودع والشحن. التجميع لا يدمج أرقام الشراء الأصلية أو تكاليف النقل المحلي أو حالات الدفع والإلغاء والاسترداد.

طلب صحيح: عدة وحدات SKU لبائع موثّق واحد

يجب أن يثبت المستودع بصورة مستقلة أن رابطَي المنتج يعودان إلى بائع واحد ذي هوية ثابتة على المنصة. الروابط التوضيحية ليست إثباتًا لهوية البائع أو نتيجة قبول في الإنتاج.

{
  "channel": "manual",
  "external_order_id": "MANUAL-SELLER-A-001",
  "source_platform": "jd",
  "seller_name": "Seller A",
  "domestic_shipping_fee": 800,
  "currency": "CNY",
  "monetary_unit": "CNY_minor",
  "items": [
    {
      "product_url": "https://example.com/seller-A/shoe",
      "product_name": "Shoes",
      "specification": "Size 40",
      "unit_price": 5000,
      "quantity": 1
    },
    {
      "product_url": "https://example.com/seller-A/shoe",
      "product_name": "Shoes",
      "specification": "Size 41",
      "unit_price": 5000,
      "quantity": 1
    }
  ]
}

مثال خاطئ: البائعون الفعليون مختلفون

إذا كان items[0].product_url للبائع A وitems[1].product_url للبائع B، فعلى المستودع إرجاع MULTIPLE_SELLERS_NOT_ALLOWED حتى لو ورد seller_name: "Seller A" في الطلب. وإذا تعذّر التحقق من النسبة إلى البائع، أرجع SELLER_ID_UNAVAILABLE بدل قبول الاسم المصرّح به.

{
  "channel": "manual",
  "external_order_id": "INVALID-MIXED-001",
  "source_platform": "jd",
  "seller_name": "Seller A",
  "domestic_shipping_fee": 800,
  "currency": "CNY",
  "monetary_unit": "CNY_minor",
  "items": [
    {
      "product_url": "https://example.com/seller-A/shoe",
      "product_name": "Shoes",
      "specification": "Size 40",
      "unit_price": 5000,
      "quantity": 1
    },
    {
      "product_url": "https://example.com/seller-B/shirt",
      "product_name": "Shirt",
      "specification": "M",
      "unit_price": 3000,
      "quantity": 1
    }
  ]
}

يجب إعادة نتيجة رفض المستودع وفق عقد مرجع الأعمال/منع التكرار الحالي دون إنشاء طلب أو خصم. تحافظ الطلبات المنشأة سابقًا على سلوك إعادة الطلب والتفاصيل والدفع والإلغاء.

POST /v1/orders/manual

ينشئ كل طلب عملية شراء واحدة لمنصة واحدة وبائع واحد، ويمكن أن تضم عدة منتجات من البائع نفسه. المنصات المتاحة فقط jd وpinduoduo وpoizon، والحقل seller_name إلزامي. استخدم طلبات وأرقام شراء منفصلة عند اختلاف المنصة أو البائع.

يلزم Production API Key وصلاحية order:create ووضع warehouse وربط مستودع ساري. لا يلزم OAuth للمنصة. Sandbox غير مدعوم. يجب تنفيذ واجهة المستودع اليدوية والتحقق منها قبل الاستخدام.

الطلب

Authorization: Bearer <PRODUCTION_API_KEY>
Content-Type: application/json
Idempotency-Key: 6c14ce20-cf29-4c25-a9ee-3d36aac94c16

{
  "channel": "manual",
  "external_order_id": "EXT-10001",
  "source_platform": "jd",
  "seller_name": "Seller A",
  "domestic_shipping_fee": 800,
  "currency": "CNY",
  "monetary_unit": "CNY_minor",
  "language": "ar",
  "remark": "Please ship together",
  "items": [
    {
      "item_ref": "I001",
      "product_url": "https://example.com/item1",
      "product_name": "Wireless Mouse",
      "specification": "Black",
      "unit_price": 3500,
      "quantity": 2,
      "product_image": null,
      "remark": ""
    }
  ]
}

external_order_id إلزامي وفريد بين الطلبات اليدوية للتطبيق. الرقم والبيانات نفسهما يعيدان الطلب الموجود؛ تغيير البيانات يعيد HTTP 409 IDEMPOTENCY_CONFLICT. الشراء الجديد يحتاج رقماً جديداً. Idempotency-Key إلزامي للإنشاء والدفع والإلغاء. ينشئ HIOBuy الحقل order_sn ويمكن حذف item_ref. لا تقبل مصفوفة sellers أو تجاوز البائع والمنصة على مستوى المنتج.

مبالغ المستودع

المبالغ أعداد صحيحة بوحدة فن CNY: القيمة 3500 تساوي CNY 35.00. يحسب المستودع المنتجات والشحن المحلي ورسوم الشراء الحالية 5% والإجمالي. المثال لا يحدد أساس الرسوم أو الحد الأدنى أو التقريب. يحفظ HIOBuy المبالغ ولا يضيف 5% أخرى. المبالغ أو روابط المنتجات الناقصة تمنع الدفع.

{
  "channel": "manual",
  "success": true,
  "order_id": "WH10001",
  "order_sn": "HB202610160001",
  "external_order_id": "EXT-10001",
  "source_platform": "jd",
  "seller_name": "Seller A",
  "status": "wait_payment",
  "currency": "CNY",
  "monetary_unit": "CNY_minor",
  "total": {
    "merchandise": {
      "amount": 7000,
      "currency": "CNY"
    },
    "shipping": {
      "amount": 800,
      "currency": "CNY"
    },
    "procurement_fee": {
      "amount": 390,
      "currency": "CNY"
    },
    "payment": {
      "amount": 8190,
      "currency": "CNY"
    }
  },
  "order_list": [
    {
      "order_id": "WH10001",
      "shipping": {
        "amount": 800,
        "currency": "CNY"
      },
      "lines": [
        {
          "item_ref": "I001",
          "sub_order_id": "WI10001",
          "title": "Wireless Mouse",
          "spec_title": "Black",
          "quantity": 2,
          "unit_price": {
            "amount": 3500,
            "currency": "CNY"
          },
          "line_total": {
            "amount": 7000,
            "currency": "CNY"
          }
        }
      ]
    }
  ],
  "failed_offers": [],
  "request_id": "req_example"
}

عمليات الطلب الحالية

الإنشاء لا يخصم من المحفظة ولا يبدأ الشراء. استخدم order_id وchannel=manual مع واجهات الدفع والإلغاء والتفاصيل والتتبع المحلي الحالية. لا ترسل pay_amount. بعد مطابقة المبلغ المحفوظ ينفذ المستودع دفع المحفظة الحالي، ثم يبدأ الشراء بعد تأكيد الدفع فقط. الإلغاء لا يؤكد اكتمال رد الأموال.

• POST /v1/orders/pay
• POST /v1/orders/cancel
• POST /v1/orders/detail
• POST /v1/orders/logistics/trace

{
  "channel": "manual",
  "order_id": "WH10001"
}

{
  "channel": "manual",
  "order_id": "WH10001",
  "cancel_reason": "buyer_request"
}

إعادة المحاولة والحدود

عند انتهاء المهلة أو عدم وضوح النتيجة احتفظ بالرقم والمفتاح الأصليين واستعلم عن التفاصيل. لا تغير المفتاح تلقائياً للدفع مرة أخرى. تشمل التفاصيل payment_status ومراجع المنتجات والرسوم. قوائم طلبات المنصات وواجهات استردادها لا تدعم manual. الحدود: 1–100 بند، الكمية 1–9999، اسم البائع 200 حرف، اسم المنتج والمواصفات 500، الملاحظات 1000، وروابط HTTP/HTTPS بطول 2048. ترفض المبالغ النصية أو العشرية.

400 VALIDATION_ERROR · 403 FULFILLMENT_MODE_NOT_SUPPORTED / WAREHOUSE_AUTH_INVALID · 409 IDEMPOTENCY_CONFLICT / ORDER_AMOUNT_CHANGED / ORDER_OPERATION_UNRESOLVED · 502 WAREHOUSE_INVALID_RESPONSE · 503 WAREHOUSE_UNAVAILABLE

Webhooks

procurement.failed / procurement.out_of_stock

{
  "type": "procurement.failed",
  "data": {
    "channel": "manual",
    "order_id": "WH10001",
    "order_sn": "HB202610160001",
    "external_order_id": "EXT-10001",
    "source_platform": "jd",
    "seller_name": "Seller A",
    "status": "partial_failure",
    "reason_code": "OUT_OF_STOCK",
    "items": [
      {
        "item_ref": "I001",
        "sub_order_id": "WI10001",
        "quantity": 1,
        "reason_code": "OUT_OF_STOCK"
      }
    ]
  }
}