Skip to main content

​
Visão geral

O catálogo é o núcleo do OmniDom. Cada produto tem:
  • Tipo (SIMPLE, KIT, MANUFACTURED) que define seu comportamento de estoque.
  • Variações (cor, tamanho) com atributos e preços próprios.
  • Componentes (apenas para KIT/MANUFACTURED) — lista de produtos simples que compõem o item.
  • Custo calculado — para kits, o custo é a soma ponderada dos componentes.
Use o tipo KIT para produtos compostos vendidos como um único item. O estoque é deduzido dos componentes individuais a cada venda confirmada.

​
Tipos de produto

TipoEstoque próprioComponentesUso típico
SIMPLE✅❌Produto avulso
KIT❌✅Combo / bundle
MANUFACTUREDOpcional✅Produto fabricado internamente

​
Endpoints de produtos

​
Listar produtos

GET /products
Query params:
ParâmetroTipoDescrição
pagenumberPágina (padrão: 1)
limitnumberRegistros por página (padrão: 20, max: 100)
searchstringBusca em nome comercial e SKU
typestringFiltrar por tipo (SIMPLE, KIT, MANUFACTURED)
isActivebooleanFiltrar por status ativo/inativo
categoryIdUUIDFiltrar por categoria

​
Criar produto

POST /products
Content-Type: application/json
Body: 
{
  "commercialName": "Camiseta Branca P",
  "sku": "CAM-BCO-P",
  "type": "SIMPLE",
  "price": 49.90,
  "costPrice": 18.00,
  "minStock": 5,
  "categoryId": "uuid-da-categoria",
  "description": "Camiseta 100% algodão"
}
CampoTipoObrig.Descrição
commercialNamestring✅Nome exibido nos anúncios
skustring✅Código único por tenant
typeenum✅SIMPLE, KIT ou MANUFACTURED
pricenumber✅Preço de venda
costPricenumberCusto unitário (relevante para SIMPLE)
minStocknumberEstoque mínimo para alertas
categoryIdUUIDCategoria do produto

​
Detalhar produto

GET /products/:id
Retorna o produto com variações e, se for kit, a lista de componentes inclusa.

​
Atualizar produto

PATCH /products/:id
Content-Type: application/json
Aceita os mesmos campos do POST /products. Apenas os campos enviados são atualizados.

​
Excluir produto

DELETE /products/:id
Soft delete — o produto é marcado como inativo. Não pode ser excluído se tiver estoque positivo ou anúncios ativos.

​
Variações

Produtos do tipo SIMPLE podem ter variações (ex: cor + tamanho). Cada variação tem seu próprio SKU, preço e estoque.

​
Listar variações

GET /products/:productId/variations

​
Criar variação

POST /products/:productId/variations
Content-Type: application/json
Body: 
{
  "sku": "CAM-BCO-M",
  "price": 49.90,
  "attributes": [
    { "name": "Cor", "value": "Branco" },
    { "name": "Tamanho", "value": "M" }
  ]
}

​
Componentes (Kits)

Somente produtos KIT ou MANUFACTURED têm componentes. Um componente é sempre um produto SIMPLE.
Kits aninhados não são permitidos — você não pode adicionar um KIT como componente de outro KIT.

​
Listar componentes

GET /products/:productId/components
Retorna os componentes com paginação por cursor (keyset pagination). Máximo de 500 por requisição. Query params:
ParâmetroTipoDescrição
cursorstringCursor base64 para paginação
limitnumberMáximo: 500
Resposta: 
{
  "data": [
    {
      "id": "comp-uuid",
      "componentId": "product-uuid",
      "quantity": 2,
      "lossPercentage": 5,
      "isMainItem": true,
      "displayInDescription": true,
      "affectsPrice": true,
      "unitCostSnapshot": 10.50,
      "component": {
        "id": "product-uuid",
        "commercialName": "Resistor 10k",
        "sku": "RES-10K",
        "price": 5.25
      }
    }
  ],
  "nextCursor": "eyJjcmVhdGVkQXQiOiIyMDI2LTAxLTAxIiwiaWQiOiJ1dWlkIn0=",
  "hasMore": false
}

​
Adicionar componente

POST /products/:productId/components
Content-Type: application/json
Body: 
{
  "componentId": "uuid-do-produto-simples",
  "quantity": 2,
  "lossPercentage": 5,
  "isMainItem": true,
  "displayInDescription": true,
  "affectsPrice": true
}
CampoTipoDescrição
componentIdUUIDID do produto SIMPLE a adicionar
quantitynumberQuantidade usada por unidade do kit
lossPercentagenumberPerda esperada em % (ex: 5 = 5%)
isMainItembooleanIndica se é o item principal do kit
displayInDescriptionbooleanExibir componente na descrição do anúncio
affectsPricebooleanInclui custo do componente no cálculo de preço

​
Atualizar componente

PUT /products/:productId/components/:componentId
Content-Type: application/json

​
Remover componente

DELETE /products/:productId/components/:componentId

​
Custo do produto

GET /products/:productId/cost-summary
Retorna um snapshot do custo calculado do produto. Para kits, o cálculo é recursivo com base nos componentes.
Este endpoint usa cache. Alterações em componentes ou estoque podem levar alguns segundos para refletir (Eventual Consistency).
Resposta: 
{
  "productId": "uuid",
  "type": "KIT",
  "totalCost": 32.50,
  "components": [
    {
      "componentId": "uuid",
      "name": "Resistor 10k",
      "sku": "RES-10K",
      "quantity": 2,
      "unitCost": 10.50,
      "totalCost": 21.00,
      "lossPercentage": 5
    }
  ]
}