API ordini AI

Dopo che il cliente conferma l'ordine in chat, chiamiamo la tua API per creare un ordine in attesa di pagamento e inviare al cliente il link di pagamento.

Dopo che il cliente ha scelto i prodotti nella conversazione, l'AI prepara una bozza d'ordine da far confermare al cliente; una volta confermata, chiediamo al tuo sistema di creare un ordine in attesa di pagamento e forniamo al cliente il link di pagamento che restituisci. Non salviamo gli ordini e non gestiamo il denaro.

Nel backend, in «Impostazioni del bot», compila l'endpoint di creazione ordine (se non lo compili, l'AI non può creare ordini); puoi anche compilare l'URL della pagina di accesso: quando un cliente non autenticato vuole effettuare un ordine, nella finestra di chat compare il pulsante «Accedi».

Prerequisiti:

Solo i clienti autenticati possono creare ordini; user_id proviene dal user_token che emetti (vedi Identificare i clienti autenticati).
I prodotti devono essere sincronizzati tramite l'API pubblica (vedi Base di conoscenza e prodotti); per i prodotti con varianti, includi variants[].sku; al momento dell'ordine ti passiamo lo sku così com'è.

Come conferma il cliente:

Finestra di chat web: dopo la bozza dell'AI viene mostrata una scheda ordine; l'ordine viene creato solo quando il cliente fa clic su «Conferma ordine» e, una volta creato, sulla scheda compare il pulsante «Vai al pagamento».
Canali che supportano solo testo, come i Mini Program di WeChat: l'AI invia al cliente un riepilogo dell'ordine e l'ordine viene creato solo dopo che il cliente risponde «Confermo»; una volta creato, viene inviato l'accesso al pagamento (vedi mp_path di seguito).

Richiesta

Stesso URL; mode distingue tra preventivo e creazione dell'ordine. Il metodo di firma e verifica è lo stesso dell'endpoint di ricerca ordini; timeout di 10 secondi.

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

Campo	Descrizione
`mode`	`quote`: calcola solo il prezzo (sconti, spedizione, tasse), non crea l'ordine e non riserva scorte; `create`: crea un ordine in attesa di pagamento
`request_id`	La richiesta di preventivo e la creazione relative alla stessa conferma d'ordine usano lo stesso valore. Quando `create` riceve un `request_id` duplicato deve restituire lo stesso ordine; i nostri tentativi ripetuti e i clic duplicati del cliente si affidano a questo per evitare ordini duplicati
`user_id`	Cliente autenticato; l'ordine può essere creato solo per questo cliente
`channel`	`widget` / `wechat_mp` / `api`
`language`, `country`	Lingua del cliente e paese dell'IP, possono essere `null`; servono per scegliere la valuta di regolamento e calcolare le tasse
`items[].product_id` / `sku`	L'`external_id` del prodotto e lo `sku` della variante; per i prodotti senza varianti, `sku` è `null`

Risposta

Preventivo riuscito:

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

Creazione ordine riuscita:

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

Impossibile creare l'ordine:

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

Gli importi sono tutti stringhe. total e currency sono obbligatori, gli altri campi possono essere omessi; discounts mostra al massimo 5 voci.
pay_url è il link di pagamento per il web e deve essere https; se nella pagina «Integrazione» è configurata una whitelist di domini, deve appartenere a un dominio della whitelist o a un suo sottodominio, altrimenti non viene mostrato.
mp_path è il percorso della pagina di pagamento nel Mini Program; nel canale WeChat viene inviato al cliente come scheda del Mini Program (la copertina usa l'immagine del primo prodotto); se manca mp_path, viene inviato pay_url. Almeno uno dei due deve essere presente.
expires_at è la scadenza del pagamento e viene mostrata sulla scheda.
Valori possibili per code: OUT_OF_STOCK, SKU_UNAVAILABLE, REGION_UNAVAILABLE, NOT_LOGGED_IN, LIMIT, OTHER. message viene mostrato direttamente al cliente: usa parole che il cliente possa capire.
Se non vuoi gestire il preventivo, puoi restituire {"status": "unsupported"} per quote; la scheda stimerà il prezzo in base ai prezzi nel catalogo prodotti e indicherà «L'importo finale è quello della pagina di pagamento».
Se create restituisce un codice diverso da 200 o un formato non valido, la conferma dell'ordine resta valida e il cliente può fare clic di nuovo; assicurati che un request_id duplicato non crei un secondo ordine.

Limiti: la conferma dell'ordine è valida per 30 minuti; se nella stessa conversazione viene preparata una nuova bozza, quella precedente viene invalidata; un ordine può contenere al massimo 10 tipi di prodotto e 20 pezzi per tipo; nella stessa conversazione si possono creare al massimo 5 ordini in 24 ore.

Questa pagina ti è stata utile?

Ultimo aggiornamento: 31 ottobre 2026