API Admin › Recursos

Montagens

A montagem liga complementos a um produto: a armação de grau ganha o grupo "Tipo de lente" (obrigatório, escolhe um) e o grupo "Tratamentos" (opcional, escolhe vários), cada um com os produtos que valem nele. O comprador escolhe também a variante de cada produto (o material da lente, 1.50 ou 1.67). A montagem vale para as coleções e os produtos ligados a ela. Na montagem opcional (optional), o comprador pode levar o produto sozinho, como a armação sem lente; quando ele monta, os grupos obrigatórios valem do mesmo jeito.

Os complementos são produtos comuns do catálogo, com SKU, preço, promoção e NCM próprios: normalmente sob encomenda (inventory_tracked: false) e vendidos só junto (sold_separately: false), e a lente de grau com requires_prescription e a faixa de grau nas variantes (ver Produtos).

O objeto montagem

{
  "id": "4a7c...",
  "name": "Lentes de grau",
  "description": "As lentes são fabricadas em até 7 dias úteis depois da receita.",
  "active": true,
  "optional": true,
  "groups": [
    {
      "code": "lens",
      "name": "Tipo de lente",
      "required": true,
      "multiple": false,
      "product_ids": ["0b6f...", "91d2..."]
    },
    {
      "code": "treatments",
      "name": "Tratamentos",
      "required": false,
      "multiple": true,
      "product_ids": ["5c1e...", "e07a..."]
    }
  ],
  "collection_ids": ["7d1e..."],
  "product_ids": [],
  "incomplete": false,
  "created_at": "2026-10-07T12:00:00.000Z",
  "updated_at": "2026-10-07T12:00:00.000Z"
}

• description: o texto da loja para o comprador, mostrado ao montar (até 500 caracteres).
• active: false desliga a montagem sem apagá-la.
• optional: true deixa o comprador levar o produto sem nenhum complemento (a armação sem lente). Com algum complemento escolhido, os grupos required valem: o tratamento não vai sem a lente. false (o padrão na criação): o produto só vai montado, e o tema precisa oferecer a montagem na página do produto.
• groups: de 1 a 8, na ordem em que o comprador escolhe. code não se repete na montagem e vai na linha do pedido; sem ele, sai do name ("Tipo de lente" vira tipo-de-lente). required: quem monta precisa escolher algo no grupo. multiple: true deixa escolher vários produtos; false, um só. product_ids: de 1 a 30, na ordem em que aparecem.
• collection_ids (até 100) e product_ids (até 500): onde a montagem vale. Cada coleção e cada produto usa uma montagem só.
• incomplete: algum grupo obrigatório ficou sem nenhum produto à venda (todos ocultos). Enquanto isso, a vitrine vende os produtos ligados sem a montagem.

Qual montagem vale para o produto: a ligada a ele (product_ids) vence a das coleções; entre as coleções, vale a da principal ou de uma de cima dela, depois a da segunda coleção e as de cima, e assim por diante. Uma montagem desativada não vale, nem a que tem o próprio produto num grupo: um complemento não recebe montagem.

Um produto excluído sai dos grupos e das ligações; uma coleção excluída sai das ligações.

GET /assemblies

Todas as montagens da loja (no máximo 50), em ordem de nome, numa página só: { "data": [montagem...], "next_cursor": null }.

GET /assemblies/{id}

Uma montagem.

POST /assemblies

Cria a montagem. Responde 201 com ela. Só name e groups são obrigatórios; sem optional, a montagem é exigida.

{
  "name": "Lentes de grau",
  "description": "As lentes são fabricadas em até 7 dias úteis depois da receita.",
  "optional": true,
  "groups": [
    {
      "code": "lens",
      "name": "Tipo de lente",
      "required": true,
      "product_ids": ["0b6f...", "91d2..."]
    },
    {
      "code": "treatments",
      "name": "Tratamentos",
      "multiple": true,
      "product_ids": ["5c1e...", "e07a..."]
    }
  ],
  "collection_ids": ["7d1e..."]
}

PATCH /assemblies/{id}

Muda só o que vier. groups, collection_ids e product_ids trocam a lista inteira.

DELETE /assemblies/{id}

Exclui a montagem (204). As coleções e os produtos ligados ficam sem montagem; os produtos dos grupos continuam no catálogo.

Códigos