VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Venddor Intelligence: ferramentas de IA

Promoções por IA

Converte um pedido em linguagem natural em um rascunho de promoção e, se pedido, o salva desativado.

O administrador escreve "frete grátis para compras acima de R$ 300" e recebe a promoção estruturada: tipo de benefício, valor, escopo de produtos, validade. A VI usa os nomes reais de produtos e categorias da loja; se o pedido citar um produto ambíguo, a resposta traz uma lista de opções (pending_choice) em vez de adivinhar. A promoção nunca nasce ativa: ela é criada desativada e só passa a valer quando o administrador a ativa na tela de promoções.

Gera o rascunho. A chamada pode levar vários segundos, então use um timeout folgado.

POST/api/v1/admin/intelligence/promotions/generateAdmin

Gerar um rascunho de promoção

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso de um administrador (veja Tokens).
Content-Typestringobrigatório
application/json.

Corpo da requisição

briefstringobrigatório
O pedido, em linguagem natural.
auto_savebooleanpadrão: false
true grava a promoção (desativada) além de devolver o rascunho. Ignorado quando há pending_choice.
scopeobject
Escolhas já feitas, para uma segunda chamada depois de pending_choice. Todas as chaves são opcionais:
scope.product_idsarray
Ids de produto (strings UUID) a que a promoção se aplica.
scope.exclude_product_idsarray
Ids de produto (strings UUID) deixados de fora.
scope.category_idsarray
Ids de categoria (strings UUID) a que a promoção se aplica.
scope.product_or_groupsarray
Lista de listas de ids de produto (strings UUID), uma lista para cada produto citado no pedido.
scope.resolved_queriesarray
Nomes de produto do pedido que você já resolveu, para não serem perguntados de novo.

Exemplo de requisição

Resposta

200Rascunho
200Produto ambíguo

Campos da resposta

draft.namestring
Nome da promoção (gerado se omitido).
draft.descriptionstring
Justificativa em texto livre. Pode faltar.
draft.discount_typestring
percentagefixedfree_shippingbuy_x_get_yfree_productsfree_productorder_discountproduct_discountcategory_discountto_percentageto_fixedgive_usergroupassign_usergroupgive_coupongive_cashback
Tipo do benefício principal.
draft.discount_valueinteger
Valor do benefício principal: centavos em fixed; pontos-base em percentage (1000 = 10%); 1 a 100 em buy_x_get_y; 0 em free_shipping.
draft.max_discountinteger
Teto do desconto percentual, em centavos. Opcional.
draft.benefitsarray
Todos os benefícios (uma promoção pode dar vários). Cada um: type, value, mais campos do tipo (buy_quantity, get_quantity, product_ids, category_ids...).
draft.applies_toobject
Alcance: product_ids, category_ids, exclude_product_ids, user_group_ids, vendor_ids e min_cart_total (centavos).
draft.codestring
Código de cupom. Sem ele, a promoção é aplicada automaticamente.
draft.valid_fromstring
RFC 3339. Opcional.
draft.valid_untilstring
RFC 3339. Opcional.
draft.usage_limitinteger
Limite global de usos. Omitido = ilimitado.
draft.per_user_limitinteger
Limite por cliente. Omitido = ilimitado.
draft.statusstring
Sempre draft na resposta, mesmo com auto_save.
draft.promotion_iduuid
Só com auto_save bem-sucedido: id da promoção criada. Pode haver promotion_ids quando o rascunho virou várias promoções.
pending_choiceobject
Presente quando um produto citado é ambíguo: query e options (id, label, hint). Escolha uma e chame de novo com scope.product_ids.

Erros

StatusQuandoCorpo
401Sem token ou token inválido/expirado.{"error":"missing authorization header"} ou {"error":"invalid or expired token"}
403O administrador não tem nenhum dos privilégios exigidos.{"error":"insufficient privileges","privilege_required_any":["manage_promotions","intelligence_use_chat"]}
400brief vazio ou corpo ilegível.{"error":"brief is required"}
403Criação de promoção por IA desligada.{"error":"AI promotion creation is disabled for this tenant"}
422A IA não conseguiu montar uma promoção válida com esse pedido.{"error":"ai_response_invalid","detail":"...","hint":"the AI couldn't produce a valid promotion from that brief ..."}
503Nenhum provedor de IA configurado.{"error":"AI provider is not configured"}
Duas chamadas quando há dúvida

Quando a resposta traz pending_choice, mostre as opções, e chame de novo com o mesmo brief e scope: {"product_ids": ["<id escolhido>"]}. Só nessa segunda chamada auto_save grava.

Veja também

  • Visão geral
  • Banners por IA
Anterior
Banners por IA
Próxima
Importação de produtos por IA
Nesta página
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também
bash
curl -X POST "$BASE_URL/api/v1/admin/intelligence/promotions/generate" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "brief": "Frete grátis para compras acima de R$ 300",
    "auto_save": false
  }'
json
{
  "draft": {
    "name": "Frete grátis acima de R$ 300",
    "discount_type": "free_shipping",
    "discount_value": 0,
    "benefits": [{ "type": "free_shipping", "value": 0 }],
    "applies_to": { "min_cart_total": 30000 },
    "status": "draft"
  }
}
json
{
  "draft": { "name": "10% no mouse", "status": "draft" },
  "pending_choice": {
    "query": "mouse",
    "options": [
      { "id": "7bc1d5e9-a9a4-457b-866f-bbb3879d258d", "label": "Mouse Gamer Titan", "hint": "SKU MG-01" },
      { "id": "0d9c8b7a-6f5e-4d3c-b2a1-908f7e6d5c4b", "label": "Mouse sem fio Office", "hint": "SKU MO-02" }
    ]
  }
}