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

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

Resposta

200Rascunho

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

200Produto ambíguo

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

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

Status	Quando	Corpo
401	Sem token ou token inválido/expirado.	`{"error":"missing authorization header"}` ou `{"error":"invalid or expired token"}`
403	O administrador não tem nenhum dos privilégios exigidos.	`{"error":"insufficient privileges","privilege_required_any":["manage_promotions","intelligence_use_chat"]}`
400	`brief` vazio ou corpo ilegível.	`{"error":"brief is required"}`
403	Criação de promoção por IA desligada.	`{"error":"AI promotion creation is disabled for this tenant"}`
422	A 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 ..."}`
503	Nenhum provedor de IA configurado.	`{"error":"AI provider is not configured"}`

Veja também

Promoções por IA

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

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

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

Resposta

200Rascunho

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

200Produto ambíguo

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

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

Status	Quando	Corpo
401	Sem token ou token inválido/expirado.	`{"error":"missing authorization header"}` ou `{"error":"invalid or expired token"}`
403	O administrador não tem nenhum dos privilégios exigidos.	`{"error":"insufficient privileges","privilege_required_any":["manage_promotions","intelligence_use_chat"]}`
400	`brief` vazio ou corpo ilegível.	`{"error":"brief is required"}`
403	Criação de promoção por IA desligada.	`{"error":"AI promotion creation is disabled for this tenant"}`
422	A 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 ..."}`
503	Nenhum provedor de IA configurado.	`{"error":"AI provider is not configured"}`