Documentação

Estruturas

As estruturas descrevem o que pode ser montado nesta loja. Alguns tipos de condição, desconto ou entidade podem não existir em todas as lojas, e os nomes exibidos podem variar. Consulte-as antes de montar o payload e use-as como fonte da verdade para IDs de grupos, subgrupos, operadores e argumentos.

Estrutura de condições

GET /api/promotions/structure/conditions

Permissão: Cadastro de promoções — visualização

Retorna a árvore grupo → subgrupo → operador → argumentos das condições disponíveis na loja. Não recebe parâmetros.

Resposta 200

{
  "data": {
    "conditions": {
      "conditionsGroup": [
        {
          "conditionGroupId": 5,
          "conditionGroupType": "Carrinho",
          "conditionsSubGroup": [
            {
              "conditionSubGroupId": 16,
              "conditionSubGroupType": "Subtotal",
              "logicOperators": [
                {
                  "id": 3,
                  "name": "Maior ou igual",
                  "multiselect": false,
                  "arguments": [
                    { "id": 4,  "name": "Valor", "dataType": "Decimal", "required": true, "options": null, "displayOrder": 1 },
                    { "id": 22, "name": "FabricantesIds", "dataType": "ListInt", "required": false, "options": null, "displayOrder": 2 }
                  ]
                }
              ]
            }
          ]
        }
      ]
    }
  }
}

Campos

CampoDescrição
conditionGroupIdValor para conditionGroup no payload.
conditionSubGroupIdValor para conditionSubGroup.
logicOperators[].idValor para logicOperator.id. Operadores fora da lista são recusados. Nos subgrupos que reúnem várias condições (4/11 e 4/12), um operador listado ainda pode ser recusado para a condição resultante; veja as Receitas.
logicOperators[].multiselecttrue quando o operador aceita mais de um valor nos argumentos de lista.
arguments[].idValor para logicOperator.arguments[].id. A lista de argumentos pode variar por operador (ex.: “incluir subcategorias” aparece apenas nos operadores 7 e 8).
arguments[].dataTypeInt, Long, Decimal, Boolean, String, ListInt, ListLong, ListString. Define o formato do valor (veja abaixo).
arguments[].requiredSe o argumento é obrigatório.
arguments[].optionsValores permitidos, quando houver.
arguments[].displayOrderOrdem sugerida de exibição. Pode ser null.
📘

Como preencher argumentos com options

Para dataType Int ou ListInt, envie a posição da opção na lista, começando em 1. Ex.: em “Tipo de cadastro”, com options: ["Física","Jurídica"], envie "1" para Física e "2" para Jurídica.

Para String ou ListString, envie o próprio texto da opção. Ex.: região "Sudeste"; aniversariante "mes". A comparação não diferencia maiúsculas, e um texto fora das opções é recusado. A exceção é a chave do parâmetro UTM (argumento 17), em que as opções são apenas sugestões.

Estrutura de descontos

GET /api/promotions/structure/discounts

Permissão: Cadastro de promoções — visualização

Retorna os grupos de desconto disponíveis na loja, seus tipos (nominal, percentual, selecionável) e os argumentos de cada um. Não recebe parâmetros.

Resposta 200

{
  "data": {
    "discounts": {
      "discountsGroup": [
        {
          "discountGroupId": 1,
          "discountGroupType": "DescontoProduto",
          "prioritySelection": true,
          "discountsSubGroup": [
            {
              "discountSubGroupId": 2,
              "discountSubGroupType": "Percentual",
              "selectionRequired": true,
              "arguments": [
                { "id": 1, "name": "ValorDesconto", "dataType": "Decimal", "argumentType": "SingleSelect", "required": true, "optionalArgumentsGroup": [] },
                { "id": 3, "name": "CategoriasId", "dataType": "ListLong", "argumentType": "MultiSelect", "required": true,
                  "optionalArgumentsGroup": [ { "optionalArguments": [ { "id": 13, "name": "IgnorarProdutosRemarcados", "dataType": "Boolean", "required": false, "options": null } ] } ] }
              ]
            }
          ]
        }
      ]
    }
  }
}
CampoDescrição
discountGroupIdValor para discounts[].discountGroup.
discountSubGroupIdValor para discounts[].discountSubGroup (1 nominal, 2 percentual, 3 selecionável).
arguments[].idValor para discounts[].arguments[].id. Argumentos MultiSelect recebem uma lista de IDs; SingleSelect, um valor.
selectionRequiredIndica que o tipo de desconto tem argumentos além do valor. Não significa que todos sejam obrigatórios (ex.: no frete, contratos e grupos são opcionais). Siga as Receitas de descontos.
optionalArgumentsGroupArgumentos complementares que podem acompanhar o alvo escolhido. Não use o required desses argumentos para decidir o que enviar; a obrigatoriedade de cada um (ex.: 13, “ignorar produtos remarcados”) está nas Receitas de descontos.

A estrutura também lista dois argumentos auxiliares, que não são dados do catálogo: 999 (“aplicar por produto”, nos descontos de subtotal) e 998 (“aplicação do desconto”, no desconto no item de menor/maior valor). Veja Receitas de descontos.

Estrutura de regras adicionais

GET /api/promotions/structure/rules

Permissão: Cadastro de promoções — visualização

Retorna as entidades que podem ser usadas em entityRules e, para cada uma, os tipos de validação e de restrição aceitos. Na maioria das entidades a restrição 1 (“ação e condição”) não aparece na lista: para aplicar a regra em toda a promoção, envie uma regra com restrição 2 e outra igual com restrição 3. Veja Regras adicionais.

Resposta 200

{
  "data": {
    "rules": [
      {
        "entityId": 3,
        "name": "Marca",
        "description": "...",
        "validationTypes": [ { "validationId": 1, "name": "Incluir todos" }, { "validationId": 3, "name": "Apenas inclusos" }, { "validationId": 4, "name": "Exceto inclusos" } ],
        "restrictionTypes": [ { "restrictionId": 2, "name": "Apenas ação" }, { "restrictionId": 3, "name": "Apenas condição" } ],
        "arguments": [ { "entityType": "Marca", "argumentType": "ListInt", "multiselect": true } ]
      }
    ]
  }
}

Condições da loja

GET /api/promotions/conditions

Permissão: Cadastro de promoções — visualização

Lista os tipos de condição cadastrados na loja. Use promotionConditionId no filtro conditions de Listar promoções. Não use esses IDs no payload de criação — lá as condições são descritas por grupo e subgrupo.

{ "data": { "conditions": [ { "promotionConditionId": 18, "name": "Se valor subtotal" } ] } }

Ações da loja

GET /api/promotions/actions

Permissão: Cadastro de promoções — visualização

Lista os tipos de ação (desconto) cadastrados na loja. Use promotionActionId no filtro actions de Listar promoções.

{
  "data": {
    "actions": [
      { "promotionActionId": 4, "name": "Desconto percentual no frete", "discountType": "Percentual", "discountGroup": "DescontoFrete",
        "arguments": [ { "name": "ValorDesconto", "type": "Decimal", "optional": false } ] }
    ]
  }
}

Updated about 2 hours ago