AI-Bestell-API

Nachdem der Kunde im Chat Produkte ausgewählt hat, entwirft die AI eine Bestellung zur Bestätigung durch den Kunden. Nach der Bestätigung bitten wir Ihr System, eine Bestellung mit ausstehender Zahlung anzulegen, und übergeben dem Kunden den von Ihnen zurückgegebenen Zahlungslink. Wir speichern keine Bestellungen und wickeln keine Zahlungen ab.

Im Backend unter „Bot-Einstellungen“ tragen Sie die Bestell-API ein (ohne Eintrag kann die AI keine Bestellungen aufgeben). Optional können Sie die URL der Anmeldeseite eintragen: Wenn ein nicht angemeldeter Kunde bestellen möchte, erscheint im Chatfenster die Schaltfläche „Anmelden“.

Voraussetzungen:

• Nur angemeldete Kunden können Bestellungen aufgeben. user_id stammt aus dem von Ihnen ausgestellten user_token (siehe Angemeldete Kunden erkennen).
• Produkte müssen über die offene API synchronisiert werden (siehe Wissensdatenbank und Produkte); Produkte mit Varianten müssen variants[].sku enthalten. Beim Anlegen der Bestellung übergeben wir sku unverändert an Sie.

So bestätigen Kunden:

• Web-Chatfenster: Nachdem die AI die Bestellung entworfen hat, wird eine Bestellkarte angezeigt. Die Bestellung wird erst angelegt, wenn der Kunde auf „Bestellung bestätigen“ klickt; nach dem Anlegen erscheint auf der Karte die Schaltfläche „Zur Zahlung“.
• Kanäle wie WeChat Mini Programs, die nur Text senden können: Die AI sendet dem Kunden eine Bestellübersicht. Die Bestellung wird erst angelegt, nachdem der Kunde mit „Bestätigen“ antwortet; nach dem Anlegen wird der Zahlungseinstieg gesendet (siehe unten mp_path).

Anfrage

Dieselbe URL; mode unterscheidet zwischen Preisberechnung und Bestellanlage. Signatur und Signaturprüfung entsprechen der Bestellabfrage-API; Timeout: 10 Sekunden.

POST {你的下单接口}
Content-Type: application/json
X-AICS-Timestamp: 1761120000
X-AICS-Signature: v1=<hex>

{
  "mode": "quote",
  "request_id": "chk_3f2a9c...",
  "user_id": "u_123",
  "conversation_id": "b3c1...",
  "channel": "widget",
  "language": "en",
  "country": "US",
  "items": [{"product_id": "w1", "sku": "w1-black", "qty": 1}]
}

Antwort

Preisberechnung erfolgreich:

{
  "status": "quoted",
  "currency": "USD",
  "goods_amount": "399.00",
  "discount": "20.00",
  "discounts": [{"label": "新客券", "amount": "20.00"}],
  "shipping_fee": "0",
  "tax": "0",
  "total": "379.00"
}

Bestellung erfolgreich angelegt:

{
  "status": "created",
  "order_no": "T2026102300001",
  "pay_url": "https://shop.example.com/pay?orderno=T2026102300001",
  "mp_path": "pages/order/pay?orderno=T2026102300001",
  "expires_at": "2026-10-23T12:30:00Z",
  "currency": "USD",
  "goods_amount": "399.00",
  "discount": "20.00",
  "shipping_fee": "0",
  "tax": "0",
  "total": "379.00"
}

Bestellung nicht möglich:

{"status": "rejected", "code": "OUT_OF_STOCK", "message": "这款黑色暂时缺货"}

• Alle Beträge sind Zeichenketten. total und currency sind Pflichtfelder, alle übrigen Felder können entfallen; von discounts werden höchstens 5 Einträge angezeigt.
• pay_url ist der Zahlungslink für die Webseite und muss https sein. Wenn auf der Seite „Integration“ eine Domain-Allowlist konfiguriert ist, muss die URL auf einer Domain oder Subdomain dieser Allowlist liegen; andernfalls wird sie nicht angezeigt.
• mp_path ist der Pfad zur Zahlungsseite im Mini Program und wird im WeChat-Kanal als Mini-Programm-Karte an den Kunden gesendet (als Titelbild dient das Bild des ersten Produkts). Wenn kein mp_path vorhanden ist, wird pay_url gesendet. Mindestens eines von beiden muss vorhanden sein.
• expires_at ist die Zahlungsfrist und wird auf der Karte angezeigt.
• Mögliche Werte für code: OUT_OF_STOCK, SKU_UNAVAILABLE, REGION_UNAVAILABLE, NOT_LOGGED_IN, LIMIT, OTHER. message wird dem Kunden direkt angezeigt; verwenden Sie eine für Kunden verständliche Formulierung.
• Wenn Sie keine Preisberechnung anbieten möchten, können Sie für quote {"status": "unsupported"} zurückgeben. Die Karte schätzt dann den Preis anhand der Preise im Produktkatalog und weist darauf hin: „Der endgültige Betrag richtet sich nach der Zahlungsseite.“
• Wenn create einen anderen Status als 200 oder ein ungültiges Format zurückgibt, bleibt die Bestellbestätigung erhalten und der Kunde kann erneut klicken; stellen Sie sicher, dass eine doppelte request_id keine zweite Bestellung anlegt.

Einschränkungen: Eine Bestellbestätigung ist 30 Minuten gültig; wird im selben Chat eine neue erstellt, wird die alte ungültig. Pro Bestellung sind höchstens 10 Produktarten mit jeweils höchstens 20 Stück möglich; pro Chat können innerhalb von 24 Stunden höchstens 5 Bestellungen angelegt werden.