Estrutura do item

Um Item é a entidade central de catálogo que representa um produto, recorrência (assinatura) ou presente. Cada item contém variantes (SKUs), atributos, imagens, conteúdo e informações de envio.

{
  "id": "698b8a825eaf8de7c5af8de7",
  "kind": "product",
  "name": "Camiseta Premium",
  "caption": "Camiseta 100% algodão de alta qualidade",
  "alias": "camiseta-premium-001",
  "active": true,
  "published": true,
  "shippable": true,
  "digital": false,
  "currency": "BRL",
  "community": "test",
  "supplierId": null,
  "formId": null,
  "requiresApproval": false,
  "createdAt": "2026-02-10T19:44:02.328Z",
  "updatedAt": "2026-02-12T20:46:11.133Z",
  "skus": [
    {
      "_id": "sku-001-blue-m",
      "alias": "#AB1234",
      "name": "Camiseta Premium - Azul M",
      "caption": "Azul | M",
      "price": {
        "amount": 9900,
        "currency": "BRL"
      },
      "priceFrom": {
        "amount": 12900,
        "currency": "BRL"
      },
      "inventoryId": "698b8a805eaf8de7c5af1cd0",
      "attributes": [
        {
          "key": "color",
          "value": "blue"
        },
        {
          "key": "size",
          "value": "M"
        }
      ],
      "gallery": [],
      "reference": null,
      "plan": null
    }
  ],
  "options": [
    {
      "_id": "color",
      "name": "Cor",
      "caption": "Escolha a cor",
      "options": [
        { "name": "Azul" },
        { "name": "Vermelho" },
        { "name": "Preto" }
      ]
    },
    {
      "_id": "size",
      "name": "Tamanho",
      "caption": "Escolha o tamanho",
      "options": [
        { "name": "P" },
        { "name": "M" },
        { "name": "G" },
        { "name": "GG" }
      ]
    }
  ],
  "package": {
    "weight": 300,
    "width": 30,
    "height": 40,
    "depth": 10
  },
  "gallery": [
    {
      "url": "https://cdn.layers.digital/uploads/.../camiseta-azul-1.jpg",
      "path": "/uploads/.../camiseta-azul-1.jpg",
      "mime": "image/jpeg",
      "width": 1200,
      "height": 1600,
      "size": 245680,
      "name": "camiseta-azul-1.jpg",
      "orientation": null
    }
  ],
  "tags": ["camiseta", "moda", "promoção"],
  "categories": ["vestuário", "masculino"],
  "content": [
    {
      "kind": "markdown",
      "markdown": "# Descrição do Produto\n\nCamiseta premium de algodão 100% com excelente durabilidade..."
    }
  ],
  "stats": {
    "channels": []
  },
  "observations": [],
  "magnetic": null
}

Campos principais

Campo	Tipo	Descrição
`id`	`string`	ID único do item
`kind`	`string`	Tipo do item. Valores possíveis: `product`, `recurrence`, `gift`
`name`	`string`	Nome do item (3-100 caracteres, obrigatório)
`caption`	`string`	Descrição curta do item (0-100 caracteres)
`alias`	`string \| null`	ID customizado único do item. Caso não informado, `null`
`active`	`boolean`	Indica se o item está ativo (padrão: `true`)
`published`	`boolean`	Indica se o item está publicado e visível (padrão: `true`)
`shippable`	`boolean`	Indica se o item pode ser enviado/entregue (padrão: `false`)
`digital`	`boolean \| null`	Indica se é um produto digital. Caso não informado, `null`
`currency`	`string`	Moeda no formato ISO 4217. Ex: `BRL`, `USD`
`community`	`string`	Comunidade (tenant) do item
`supplierId`	`string \| null`	ID do fornecedor/supplier associado. Caso não informado, `null`
`formId`	`string \| null`	ID do formulário customizado a preencher na compra. Caso não informado, `null`
`requiresApproval`	`boolean`	Indica se o item precisa de aprovação antes de ser ativado (padrão: `false`)
`skus`	`array<object>`	Lista de variantes do item (ver abaixo)
`options`	`array<object>`	Lista de atributos/opções do item (ex: Cor, Tamanho)
`package`	`object`	Informações de dimensões e peso para envio (ver abaixo)
`gallery`	`array<object>`	Array de imagens do item (primeira é a principal)
`tags`	`array<string>`	Tags descritivas do item
`categories`	`array<string>`	Categorias do item
`content`	`array<object>`	Conteúdo descritivo em Markdown
`stats`	`object`	Estatísticas de vendas e dados por canal
`observations`	`array<object>`	Histórico de observações/auditoria
`magnetic`	`object \| null`	Mídia magnética do item. Caso não informado, `null`
`createdAt`	`string (ISO 8601)`	Data e hora de criação
`updatedAt`	`string (ISO 8601)`	Data e hora da última atualização

Tipos de Item

Os itens são classificados em 3 tipos (discriminadores) com restrições e validações diferentes:

Tipo	Descrição	SKU com Plan	SKU com Price > 0	Caso de Uso
`product`	Produto simples com venda única	❌ Não permitido	✅ Obrigatório	Camiseta, livro, eletrônico
`recurrence`	Assinatura/cobrança recorrente	✅ Obrigatório	✅ Obrigatório	Netflix, Academia, Serviço mensal
`gift`	Presente/brinde gratuito	❌ Não permitido	❌ Não permitido (price = 0)	Brinde, amostra, cupom

Validações Automáticas:

Product: Todos os SKUs validam que plan seja null
Recurrence: Todos os SKUs validam que plan está preenchido
Gift: Todos os SKUs validam que plan é null E price = 0

`skus` (ItemSku[])

Lista de variantes do item. Cada SKU representa uma combinação de atributos e tem seu próprio preço e estoque.

"skus": [
  {
    "_id": "sku-001-blue-m",
    "alias": "#AB1234",
    "name": "Camiseta Premium - Azul M",
    "caption": "Azul | M",
    "price": {
      "amount": 9900,
      "currency": "BRL"
    },
    "priceFrom": {
      "amount": 12900,
      "currency": "BRL"
    },
    "inventoryId": "698b8a805eaf8de7c5af1cd0",
    "attributes": [
      {
        "key": "color",
        "value": "blue"
      },
      {
        "key": "size",
        "value": "M"
      }
    ],
    "gallery": [],
    "reference": {
      "resourceKind": "layers:group",
      "resourceId": "698b8a805eaf8de7c5af1cd1",
      "dynamicInventory": true,
      "dynamicForm": true
    },
    "plan": null
  }
]

Campos do SKU

Campo	Tipo	Descrição
`_id`	`string`	ID único do SKU (UUID v4, gerado automaticamente)
`alias`	`string \| null`	Código legível do SKU. Ex: `#AB1234`. Gerado automaticamente se não informado
`name`	`string \| null`	Nome customizado do SKU (sobrescreve nome do item se informado)
`caption`	`string \| null`	Descrição do SKU com atributos. Ex: `Azul \| M`. Gerado dinamicamente
`price`	`object`	Preço atual do SKU (Amount)
`price.amount`	`integer`	Valor em centavos (ex: 9900 = R$ 99,00)
`price.currency`	`string`	Moeda ISO 4217 (herda do item)
`priceFrom`	`object \| null`	Preço original antes da promoção (Amount). Caso não em promoção, `null`
`inventoryId`	`string`	ID do Inventory associado (criado automaticamente)
`attributes`	`array<object>`	Atributos do SKU que diferem este SKU de outros
`attributes[].key`	`string`	ID da opção (ex: `color`, `size`)
`attributes[].value`	`string`	Valor do atributo (ex: `blue`, `M`)
`gallery`	`array<object>`	Imagens específicas deste SKU (sobrescreve gallery do item)
`reference`	`object \| null`	Referência externa para integração com sistemas (ex: ERP). Caso não aplicável, `null`
`plan`	`object \| null`	Configuração de recorrência (obrigatório para `recurrence`). Caso não aplicável, `null`

Validações de SKU

Produto (kind: product): Não pode ter plan preenchido
Recorrência (kind: recurrence): Deve ter plan preenchido com frequência e ciclos
Presente (kind: gift): Não pode ter plan e deve ter price = 0
Aliases de SKU devem ser únicos dentro do item
Pelo menos 1 SKU é obrigatório
Se nenhum SKU é informado, usa defaultPrice como preço do SKU padrão

`options` (ItemOption[])

Lista de atributos/variações disponíveis para este item. Define as opções que os clientes podem escolher.

"options": [
  {
    "_id": "color",
    "name": "Cor",
    "caption": "Escolha a cor disponível",
    "options": [
      { "name": "Azul" },
      { "name": "Vermelho" },
      { "name": "Preto" },
      { "name": "Branco" }
    ]
  },
  {
    "_id": "size",
    "name": "Tamanho",
    "caption": "Escolha o tamanho",
    "options": [
      { "name": "P" },
      { "name": "M" },
      { "name": "G" },
      { "name": "GG" }
    ]
  }
]

Campos da Opção

Campo	Tipo	Descrição
`_id`	`string`	ID único da opção (slug do nome, 2-36 caracteres)
`name`	`string`	Nome da opção. Ex: `Cor`, `Tamanho`, `Capacidade` (1-32 caracteres)
`caption`	`string \| null`	Descrição curta da opção (0-32 caracteres). Caso não informada, `null`
`options`	`array<object>`	Array de valores possíveis
`options[].name`	`string`	Nome do valor. Ex: `Azul`, `M`, `64GB` (1-32 caracteres)

Validações de Opção

IDs das opções devem ser únicos dentro do item (não pode haver 2 color, size, etc.)
Nomes das opções devem ser únicos (case-insensitive)

`package` (Dimensões de Envio)

Informações sobre dimensões e peso do item para cálculo de frete e empacotamento.

"package": {
  "weight": 300,
  "width": 30,
  "height": 40,
  "depth": 10
}

Campo	Tipo	Descrição
`weight`	`integer \| null`	Peso em gramas. Caso não informado, `null`
`width`	`integer \| null`	Largura em centímetros. Caso não informada, `null`
`height`	`integer \| null`	Altura em centímetros. Caso não informada, `null`
`depth`	`integer \| null`	Profundidade em centímetros. Caso não informada, `null`

`gallery` (Media[])

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

"gallery": [
  {
    "url": "https://cdn.layers.digital/uploads/.../camiseta-1.jpg",
    "path": "/uploads/.../camiseta-1.jpg",
    "mime": "image/jpeg",
    "width": 1200,
    "height": 1600,
    "size": 245680,
    "name": "camiseta-1.jpg",
    "orientation": null
  },
  {
    "url": "https://cdn.layers.digital/uploads/.../camiseta-2.jpg",
    "path": "/uploads/.../camiseta-2.jpg",
    "mime": "image/jpeg",
    "width": 1200,
    "height": 1600,
    "size": 256320,
    "name": "camiseta-2.jpg",
    "orientation": null
  }
]

Campo	Tipo	Descrição
`url`	`string`	URL pública da imagem
`path`	`string`	Caminho interno da imagem
`mime`	`string`	Tipo MIME. Ex: `image/jpeg`, `image/png`
`width`	`integer \| null`	Largura em pixels. Caso não informada, `null`
`height`	`integer \| null`	Altura em pixels. Caso não informada, `null`
`size`	`integer`	Tamanho do arquivo em bytes
`name`	`string`	Nome do arquivo
`orientation`	`string \| null`	Orientação (portrait/landscape). Caso não informada, `null`

`content` (ItemContent[])

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

"content": [
  {
    "kind": "markdown",
    "markdown": "# Descrição Completa\n\n## Características\n\n- 100% algodão\n- Acabamento premium\n- Disponível em 4 cores"
  }
]

Campo	Tipo	Descrição
`kind`	`string`	Tipo de conteúdo. Valor padrão: `markdown`
`markdown`	`string`	Conteúdo em formato Markdown

`stats` (EntityStats)

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

"stats": {
  "channels": [
    {
      "_id": "698b8a805eaf8de7c5af1cd2",
      "sales": 156,
      "revenue": {
        "amount": 1544400,
        "currency": "BRL"
      }
    }
  ]
}

Campo	Tipo	Descrição
`channels`	`array<object>`	Array de estatísticas por canal
`channels[._id`	`string`	ID do canal
`channels[].sales`	`integer`	Total de vendas neste canal
`channels[].revenue.amount`	`integer`	Receita em centavos
`channels[].revenue.currency`	`string`	Moeda ISO 4217

Validações Detalhadas

Validações de Tipo de Item

Product (Produto Simples)

✅ SKUs podem ter qualquer nome
❌ SKUs não podem ter plan
✅ SKUs devem ter price > 0
✅ Múltiplos SKUs são permitidos

Recurrence (Assinatura)

✅ Todos os SKUs devem ter plan
✅ SKUs devem ter price > 0
✅ Múltiplos SKUs com planos diferentes são permitidos
📝 Preço é recalculado periodicamente

Gift (Presente)

❌ SKUs não podem ter plan
❌ SKUs devem ter price = 0
✅ Múltiplos SKUs são permitidos
📝 Entregue sem cobrança

Validações de SKU

Aliases de SKU devem ser únicos dentro do item
Se nenhum SKU existe e defaultPrice não está definido: erro
price.amount deve ser sempre positivo (validação Amount)
Atributos devem corresponder a opções do item

Validações de Opção

Nomes de opção não podem se repetir (case-insensitive)
IDs de opção não podem se repetir
Cada opção deve ter pelo menos 1 valor
Nomes de valores não podem ser vazios

Estados de Publicação

Flag	Significado
`active: true, published: true`	Item visível e ativo (pronta para venda)
`active: true, published: false`	Item ativo mas oculto (parado)
`active: false, published: false`	Item inativo/arquivado (todos os ItemLinks também ficarão inativos)

Guias

Marketplace integrado

Referência

Referências

Cobranças

Entregas

Formulários

Inventários

Itens

Kits

Vendas

Webhooks

Guia

Referência

Estrutura do item

Campos principais

Tipos de Item

`skus` (ItemSku[])

Campos do SKU

Validações de SKU

`options` (ItemOption[])

Campos da Opção

Validações de Opção

`package` (Dimensões de Envio)

`gallery` (Media[])

`content` (ItemContent[])

`stats` (EntityStats)

Validações Detalhadas

Validações de Tipo de Item

Validações de SKU

Validações de Opção

Estados de Publicação

Referência

Cobranças

Entregas

Formulários

Inventários

Itens

Kits

Vendas

Guia

Referência

Estrutura do item ​

Campos principais ​

Tipos de Item ​

skus (ItemSku[]) ​

Campos do SKU ​

Validações de SKU ​

options (ItemOption[]) ​

Campos da Opção ​

Validações de Opção ​

package (Dimensões de Envio) ​

gallery (Media[]) ​

content (ItemContent[]) ​

stats (EntityStats) ​

Validações Detalhadas ​

Validações de Tipo de Item ​

Validações de SKU ​

Validações de Opção ​

Estados de Publicação ​

Estrutura do item

Campos principais

Tipos de Item

`skus` (ItemSku[])

Campos do SKU

Validações de SKU

`options` (ItemOption[])

Campos da Opção

Validações de Opção

`package` (Dimensões de Envio)

`gallery` (Media[])

`content` (ItemContent[])

`stats` (EntityStats)

Validações Detalhadas

Validações de Tipo de Item

Validações de SKU

Validações de Opção

Estados de Publicação