API de pedidos con AI

Cuando el cliente confirma el pedido en la conversación, llamamos a tu API para crear un pedido pendiente de pago y le enviamos el enlace de pago.

Cuando el cliente elige productos en la conversación, la AI prepara un borrador de pedido para que el cliente lo confirme; una vez que el cliente confirma, solicitamos a tu sistema que cree un pedido pendiente de pago y entregamos al cliente el enlace de pago que devuelvas. No almacenamos el pedido ni gestionamos los fondos.

En el panel de administración, en «Configuración del bot», completa el endpoint de creación de pedidos (si no lo completas, la AI no podrá crear pedidos). También puedes completar la URL de la página de inicio de sesión: cuando un cliente que no ha iniciado sesión quiera hacer un pedido, aparecerá el botón «Iniciar sesión» en la ventana de chat.

Requisitos previos:

Solo los clientes que han iniciado sesión pueden crear pedidos; user_id proviene del user_token que emites (consulta Identificar a los clientes que han iniciado sesión).
Los productos deben sincronizarse a través de la API abierta (consulta Base de conocimiento y productos); los productos con variantes deben incluir variants[].sku. Al crear el pedido, te pasamos el sku tal cual.

Cómo confirma el cliente:

Ventana de chat web: después de que la AI prepara el borrador, se muestra una tarjeta de pedido; el pedido solo se crea cuando el cliente pulsa «Confirmar pedido». Una vez creado, en la tarjeta aparece el botón «Ir a pagar».
Canales que solo permiten enviar texto, como WeChat Mini Program: la AI envía al cliente un resumen del pedido y el pedido solo se crea cuando el cliente responde «Confirmar». Una vez creado, se envía el acceso al pago (consulta mp_path más abajo).

Solicitud

En la misma URL, mode distingue entre cotización y creación del pedido. La firma y la verificación de la firma funcionan igual que en la API de consulta de pedidos; el tiempo de espera es de 10 segundos.

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	Descripción
`mode`	`quote`: solo calcula el precio (descuentos, envío, impuestos), no crea el pedido ni reserva stock; `create`: crea un pedido pendiente de pago
`request_id`	La cotización y la creación del pedido para la misma confirmación de pedido usan el mismo valor. Cuando `create` recibe un `request_id` duplicado, debe devolver el mismo pedido; tanto nuestros reintentos como los clics repetidos del cliente dependen de esto para evitar pedidos duplicados
`user_id`	Cliente que ha iniciado sesión; solo se puede crear un pedido para este cliente
`channel`	`widget` / `wechat_mp` / `api`
`language`, `country`	Idioma del cliente y país de su IP; pueden ser `null`. Sirven para elegir la moneda de liquidación y calcular impuestos
`items[].product_id` / `sku`	`external_id` del producto y `sku` de la variante; en productos sin variantes, `sku` es `null`

Respuesta

Cotización correcta:

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

Pedido creado correctamente:

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

No se puede crear el pedido:

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

Los importes se envían como cadenas. total y currency son obligatorios; el resto puede omitirse. discounts muestra como máximo 5 elementos.
pay_url es el enlace de pago web y debe ser https. Si en la página «Integración» se ha configurado una lista blanca de dominios, también debe pertenecer al dominio de la lista blanca o a uno de sus subdominios; de lo contrario, no se mostrará.
mp_path es la ruta de la página de pago dentro del Mini Program; en el canal de WeChat se enviará al cliente como una tarjeta de Mini Program (la portada usa la imagen del primer producto). Si no hay mp_path, se enviará pay_url. Debe haber al menos uno de los dos.
expires_at es la fecha y hora límite de pago y se mostrará en la tarjeta.
Valores posibles de code: OUT_OF_STOCK, SKU_UNAVAILABLE, REGION_UNAVAILABLE, NOT_LOGGED_IN, LIMIT, OTHER. message se mostrará directamente al cliente; usa un texto que el cliente pueda entender.
Si no quieres realizar la cotización, puedes devolver {"status": "unsupported"} para quote; la tarjeta estimará el importe según los precios del catálogo de productos e indicará «El importe final se mostrará en la página de pago».
Si create devuelve un código distinto de 200 o el formato no es correcto, la confirmación del pedido se mantiene y el cliente puede volver a pulsar; asegúrate de que un request_id duplicado no cree un segundo pedido.

Límites: la confirmación del pedido es válida durante 30 minutos; si se prepara un nuevo borrador en la misma conversación, el anterior queda invalidado. Un pedido puede incluir como máximo 10 tipos de productos y 20 unidades de cada tipo; en una misma conversación se pueden crear como máximo 5 pedidos en 24 horas.

¿Te ha resultado útil esta página?

Última actualización: 31 de octubre de 2026