API für manuelle Beschaffung

Ein Kanal, ein Verkäufer, eine Beschaffungsbestellung

Eine Beschaffungsbestellung darf mehrere Produkte oder SKU enthalten, aber alle Positionen müssen demselben Kanal und Verkäufer zugeordnet sein.

Kauft Ihr Kunde bei verschiedenen Verkäufern oder über verschiedene Kanäle, muss Ihre Anwendung die Artikel vor dem Aufruf der HIOBuy-Bestell-API in getrennte Beschaffungsbestellungen aufteilen.

HIOBuy teilt Beschaffungsbestellungen nicht automatisch auf und bietet für diesen Ablauf keine Sammelbestell-API an.

Kanal und Verkäufer bestimmen

• Verwenden Sie das channel-Feld der Bestellung. Kanal-Kurzpfad, Anfrageinhalt und Positionen müssen übereinstimmen. Mischen Sie keine Kanäle in lines[] oder items[].
• Nutzen Sie zur Gruppierung im Client nach Möglichkeit die echte seller.id der Produkt-API: bei 1688 stammt sie aus sellerOpenId, bei Taobao-Produktdetails aus shop_id. Generierte Ersatzwerte wie seller_1688_* / seller_taobao_*, fehlende IDs, Produkttitel oder Shopnamen sind kein zuverlässiger Identitätsnachweis. Taobao-Shop-IDs und Verkäufer-IDs aus der Vorschau verwenden unterschiedliche Kennungssysteme und dürfen nicht verglichen werden.
• Die Standardanfrage erhält kein neues Pflichtfeld für den Verkäufer. Im Modus self prüft das Gateway vor der offiziellen Bestellung die 1688-Zuordnung anhand der ursprünglichen Produktdetails. Bei Taobao verwendet es render_item_list[].seller_id und prüft die vollständige Abdeckung aller angeforderten Produkte und SKU. Fehlende oder mehrdeutige Nachweise führen zur Ablehnung.
• Bei der Warehouse-Beschaffung, einschließlich manueller Bestellungen, prüft das Lager den Verkäufer vor Bestellerstellung, Beschaffung, Wallet-Belastung oder Teilerfolg. Das Gateway prüft Kanalkonflikte in der ursprünglichen Anfrage und reicht Lagerfehler ohne erneute Plattformabfragen weiter. Eine gesonderte Lagerabnahme ist erforderlich; ein bereitgestelltes Gateway belegt nicht, dass ein externes Lager diese Prüfung bereits umsetzt.
• Manuelle Bestellungen verwenden channel=manual; alle Artikel müssen außerdem dieselbe source_platform haben. seller_name ist nur eine Anzeigeangabe. Das Lager muss den tatsächlichen Plattformverkäufer jedes Artikels bestimmen oder SELLER_ID_UNAVAILABLE zurückgeben. Ein vom Aufrufer angegebener Name oder eine ID ersetzt diese Prüfung nicht. Aktivieren Sie die manuelle Erstellung erst nach Abnahme des Lagervertrags.

Fehler und empfohlene Maßnahmen

Alle drei Fehler verwenden HTTP 400 und die Kategorie VALIDATION_ERROR:

Englischer Originaltext der API bei einer gemischten Bestellung:

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

Eine Ablehnung wegen des Verkäufers darf weder Bestellung noch Beschaffungsauftrag, Wallet-Belastung oder Teilerfolg erzeugen. Die bisherigen Idempotenzregeln gelten weiter. Jeder bewusst getrennte Einkauf benötigt eine eigene Geschäftsreferenz/einen eigenen Schlüssel; wiederholen Sie einen unveränderten Einkauf mit dem ursprünglichen Schlüssel.

Beschaffung und zusammengefasster Versand

Beschaffungsbestellungen sind Inlandskäufe bei einzelnen Verkäufern. Waren aus getrennten Bestellungen können als einzelne Lagerpakete eingehen und später unter Einhaltung der Lager- und Versandbedingungen zu einer internationalen Sendung zusammengefasst werden. Dabei bleiben ursprüngliche Bestellnummern, Inlandsfracht sowie Zahlungs-, Storno- und Erstattungsstatus getrennt.

Gültige Anfrage: mehrere SKU eines geprüften Verkäufers

Das Lager muss unabhängig bestätigen, dass beide Produkt-URLs zu einem einzigen stabilen Plattformverkäufer gehören. Die Beispiel-URLs belegen weder die Verkäuferidentität noch eine Produktionsabnahme.

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

Ungültiges Beispiel: unterschiedliche tatsächliche Verkäufer

Gehört items[0].product_url Verkäufer A und items[1].product_url Verkäufer B, muss das Lager auch bei seller_name: "Seller A" den Fehler MULTIPLE_SELLERS_NOT_ALLOWED zurückgeben. Ist die Zuordnung nicht prüfbar, ist SELLER_ID_UNAVAILABLE zurückzugeben, statt dem angegebenen Namen zu vertrauen.

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

Eine Verkäuferablehnung des Lagers muss nach dem bestehenden Geschäftsreferenz-/Idempotenzvertrag wiedergegeben werden, ohne Bestellung oder Belastung. Für bereits erstellte Bestellungen bleiben Wiederholung, Abfrage, Zahlung und Stornierung kompatibel.

POST /v1/orders/manual

Eine Anfrage erstellt eine Bestellung für eine Plattform und einen Verkäufer mit mehreren Artikeln dieses Verkäufers. Nur jd, pinduoduo und poizon sind freigegeben; seller_name ist Pflicht. Andere Plattformen oder Verkäufer erfordern getrennte Bestellnummern.

Production API Key, order:create, warehouse-Modus und aktive Lagerbindung sind erforderlich. Kein Marketplace-OAuth nötig. Sandbox wird nicht unterstützt. Das Lager muss seine manuelle API vor der Nutzung implementieren und prüfen.

Anfrage

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": "de",
  "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 ist innerhalb der manuellen Bestellungen einer App eindeutig und Pflicht. Gleiche Nummer und Daten liefern die vorhandene Bestellung; geänderte Daten ergeben HTTP 409 IDEMPOTENCY_CONFLICT. Neuer Einkauf: neue Nummer. Idempotency-Key ist für Erstellen, Bezahlen und Stornieren Pflicht. HIOBuy erzeugt order_sn; item_ref ist optional. sellers-Arrays und Verkäuferangaben je Artikel sind unzulässig.

Lagerbeträge

Beträge sind ganze CNY-Fen: 3500 = CNY 35.00. Das Lager berechnet Ware, Inlandsversand, bestehende 5-%-Gebühr und Endbetrag. Das Beispiel legt weder Basis noch Mindestgebühr oder Rundung fest. HIOBuy speichert Beträge und addiert keine weiteren 5 %. Unvollständige Beträge oder Artikelzuordnungen verhindern Zahlung.

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

Bestehende Vorgänge

Erstellen belastet kein Guthaben und startet keine Beschaffung. Verwenden Sie order_id und channel=manual mit bestehenden Zahlungs-, Storno-, Detail- und Inlandsverfolgungs-APIs. Kein pay_amount senden. Nach Abgleich des gespeicherten Betrags führt das Lager die bestehende Wallet-Zahlung aus; erst nach Bestätigung beginnt der Einkauf. Stornierung bestätigt keine Erstattung.

• 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"
}

Wiederholungen und Grenzen

Bei Timeout oder unbekanntem Ergebnis Nummer und Schlüssel beibehalten und Details abfragen. Nicht automatisch mit neuem Schlüssel erneut zahlen. Details enthalten payment_status, Artikelreferenzen und Gebühren. Marketplace-Listen und -Erstattungen unterstützen manual nicht. Grenzen: 1–100 Positionen, Menge 1–9999, Verkäufername 200 Zeichen, Produktname und Spezifikation 500, Hinweise 1000, HTTP/HTTPS-URL 2048. Text- und Dezimalbeträge werden abgewiesen.

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