API zamówień AI

Gdy klient wybierze produkty w rozmowie, AI przygotowuje projekt zamówienia do potwierdzenia przez klienta; po potwierdzeniu przez klienta prosimy Twój system o utworzenie zamówienia oczekującego na płatność i przekazujemy klientowi zwrócony przez Ciebie link do płatności. Nie przechowujemy zamówień ani nie pośredniczymy w płatnościach.

W panelu administracyjnym, w sekcji „Ustawienia bota”, wypełnij interfejs składania zamówień (jeśli go nie wypełnisz, AI nie będzie w stanie składać zamówień). Możesz też podać adres strony logowania: gdy niezalogowany klient będzie chciał złożyć zamówienie, w oknie czatu pojawi się przycisk „Zaloguj się”.

Wymagania wstępne:

• Tylko zalogowani klienci mogą składać zamówienia; user_id pochodzi z wydanego przez Ciebie user_token (zob. Rozpoznawanie zalogowanych klientów).
• Produkty muszą być zsynchronizowane przez otwarte API (zob. Baza wiedzy i produkty); produkty z wariantami muszą zawierać variants[].sku — przy składaniu zamówienia przekazujemy sku bez zmian.

Jak klient potwierdza zamówienie:

• Okno czatu na stronie: po przygotowaniu projektu przez AI wyświetlana jest karta zamówienia; zamówienie powstaje dopiero, gdy klient kliknie „Potwierdź zamówienie”, a po jego utworzeniu na karcie pojawia się przycisk „Przejdź do płatności”.
• Kanały obsługujące tylko tekst, np. mini-program WeChat: AI wysyła klientowi podsumowanie zamówienia, a zamówienie powstaje dopiero po odpowiedzi „Potwierdzam”; po utworzeniu wysyłamy link do płatności (zob. mp_path poniżej).

Żądanie

Ten sam adres; pole mode rozróżnia wycenę i utworzenie zamówienia. Sposób podpisywania i weryfikacji podpisu jest taki sam jak w interfejsie wyszukiwania zamówień, limit czasu wynosi 10 sekund.

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

Odpowiedź

Wycena zakończona powodzeniem:

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

Zamówienie utworzone:

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

Nie można złożyć zamówienia:

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

• Kwoty są zawsze ciągami znaków. total i currency są wymagane, pozostałe pola można pominąć; w discounts wyświetlamy maksymalnie 5 pozycji.
• pay_url to link do płatności w przeglądarce; musi używać https. Jeśli na stronie „Integracja” skonfigurowano białą listę domen, link musi też należeć do domeny z listy lub jej subdomeny — w przeciwnym razie nie zostanie wyświetlony.
• mp_path to ścieżka strony płatności w mini-programie; w kanałach WeChat jest wysyłana klientowi jako karta mini-programu (okładką jest zdjęcie pierwszego produktu). Jeśli nie ma mp_path, wysyłamy pay_url. Przynajmniej jedno z tych pól musi być podane.
• expires_at to termin płatności, który będzie wyświetlany na karcie.
• Dozwolone wartości code: OUT_OF_STOCK, SKU_UNAVAILABLE, REGION_UNAVAILABLE, NOT_LOGGED_IN, LIMIT, OTHER. message jest wyświetlany klientowi bezpośrednio, więc użyj sformułowań, które klient zrozumie.
• Jeśli nie chcesz realizować wyceny, możesz na quote zwrócić {"status": "unsupported"}; karta oszacuje kwotę na podstawie cen z katalogu produktów i doda informację „Ostateczna kwota zostanie pokazana na stronie płatności”.
• Jeśli create zwróci kod inny niż 200 lub nieprawidłowy format, potwierdzenie zamówienia pozostaje ważne i klient może kliknąć ponownie; upewnij się, że powtórzony request_id nie utworzy drugiego zamówienia.

Limity: potwierdzenie zamówienia jest ważne 30 minut; przygotowanie nowego potwierdzenia w tej samej rozmowie unieważnia poprzednie; jedno zamówienie może obejmować maksymalnie 10 rodzajów produktów, po maksymalnie 20 sztuk każdego; w tej samej rozmowie w ciągu 24 godzin można utworzyć maksymalnie 5 zamówień.