AI-bestel-API

Nadat de klant in het gesprek producten heeft uitgekozen, stelt de AI een order op die de klant kan bevestigen; zodra de klant bevestigt, vragen we je systeem om een order in afwachting van betaling aan te maken en geven we de betaallink die je terugstuurt aan de klant. Wij slaan de order niet op en verwerken het geld niet.

Vul in de backend bij 'Botinstellingen' de order-API in (laat je dit leeg, dan kan de AI geen orders plaatsen). Je kunt daarnaast een inlogpagina-URL invullen: wanneer een niet-ingelogde klant wil bestellen, verschijnt er een knop 'Inloggen' in het chatvenster.

Vereisten:

• Alleen ingelogde klanten kunnen bestellen; user_id komt uit de user_token die jij uitgeeft (zie Ingelogde klanten identificeren).
• Producten moeten via de open API gesynchroniseerd zijn (zie Kennisbank en producten); producten met varianten moeten variants[].sku bevatten — bij het bestellen geven we de sku ongewijzigd aan je door.

Hoe de klant bevestigt:

• Chatvenster op de website: nadat de AI de order heeft opgesteld, verschijnt er een orderkaart; pas wanneer de klant op 'Bestelling bevestigen' klikt, wordt de order aangemaakt, en daarna verschijnt op de kaart de knop 'Ga betalen'.
• Kanalen die alleen tekst kunnen versturen, zoals de WeChat-miniprogramma: de AI stuurt de klant een ordersamenvatting; pas nadat de klant met 'Bevestigen' antwoordt, wordt de order aangemaakt, en daarna sturen we de betaalingang (zie mp_path hieronder).

Verzoek

Hetzelfde adres, met mode wordt onderscheid gemaakt tussen prijsopgave en order aanmaken. De signatuur- en verificatiemethode zijn dezelfde als bij de Orderopvraag-API, time-out 10 seconden.

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

Antwoord

Prijsopgave gelukt:

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

Order aanmaken gelukt:

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

Bestellen niet mogelijk:

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

• Alle bedragen zijn strings. total en currency zijn verplicht, de rest mag worden weggelaten; discounts toont maximaal 5 regels.
• pay_url is de betaallink voor de website en moet https zijn; als er op de pagina 'Integratie' een domeinwhitelist is ingesteld, moet het adres bovendien op een domein of subdomein uit die whitelist vallen, anders wordt het niet getoond.
• mp_path is het pad van de betaalpagina in de miniprogramma; bij het WeChat-kanaal wordt dit als miniprogramma-kaart naar de klant gestuurd (als omslagafbeelding wordt de afbeelding van het eerste product gebruikt); is er geen mp_path, dan sturen we pay_url. Minstens één van de twee is nodig.
• expires_at is de uiterste betaaltijd en wordt op de kaart getoond.
• code mogelijke waarden: OUT_OF_STOCK, SKU_UNAVAILABLE, REGION_UNAVAILABLE, NOT_LOGGED_IN, LIMIT, OTHER. message wordt rechtstreeks aan de klant getoond; gebruik woorden die de klant begrijpt.
• Wil je geen prijsopgave doen, dan kun je op quote {"status": "unsupported"} terugsturen; de kaart schat de prijs dan op basis van de prijzen in de productbibliotheek en vermeldt 'Het uiteindelijke bedrag staat op de betaalpagina'.
• Geeft create iets anders dan 200 terug of klopt het formaat niet, dan blijft de orderbevestiging staan en kan de klant nog eens klikken; zorg ervoor dat een dubbele request_id geen tweede order aanmaakt.

Beperkingen: Een orderbevestiging is 30 minuten geldig; stel je in hetzelfde gesprek een nieuwe op, dan vervalt de oude; per order maximaal 10 soorten producten en per soort maximaal 20 stuks; per gesprek maximaal 5 orders binnen 24 uur.