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_soldemetricssão números de negócio. Só vêm para chave comdeals:read, e contam só os negócios que o responsável pela chave enxerga ("Só o dele" vale). Semdeals:read, as chaves somem da resposta (e a coluna do CSV também) — nunca vêm zeradas.sales_countvem sempre0pela API — a contagem de vendas por período é da tela. Para "quanto vendeu no período", useGET/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_profitemarginnão existem na resposta, e mandarcost/tax_ratenuma escrita é ignorado — a resposta trazavisodizendo 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_stocksó 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 |