API de pedidos com IA

Depois que o cliente confirma o pedido na conversa, chamamos sua API para criar um pedido pendente de pagamento e enviamos o link de pagamento ao cliente.

Depois que o cliente escolhe os produtos na conversa, a IA elabora um rascunho de pedido para o cliente confirmar; após a confirmação do cliente, solicitamos ao seu sistema a criação de um pedido pendente de pagamento e entregamos ao cliente o link de pagamento que você retornar. Não armazenamos o pedido nem intermediamos o valor da compra.

Em "Configurações do robô" no painel, preencha a API de criação de pedidos (se não preencher, a IA não poderá criar pedidos); opcionalmente, preencha também o endereço da página de login: quando um cliente não logado quiser fazer um pedido, um botão "Entrar" aparecerá na janela de chat.

Pré-requisitos:

Apenas clientes logados podem fazer pedidos; o user_id vem do user_token que você emite (veja Identificar clientes logados).
Os produtos devem ser sincronizados pela API aberta (veja Base de conhecimento e produtos); produtos com variações devem incluir variants[].sku, e passamos o sku para você exatamente como está ao criar o pedido.

Como o cliente confirma:

Janela de chat no site: após a elaboração da IA, um cartão de pedido é exibido; o pedido só é criado quando o cliente clica em "Confirmar pedido" e, depois de criado, o botão "Ir para pagamento" aparece no cartão.
Canais que só permitem enviar texto, como o Mini Program do WeChat: a IA envia o resumo do pedido ao cliente; o pedido só é criado após o cliente responder "Confirmar" e, depois de criado, enviamos a entrada de pagamento (veja mp_path abaixo).

Requisição

O mesmo endereço, diferenciando orçamento e criação de pedido por mode. O método de assinatura e verificação é o mesmo da API de consulta de pedidos; timeout 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	Descrição
`mode`	`quote`: apenas calcula preços (descontos, frete, impostos), não cria pedido nem reserva estoque; `create`: cria um pedido pendente de pagamento
`request_id`	O orçamento e a criação do pedido da mesma confirmação usam o mesmo valor. Ao receber um `request_id` repetido em `create`, você deve retornar o mesmo pedido; nossas retentativas e os cliques repetidos do cliente dependem disso para evitar pedidos duplicados
`user_id`	Cliente logado; o pedido só pode ser criado para este cliente
`channel`	`widget` / `wechat_mp` / `api`
`language`, `country`	Idioma do cliente e país do IP, podem ser `null`; podem ser usados para escolher a moeda de liquidação e calcular impostos
`items[].product_id` / `sku`	O `external_id` do produto e o `sku` da variação; para produtos sem variação, `sku` é `null`

Retorno

Orçamento bem-sucedido:

{
  "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 criado com sucesso:

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

Não é possível criar o pedido:

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

Todos os valores monetários são strings. total e currency são obrigatórios; os demais podem ser omitidos; discounts exibe no máximo 5 itens.
pay_url é o link de pagamento web e deve ser https; se uma whitelist de domínios estiver configurada na página "Integração", ele também deve estar no domínio da whitelist ou em um subdomínio dela, caso contrário não será exibido.
mp_path é o caminho da página de pagamento no Mini Program; no canal WeChat ele será enviado ao cliente como um cartão do Mini Program (a capa usa a imagem do primeiro produto); se não houver mp_path, enviamos o pay_url. É necessário ter pelo menos um dos dois.
expires_at é o prazo limite de pagamento e será exibido no cartão.
Valores possíveis de code: OUT_OF_STOCK, SKU_UNAVAILABLE, REGION_UNAVAILABLE, NOT_LOGGED_IN, LIMIT, OTHER. O message é exibido diretamente ao cliente; use palavras que o cliente entenda.
Se não quiser fazer o orçamento, você pode retornar {"status": "unsupported"} para quote; o cartão fará uma estimativa com base nos preços do catálogo de produtos e indicará "O valor final está sujeito à página de pagamento".
Se create retornar algo diferente de 200 ou em formato incorreto, a confirmação do pedido é mantida e o cliente pode clicar novamente; garanta que um request_id repetido não crie um segundo pedido.

Limitações: a confirmação do pedido é válida por 30 minutos; criar uma nova confirmação na mesma conversa invalida a anterior; no máximo 10 tipos de produtos por pedido, com no máximo 20 unidades de cada; no máximo 5 pedidos criados na mesma conversa em 24 horas.

Esta página foi útil?

Última atualização: 31 de outubro de 2026