Developer Center
Pesquisar K

Appearance

Estrutura do kit ​

Um Kit (List) é um container que agrupa múltiplos itens com diferentes estratégias de seleção. Permite criar combos, bundles, kits customizados onde o cliente pode escolher quais itens incluir, remover ou em que quantidade.

{
  "id": "698b8a825eaf8de7c5af8de7",
  "name": "Kit Completo de Verão",
  "alias": "kit-verao-001",
  "caption": "Tudo o que você precisa para o verão",
  "active": true,
  "published": true,
  "hideIndividualPricesInWholeList": false,
  "community": "test",
  "formId": null,
  "createdAt": "2026-02-10T19:44:02.328Z",
  "updatedAt": "2026-02-12T20:46:11.133Z",
  "items": [
    {
      "itemId": "698b8a805eaf8de7c5af1cb9",
      "quantity": 1,
      "required": true,
      "defaultQuantity": 1,
      "selectedSkus": [],
      "allSkus": true,
      "strategy": "required",
      "linkingGroup": {
        "name": "Essencial",
        "icon": "star",
        "color": "gold",
        "links": []
      }
    },
    {
      "itemId": "698b8a805eaf8de7c5af1cba",
      "quantity": 1,
      "required": false,
      "defaultQuantity": 1,
      "selectedSkus": ["sku-preto", "sku-azul", "sku-vermelho"],
      "allSkus": false,
      "strategy": "optional",
      "linkingGroup": {
        "name": "Complemento",
        "icon": "bag",
        "color": "blue",
        "links": []
      }
    },
    {
      "itemId": "698b8a805eaf8de7c5af1cbb",
      "quantity": 0,
      "required": false,
      "defaultQuantity": 0,
      "selectedSkus": [],
      "allSkus": true,
      "strategy": "free-choice",
      "linkingGroup": null
    }
  ],
  "gallery": [
    {
      "url": "https://cdn.layers.digital/uploads/.../kit-verao.jpg",
      "path": "/uploads/.../kit-verao.jpg",
      "mime": "image/jpeg",
      "width": 1200,
      "height": 800,
      "size": 156780,
      "name": "kit-verao.jpg",
      "orientation": null
    }
  ],
  "tags": ["kit", "promoção", "verão"],
  "categories": ["bundles", "combos"],
  "content": [
    {
      "kind": "markdown",
      "markdown": "# Kit Completo de Verão\n\nTudo preparado para aproveitar melhor seus dias quentes..."
    }
  ],
  "stats": {
    "channels": []
  }
}

Campos principais ​

CampoTipoDescrição
idstringID único do kit
namestringNome do kit (3-100 caracteres, obrigatório)
aliasstring | nullID customizado único do kit. Caso não informado, null
captionstring | nullDescrição curta do kit (0-100 caracteres). Caso não informada, null
activebooleanIndica se o kit está ativo (padrão: true)
publishedbooleanIndica se o kit está publicado e visível (padrão: true)
hideIndividualPricesInWholeListbooleanSe true, oculta preços individuais dos itens, mostrando apenas o preço total do kit (padrão: false)
communitystringComunidade (tenant) do kit
formIdstring | nullID do formulário customizado a preencher na compra do kit. Caso não informado, null
itemsarray<object>Lista de itens que compõem o kit (ver abaixo)
galleryarray<object>Array de imagens do kit (primeira é a principal)
tagsarray<string>Tags descritivas do kit
categoriesarray<string>Categorias do kit
contentarray<object>Conteúdo descritivo em Markdown
statsobjectEstatísticas de vendas e dados por canal
createdAtstring (ISO 8601)Data e hora de criação
updatedAtstring (ISO 8601)Data e hora da última atualização

Estratégias de Seleção ​

O comportamento de cada item no kit é definido pela sua estratégia, que é derivada automaticamente dos campos required e quantity:

EstratégiaCondiçãorequiredquantitydefaultQuantityComportamento
requiredrequired = true✅ true≥ 1≥ 1Item obrigatório no kit. Cliente não pode remover. Quantidade fixa.
optionalrequired = false, quantity > 0❌ false≥ 1≥ 1Item opcional com quantidade fixa. Cliente pode aceitar ou recusar.
free-choicerequired = false, quantity = 0❌ false00Cliente escolhe livremente a quantidade (0 a N unidades).

Exemplos de Estratégia ​

Required - Item Obrigatório:

json
{
  "itemId": "...",
  "quantity": 1,
  "required": true,
  "defaultQuantity": 1,
  "strategy": "required"
}
  • Cliente DEVE incluir exatamente 1 unidade
  • Não pode ser removido do kit

Optional - Item Opcional com Quantidade Fixa:

json
{
  "itemId": "...",
  "quantity": 2,
  "required": false,
  "defaultQuantity": 2,
  "strategy": "optional"
}
  • Cliente pode aceitar (2 unidades) ou recusar (0 unidades)
  • Não pode ajustar para 1 unidade; é tudo ou nada

Free-Choice - Seleção Livre:

json
{
  "itemId": "...",
  "quantity": 0,
  "required": false,
  "defaultQuantity": 0,
  "strategy": "free-choice"
}
  • Cliente pode escolher de 0 a qualquer quantidade
  • Quantidade totalmente flexível

items (ListItem[]) ​

Lista de itens que compõem o kit. Cada item tem sua própria estratégia e configurações.

"items": [
  {
    "itemId": "698b8a805eaf8de7c5af1cb9",
    "quantity": 1,
    "required": true,
    "defaultQuantity": 1,
    "selectedSkus": [],
    "allSkus": true,
    "strategy": "required",
    "linkingGroup": {
      "name": "Essencial",
      "icon": "star",
      "color": "gold",
      "links": []
    }
  }
]

Campos do ListItem ​

CampoTipoDescrição
itemIdstringID do item associado (obrigatório)
quantityintegerQuantidade fixa deste item no kit (padrão: 1). Mín: 0
requiredbooleanIndica se o item é obrigatório no kit (padrão: false)
defaultQuantityintegerQuantidade padrão pré-selecionada para este item (padrão: 0). Mín: 0
selectedSkusarray<string>Array de IDs de SKUs permitidos deste item. Se vazio, allSkus muda para true
allSkusbooleanSe true, todos os SKUs do item são permitidos. Se false, apenas selectedSkus (padrão: true)
strategystringVirtual (derivado) - Estratégia automaticamente derivada: required, optional ou free-choice
linkingGroupobject | nullInformações de agrupamento visual (opcional). Caso não informado, null

Validações de ListItem ​

  • required = true força quantity >= 1 e defaultQuantity >= 1
  • required = false com quantity > 0 cria estratégia optional
  • required = false com quantity = 0 cria estratégia free-choice
  • Não pode haver duplicatas de itemId no kit
  • Se selectedSkus é modificado, allSkus é automaticamente ajustado
  • Quantity e defaultQuantity devem ser inteiros não-negativos

items[].linkingGroup (ListItemLinkingGroup) ​

Informações opcionais de agrupamento visual dos itens do kit. Usado para organizar e destacar itens relacionados na interface.

"linkingGroup": {
  "name": "Essencial",
  "icon": "star",
  "color": "gold",
  "links": []
}

Campos do LinkingGroup ​

CampoTipoDescrição
namestringNome do grupo. Ex: Essencial, Complementos, Acessórios
iconstringÍcone representativo. Valores possíveis: bag, users, gift, archive, check, star
colorstringCor associada ao grupo. Ex: gold, blue, red, green
linksarray<string>Array de IDs de itens relacionados (para agrupamento avançado)

Ícones Disponíveis ​

ÍconeUso
bagCompras, produtos gerais
usersGrupo, equipe, pessoas
giftPresentes, brindes
archiveArmazenamento, arquivo
checkConfirmação, completado
starDestaque, favorito, essencial

Array de imagens do kit. A primeira imagem é sempre a principal/capa.

"gallery": [
  {
    "url": "https://cdn.layers.digital/uploads/.../kit-1.jpg",
    "path": "/uploads/.../kit-1.jpg",
    "mime": "image/jpeg",
    "width": 1200,
    "height": 800,
    "size": 156780,
    "name": "kit-1.jpg",
    "orientation": null
  }
]
CampoTipoDescrição
urlstringURL pública da imagem
pathstringCaminho interno da imagem
mimestringTipo MIME. Ex: image/jpeg, image/png
widthinteger | nullLargura em pixels. Caso não informada, null
heightinteger | nullAltura em pixels. Caso não informada, null
sizeintegerTamanho do arquivo em bytes
namestringNome do arquivo
orientationstring | nullOrientação. Caso não informada, null

content (ItemContent[]) ​

Conteúdo descritivo do kit em Markdown ou outro formato.

"content": [
  {
    "kind": "markdown",
    "markdown": "# Kit Completo\n\n## O que inclui:\n\n- Item 1\n- Item 2 (opcional)\n- Item 3 (escolha a quantidade)"
  }
]
CampoTipoDescrição
kindstringTipo de conteúdo. Valor padrão: markdown
markdownstringConteúdo em formato Markdown

stats (EntityStats) ​

Estatísticas e metadados de vendas do kit agrupados por canal.

"stats": {
  "channels": [
    {
      "_id": "698b8a805eaf8de7c5af1cd2",
      "sales": 42,
      "revenue": {
        "amount": 2094000,
        "currency": "BRL"
      }
    }
  ]
}
CampoTipoDescrição
channelsarray<object>Array de estatísticas por canal
channels[._idstringID do canal
channels[].salesintegerTotal de vendas neste canal
channels[].revenue.amountintegerReceita em centavos
channels[].revenue.currencystringMoeda ISO 4217

Estados de Publicação ​

FlagSignificado
active: true, published: trueKit visível e ativo (pronto para venda)
active: true, published: falseKit ativo mas oculto (pausado)
active: false, published: falseKit inativo/arquivado (todos os KitLinks também ficarão inativos)

Casos de Uso Comuns ​

Kit Combo (Recomendado) ​

json
{
  "name": "Combo Promocional",
  "items": [
    { "itemId": "...", "required": true, "quantity": 1 },
    { "itemId": "...", "required": true, "quantity": 1 },
    { "itemId": "...", "required": true, "quantity": 1 }
  ]
}

Descrição: Todos os itens são obrigatórios, cliente compra o combo inteiro por um preço especial.

Kit Bundle (Customizável) ​

json
{
  "name": "Bundle de Verão",
  "items": [
    { "itemId": "...", "required": true, "quantity": 1 },
    { "itemId": "...", "required": false, "quantity": 1 },
    { "itemId": "...", "required": false, "quantity": 1 }
  ]
}

Descrição: Item obrigatório mais itens opcionais que cliente pode escolher incluir.

Kit Livre (Construtor de Kit) ​

json
{
  "name": "Construa Seu Kit",
  "items": [
    { "itemId": "...", "required": false, "quantity": 0 },
    { "itemId": "...", "required": false, "quantity": 0 },
    { "itemId": "...", "required": false, "quantity": 0 }
  ]
}

Descrição: Cliente escolhe livremente quais items incluir e em que quantidade.

Diferenças com Item ​

AspectoItemKit
PropósitoProduto individualAgrupamento de produtos
SKUsVariantes do mesmo produtoMúltiplos itens diferentes
PreçoPor SKUTotal do kit (pode ter desconto)
CustomizaçãoAtributos (cor, tamanho)Seleção de items
ValidaçãoTipo de item (product, recurrence, gift)Estratégia de seleção (required, optional, free-choice)