AI 주문 API

고객이 대화에서 상품을 선택하면 AI가 주문 초안을 작성해 고객에게 확인을 요청합니다. 고객이 확인하면 저희가 귀하의 시스템에 결제 대기 주문 생성을 요청하고, 반환된 결제 링크를 고객에게 전달합니다. 저희는 주문을 저장하지 않으며 결제 대금도 취급하지 않습니다.

백오피스의 「봇 설정」에서 주문 생성 API를 입력하세요(입력하지 않으면 AI가 주문할 수 없습니다). 선택적으로 로그인 페이지 URL도 입력할 수 있습니다. 로그인하지 않은 고객이 주문하려고 하면 채팅 창에 「로그인」 버튼이 표시됩니다.

전제 조건:

• 로그인한 고객만 주문할 수 있으며, user_id는 귀하가 발급한 user_token에서 가져옵니다(로그인 고객 식별 참조).
• 상품은 Open API를 통해 동기화해야 합니다(지식 베이스와 상품 참조). 옵션이 있는 상품은 variants[].sku를 포함해야 하며, 저희는 주문 시 sku를 그대로 전달합니다.

고객 확인 방법:

• 웹 채팅 창: AI가 초안을 작성하면 주문 카드가 표시되며, 고객이 「주문 확인」을 클릭해야 주문이 생성됩니다. 생성 후 카드에 「결제하기」 버튼이 나타납니다.
• WeChat 미니프로그램 등 텍스트만 보낼 수 있는 채널: AI가 주문 요약을 고객에게 보내고, 고객이 「확인」이라고 답해야 주문이 생성됩니다. 생성 후 결제 진입점을 보냅니다(아래 mp_path 참조).

요청

동일한 주소에서 mode로 견적과 주문 생성을 구분합니다. 서명 및 서명 검증 방법은 주문 조회 API와 동일하며, 타임아웃은 10초입니다.

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

응답

견적 성공:

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

주문 생성 성공:

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

주문할 수 없음:

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

• 금액은 모두 문자열로 전달합니다. total과 currency는 필수이며 나머지는 생략할 수 있습니다. discounts는 최대 5개까지 표시됩니다.
• pay_url은 웹 결제 링크이며 https여야 합니다. 「연동」 페이지에서 도메인 화이트리스트를 설정한 경우 화이트리스트의 도메인 또는 그 하위 도메인에 속해야 하며, 그렇지 않으면 표시되지 않습니다.
• mp_path는 미니프로그램 내 결제 페이지 경로이며, WeChat 채널에서는 미니프로그램 카드로 고객에게 전송됩니다(커버 이미지는 첫 번째 상품 이미지를 사용합니다). mp_path가 없으면 pay_url을 전송합니다. 둘 중 하나는 반드시 있어야 합니다.
• expires_at은 결제 마감 시간이며 카드에 표시됩니다.
• code의 가능한 값: OUT_OF_STOCK, SKU_UNAVAILABLE, REGION_UNAVAILABLE, NOT_LOGGED_IN, LIMIT, OTHER. message는 고객에게 그대로 표시되므로 고객이 이해할 수 있는 문구를 사용하세요.
• 견적을 제공하고 싶지 않다면 quote에 대해 {"status": "unsupported"}를 반환할 수 있습니다. 이 경우 카드는 상품 라이브러리의 가격으로 추정하며 「최종 금액은 결제 페이지를 기준으로 합니다」라고 표시합니다.
• create가 200이 아닌 응답을 반환하거나 형식이 올바르지 않으면 주문 확인은 유지되며 고객은 다시 클릭할 수 있습니다. 중복된 request_id로 두 번째 주문이 생성되지 않도록 해주세요.

제한 사항: 주문 확인은 30분 동안 유효하며, 같은 대화에서 새로 초안을 작성하면 이전 초안은 무효가 됩니다. 주문 하나당 최대 10종의 상품, 상품당 최대 20개까지 가능합니다. 같은 대화에서 24시간 이내에 최대 5건의 주문을 생성할 수 있습니다.