Produtos

O catálogo de produtos da conta, as categorias, e os produtos que entram em cada negócio (as linhas de produto, que somam o Valor do negócio).

O catálogo de produtos da conta, as categorias, e os produtos que entram em cada negócio (as linhas de produto, que somam o Valor do negócio).

Escopos: products:read para ler, products:write para criar, editar e excluir. Linha de produto de negócio pede dois escopos: products:read + deals:read para ler, products:write + deals:write para mexer. O responsável pela chave (§2) também precisa ter o módulo Produtos liberado — e, nas linhas de negócio, poder editar aquele negócio.

Método Escopo Descrição
GET/api/products products:read Lista o catálogo (paginado). Filtros: ?search=, ?type=, ?status=, ?category_id=, ?sort=, ?dir=, ?format=csv
GET/api/products/{id} products:read Um produto, com estoque e números de negócios
POST/api/products products:write Cria (201)
POST/api/products/batch products:write Cria ou atualiza até 100 produtos pelo SKU
PATCH/api/products/{id} products:write Edição parcial, inclusive SKU, custo e contagem de estoque
DELETE/api/products/{id} products:write Exclui (204) — ou arquiva, se o produto tem histórico de venda (200)
GET/api/product-categories products:read Categorias e subcategorias
POST/api/product-categories products:write Cria categoria (201), ou devolve a que já existe com o mesmo nome (200)
GET/api/deals/{id}/products products:read + deals:read Linhas de produto do negócio
POST/api/deals/{id}/products products:write + deals:write Define a linha de um produto no negócio (201 nova, 200 já existia)
PATCH/api/deals/{id}/products/{lineId} products:write + deals:write Muda quantidade, preço ou desconto de uma linha
DELETE/api/deals/{id}/products/{lineId} products:write + deals:write Remove a linha
POST/api/deals/{id}/products/replace products:write + deals:write Troca a lista inteira pela enviada
GET/api/reports/products reports:read + products:read + deals:read Quanto de cada produto foi vendido — ver §19

Todas as escritas aceitam Idempotency-Key (§5) e ?dry_run=true (§26).

O produto

{
  "id": "9f1e4b7a-2d5c-4f8e-8b3a-6c9d2e5f1a73",
  "name": "Camiseta Básica",
  "type": "physical",
  "status": "active",
  "unit": "UN",
  "track_stock": true,
  "base_price": 49.9,
  "effective_price": 49.9,
  "price_inherits": true,
  "category_id": null,
  "category_name": null,
  "subcategory_name": null,
  "sku": "CAM-1",
  "default_variant_id": "4e8b2f6d-7a1c-4d5e-9f4b-8a2c6e1d3b84",
  "variant_count": 1,
  "stock": 12,
  "total_sold": 1996,
  "sales_count": 0,
  "created_at": "2026-10-06T12:00:00.000Z",
  "custom_fields": {}
}

Esse é o item da listagem. GET/api/products/{id} devolve o cadastro completo em product (com marca, descrição, NCM, cobrança e external_id), a variação em variants (com em_estoque, em_orcamentos — o que está em negócios abertos — e disponivel), price_range, metrics (negócios abertos, em orçamento, ganhos e perdidos com esse produto) e custom_fields.

⛔ Cada produto é um produto — não existe grade de variação. Por baixo, todo produto tem uma variação, criada junto com ele. É o id dela que entra na linha do negócio: use o default_variant_id da listagem (ou variants[0].id do GET). SKU, código de barras, estoque mínimo, medidas e custo moram nela, mas se editam pelo PATCH do próprio produto.

  • total_sold e metrics são números de negócio. Só vêm para chave com deals:read, e contam só os negócios que o responsável pela chave enxerga ("Só o dele" vale). Sem deals:read, as chaves somem da resposta (e a coluna do CSV também) — nunca vêm zeradas.
  • sales_count vem sempre 0 pela API — a contagem de vendas por período é da tela. Para "quanto vendeu no período", use GET/api/reports/products.
  • ⛔ Custo, imposto, lucro e margem só aparecem se o responsável pela chave é dono ou administrador da conta, conferido a cada chamada. Para os outros, as chaves cost, tax_rate, tax_value, gross_profit e margin não existem na resposta, e mandar cost/tax_rate numa escrita é ignorado — a resposta traz aviso dizendo isso.

Listagem: padrão de 25 por página, até 100 (no CSV, padrão 100). ⚠️ O cursor guarda o tamanho da página: não mude o limit no meio da paginação, ou o cursor é recusado com 400. ?search= procura por nome, SKU e código de barras. ?status= aceita active ou inactive; produto excluído (arquivado) nunca aparece. ?sort= aceita name (padrão), sku, type, category, subcategory, price, stock, total_sold, sales_count, status, created, cost e margin (estes dois só ordenam para quem vê custo; os outros recebem por name), e ?dir= aceita asc (padrão) ou desc.

Criar e editar

curl -X POST https://app.salos.com.br/api/products \
  -H "Authorization: Bearer $SALOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Camiseta Básica", "base_price": 49.9, "sku": "CAM-1", "initial_stock": 10 }'
Campo Criar Editar Regras
name obrigatório opcional 1–200
type opcional opcional physical (padrão), digital ou service. Digital e serviço nunca controlam estoque
status opcional opcional active (padrão) ou inactive. Inativo continua na lista, mas não entra em negócio novo
category_id / subcategory_id opcional opcional precisam existir na conta; a subcategoria é filha da categoria
brand opcional opcional até 120
description opcional opcional até 2000
unit opcional opcional UN (padrão), PC, CX, PAR, KG, G, L, ML, M, M², M³, H, DIA, MÊS
billing opcional opcional one_time (padrão), monthly ou yearly
base_price opcional opcional ≥ 0, no máximo 2 casas decimais
track_stock opcional opcional controlar estoque; padrão ligado para produto físico
external_id opcional opcional até 200. Código de referência livre — não é único (ver §27)
sku opcional opcional até 100. Único na conta, sem diferenciar maiúscula — repetir é 409
barcode opcional opcional 8, 12, 13 ou 14 números
ncm opcional opcional 8 números. Só produto físico
weight_kg, height_cm, width_cm, length_cm opcional opcional 0 a 999.999. Só produto físico
stock_min opcional opcional estoque mínimo, ≥ 0 — quando o estoque cai abaixo dele sai o evento product.stock_low (uma vez por queda, não a cada movimento)
cost, tax_rate opcional opcional 🔒 só dono ou administrador grava. tax_rate é percentual, 0–100
initial_stock opcional — quantidade inicial em estoque, maior que zero. Só vale em produto que controla estoque
stock_count — opcional a contagem de agora — ver abaixo
custom_fields opcional opcional ver §28. Não vale no lote

A criação responde 201 com o produto completo (como o GET), mais variant_id (o id que vai na linha do negócio). Se algo do corpo não entrou, a resposta diz: aviso em texto, e estoque_inicial com "lancado", "ignorado" (o produto não controla estoque) ou "falhou" (o produto foi criado, mas o estoque não — acerte com stock_count). A edição responde 200 com o produto e changed_fields (o que mudou de verdade).

Acertar o estoque (stock_count): mande quanto existe agora (zero ou mais). O sistema compara com o estoque atual e lança a diferença como um ajuste — o mesmo que digitar o número na tela. Não existe lançamento de entrada ou saída: mande sempre o total contado. Repetir a mesma contagem não grava nada. Em produto que não controla estoque, 422 e nada é gravado.

A venda baixa o estoque sozinha (em produto que controla estoque). Quando um negócio com o produto é ganho, a quantidade sai do estoque; se ele deixa de ser ganho (ou a linha sai de um negócio ganho), volta. Cada movimento dispara product.updated.

Excluir

Produto que não está em nenhum negócio e nunca teve venda é apagado de vez: 204 (a contagem de estoque digitada some junto). Produto em algum negócio, ou com venda no histórico de estoque, é arquivado: some da lista e do seletor de produtos dos negócios, e os negócios antigos continuam mostrando a linha. A resposta é 200 com { "data": { "id": "…", "deleted": true, "archived": true } }. Arquivado não é o mesmo que "status": "inactive" — o inativo continua na lista. Produto arquivado recusa mudança de status com 400, e o SKU dele continua reservado (não pode ser usado em outro produto).

Lote

POST/api/products/batch recebe { "items": [ … ] }, até 100 itens e 512 KB. Cada item é o corpo da criação (sem custom_fields), e o lote é um upsert pelo SKU:

  • SKU que já existe na conta → atualiza aquele produto com os campos enviados (o que não veio não muda; initial_stock só vale na criação);
  • SKU novo, ou item sem SKU → cria.

Um item com problema não derruba os outros. A resposta é sempre 200, item a item:

{
  "data": {
    "resultados": [
      { "indice": 0, "ok": true, "id": "…", "acao": "criado" },
      { "indice": 1, "ok": true, "id": "…", "acao": "atualizado", "avisos": ["Custo e imposto ignorados: só administrador grava."] },
      { "indice": 2, "ok": false, "erro": "Esse código pertence a um produto excluído." }
    ]
  }
}

O mesmo SKU duas vezes no mesmo lote: só o primeiro vale, os repetidos voltam com erro. No ensaio, os itens que passariam voltam ok: true sem id.

Categorias

{ "data": [ { "id": "…", "name": "Vestuário", "parent_id": null }, { "id": "…", "name": "Camisetas", "parent_id": "…" } ], "pagination": { "next_cursor": null } }

São dois níveis: categoria (parent_id: null) e subcategoria (parent_id é a categoria). A lista vem inteira, por nome. Para criar, mande name (até 120) e, se for subcategoria, parent_id. Nome que já existe no mesmo nível (sem diferenciar maiúscula) não duplica: devolve a existente com 200 e created: false; categoria nova vem com 201 e created: true.

Produtos no negócio

{
  "data": [
    {
      "id": "…", "variant_id": "…", "product_id": "…",
      "product_name": "Camiseta Básica", "unit": "UN", "sku": "CAM-1",
      "quantity": 2, "unit_price": 49.9, "discount_pct": 10, "total": 89.82, "position": 1
    }
  ]
}

total = quantity × unit_price × (1 − discount_pct/100), arredondado a centavos. O unit_price é uma cópia do preço de quando a linha entrou — reajustar o catálogo depois não muda linha nenhuma. O Valor do negócio passa a ser a soma das linhas. Negócio sem nenhuma linha nunca tem o Valor tocado (o que foi digitado vale); remover a última linha leva o Valor a 0.

⛔ POST/api/deals/{id}/products DEFINE, não soma. Corpo: variant_id (obrigatório), quantity (obrigatório, maior que zero, até 3 casas), unit_price e discount_pct (0–100) opcionais. Se o produto já está no negócio, a quantidade vira a enviada — mandar o mesmo corpo duas vezes deixa a mesma quantidade. Na primeira vez, sem unit_price a linha copia o preço do catálogo e sem discount_pct o desconto é 0; numa linha que já existe, o que não veio não muda.

PATCH …/products/{lineId} aceita quantity, unit_price e discount_pct (valores absolutos). Trocar o produto de uma linha não existe — remova e adicione. POST …/products/replace recebe { "items": [ … ] } (até 500, mesmo formato do POST) e faz a lista do negócio ficar igual à enviada: o que não está sai, o que mudou é atualizado, o que é novo entra — e repetir a mesma lista não grava nada. "items": [] esvazia o negócio.

As respostas de escrita trazem value (o Valor do negócio depois da escrita) e value_changed; o POST traz também line_id e created, o replace traz inserted, updated e deleted, e os três (exceto o DELETE) devolvem a lista atualizada em items. Quando o Valor muda, o negócio dispara deal.updated uma vez.

Erro Código
Negócio inexistente, ou que a chave não enxerga ("Só o dele") 404
Produto (ou variação) inexistente nesta conta — no replace, se qualquer um não existe, nada é gravado 404
Produto inativo ou arquivado entrando no negócio 400
A chave enxerga o negócio mas não pode editá-lo (é de outro colega, "Só o dele" em editar) 403 forbidden_module
Falta products:write ou deals:write 403 forbidden_scope