API atual/Referência completa/ERP Fiscal, contábil e custos

Custos e margem

Lê o custo médio e a margem de cada produto e grava custos manualmente.

Listar custos e margens

Custo médio é quanto, em média, cada unidade em estoque custou ao seller; ele é atualizado a cada recebimento de compra e a cada NF-e lançada, mas também pode ser informado na mão. A lista cruza o custo com o preço de venda para mostrar a margem de cada produto. Todos os produtos ativos do seller aparecem, tenham custo ou não.

GET/api/v1/vendor/erp/custosSeller

Lista custos e margens por produto

Parâmetros de consulta

product_iduuid

Só este produto.

warehouse_iduuid

Custo de um depósito. Omitido, mostra a visão consolidada (custo geral ou média ponderada dos depósitos).

searchstring

Busca parcial, sem diferenciar maiúsculas, no nome ou no SKU.

pageintegerpadrão: 1

Página, a partir de 1. Valor inválido ou menor que 1 volta para 1.

per_pageintegerpadrão: 50

Itens por página, de 1 a 200. Fora dessa faixa vale o padrão.

Exemplo de requisição: Listar custos e margens

bash

curl "$BASE_URL/api/v1/vendor/erp/custos?search=camiseta" \
  -H "Authorization: Bearer $TOKEN"

Resposta: Listar custos e margens

200Custos

json

{
  "costs": [
    {
      "product_id": "94e6917e-8733-4ddc-b446-ed85977117e8",
      "product_name": "Camiseta Básica Preta M",
      "sku": "CAM-PRE-M",
      "warehouse_id": "",
      "price_cents": 8990,
      "avg_cost_cents": 4990,
      "last_cost_cents": 5240,
      "margin_cents": 4000,
      "margin_pct": 44.49,
      "has_cost": true,
      "derived": false,
      "updated_at": "2026-10-11T14:30:00Z"
    }
  ],
  "total": 1
}

Campos da resposta

costsarray

Produtos da página, por nome.

product_iduuid

Produto.

product_namestring

Nome.

skustring

SKU.

warehouse_idstring

Eco do filtro warehouse_id; vazio na visão consolidada.

price_centsinteger

Preço de venda atual em centavos.

avg_cost_centsinteger

Custo médio em centavos. 0 se não há custo.

last_cost_centsinteger

Último custo.

margin_centsinteger

price_cents menos avg_cost_cents.

margin_pctnumber

Margem em %, com 2 casas: (preço - custo) / preço x 100. 0 se o preço é 0.

has_costboolean

true se há custo explícito ou derivado. Se false, ignore a margem: ela sai como 100%.

derivedboolean

true quando o custo é a média ponderada dos custos por depósito (só na visão consolidada).

updated_atdatetime

Última gravação do custo. null se derivado ou sem custo.

totalinteger

Total de produtos que atende ao filtro.

Erros: Listar custos e margens

Status	Quando	Corpo
500	Um filtro de id não é um UUID válido (a plataforma devolve 500, não 400).	`{"error":"failed to list costs","detail":"o valor \"xyz\" não é um uuid válido. Envie o identificador completo, com os 36 caracteres e os hífens. Corrija o campo e reenvie."}`
401	Cabeçalho `Authorization` ausente, token inválido, expirado ou revogado.	`{"error":"missing authorization header"}`
403	O token não é de um usuário seller (por exemplo, é de administrador).	`{"error":"insufficient permissions"}`
403	O usuário não está vinculado a um seller, ou o cadastro do seller ainda está em análise (`vendor_pending_review`).	`{"error":"no vendor account associated with this user"}`

Gravar custo

Grava (cria ou substitui) o custo de um produto, no geral ou para um depósito. Útil para carga inicial de custos antes da primeira compra. Os recebimentos e as NF-e seguintes recalculam o custo médio a partir do que estiver gravado.

PUT/api/v1/vendor/erp/custosSeller

Grava o custo de um produto

Corpo da requisição

product_iduuidobrigatório

Produto do próprio seller.

warehouse_iduuid

Depósito do seller. Omitido, grava o custo geral do produto.

avg_cost_centsintegerobrigatório

Custo médio em centavos, zero ou mais.

last_cost_centsinteger

Último custo. Omitido, usa o custo médio.

Exemplo de requisição: Gravar custo

bash

curl -X PUT "$BASE_URL/api/v1/vendor/erp/custos" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "product_id": "94e6917e-8733-4ddc-b446-ed85977117e8",
  "avg_cost_cents": 4990,
  "last_cost_cents": 5240
}'

Resposta: Gravar custo

200Custo gravado

json

{
  "id": "6b7c8d9e-0f10-4a21-b3c4-d5e6f7081920",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "product_id": "94e6917e-8733-4ddc-b446-ed85977117e8",
  "warehouse_id": "",
  "avg_cost_cents": 4990,
  "last_cost_cents": 5240,
  "created_at": "2026-10-11T14:30:00Z",
  "updated_at": "2026-10-11T14:30:00Z"
}

Campos da resposta

iduuid

Id do registro de custo.

vendor_iduuid

Seller dono.

product_iduuid

Produto.

warehouse_idstring

Depósito; vazio no custo geral.

avg_cost_centsinteger

Custo médio.

last_cost_centsinteger

Último custo.

created_atdatetime

Criação.

updated_atdatetime

Última gravação.

Erros: Gravar custo

Status	Quando	Corpo
400	Corpo não é um JSON válido.	`{"error":"invalid request body","detail":"invalid character 'b' looking for beginning of object key string"}`
400	`product_id` em branco.	`{"error":"vendorerp: product_id required"}`
400	Custo negativo.	`{"error":"vendorerp: avg_cost_cents must be >= 0"}`
404	O produto não existe ou não é do seller, ou o depósito não existe.	`{"error":"product not found"}`
401	Cabeçalho `Authorization` ausente, token inválido, expirado ou revogado.	`{"error":"missing authorization header"}`
403	O token não é de um usuário seller (por exemplo, é de administrador).	`{"error":"insufficient permissions"}`
403	O usuário não está vinculado a um seller, ou o cadastro do seller ainda está em análise (`vendor_pending_review`).	`{"error":"no vendor account associated with this user"}`

Veja também

Pedidos de compra

API atual/Referência completa/ERP Fiscal, contábil e custos

Custos e margem

Lê o custo médio e a margem de cada produto e grava custos manualmente.

Listar custos e margens

GET/api/v1/vendor/erp/custosSeller

Lista custos e margens por produto

Parâmetros de consulta

product_iduuid

Só este produto.

warehouse_iduuid

Custo de um depósito. Omitido, mostra a visão consolidada (custo geral ou média ponderada dos depósitos).

searchstring

Busca parcial, sem diferenciar maiúsculas, no nome ou no SKU.

pageintegerpadrão: 1

Página, a partir de 1. Valor inválido ou menor que 1 volta para 1.

per_pageintegerpadrão: 50

Itens por página, de 1 a 200. Fora dessa faixa vale o padrão.

Exemplo de requisição: Listar custos e margens

bash

curl "$BASE_URL/api/v1/vendor/erp/custos?search=camiseta" \
  -H "Authorization: Bearer $TOKEN"

Resposta: Listar custos e margens

200Custos

json

{
  "costs": [
    {
      "product_id": "94e6917e-8733-4ddc-b446-ed85977117e8",
      "product_name": "Camiseta Básica Preta M",
      "sku": "CAM-PRE-M",
      "warehouse_id": "",
      "price_cents": 8990,
      "avg_cost_cents": 4990,
      "last_cost_cents": 5240,
      "margin_cents": 4000,
      "margin_pct": 44.49,
      "has_cost": true,
      "derived": false,
      "updated_at": "2026-10-11T14:30:00Z"
    }
  ],
  "total": 1
}

Campos da resposta

costsarray

Produtos da página, por nome.

product_iduuid

Produto.

product_namestring

Nome.

skustring

SKU.

warehouse_idstring

Eco do filtro warehouse_id; vazio na visão consolidada.

price_centsinteger

Preço de venda atual em centavos.

avg_cost_centsinteger

Custo médio em centavos. 0 se não há custo.

last_cost_centsinteger

Último custo.

margin_centsinteger

price_cents menos avg_cost_cents.

margin_pctnumber

Margem em %, com 2 casas: (preço - custo) / preço x 100. 0 se o preço é 0.

has_costboolean

true se há custo explícito ou derivado. Se false, ignore a margem: ela sai como 100%.

derivedboolean

true quando o custo é a média ponderada dos custos por depósito (só na visão consolidada).

updated_atdatetime

Última gravação do custo. null se derivado ou sem custo.

totalinteger

Total de produtos que atende ao filtro.

Erros: Listar custos e margens

Status	Quando	Corpo
500	Um filtro de id não é um UUID válido (a plataforma devolve 500, não 400).	`{"error":"failed to list costs","detail":"o valor \"xyz\" não é um uuid válido. Envie o identificador completo, com os 36 caracteres e os hífens. Corrija o campo e reenvie."}`
401	Cabeçalho `Authorization` ausente, token inválido, expirado ou revogado.	`{"error":"missing authorization header"}`
403	O token não é de um usuário seller (por exemplo, é de administrador).	`{"error":"insufficient permissions"}`
403	O usuário não está vinculado a um seller, ou o cadastro do seller ainda está em análise (`vendor_pending_review`).	`{"error":"no vendor account associated with this user"}`

Gravar custo

PUT/api/v1/vendor/erp/custosSeller

Grava o custo de um produto

Corpo da requisição

product_iduuidobrigatório

Produto do próprio seller.

warehouse_iduuid

Depósito do seller. Omitido, grava o custo geral do produto.

avg_cost_centsintegerobrigatório

Custo médio em centavos, zero ou mais.

last_cost_centsinteger

Último custo. Omitido, usa o custo médio.

Exemplo de requisição: Gravar custo

bash

curl -X PUT "$BASE_URL/api/v1/vendor/erp/custos" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "product_id": "94e6917e-8733-4ddc-b446-ed85977117e8",
  "avg_cost_cents": 4990,
  "last_cost_cents": 5240
}'

Resposta: Gravar custo

200Custo gravado

json

{
  "id": "6b7c8d9e-0f10-4a21-b3c4-d5e6f7081920",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "product_id": "94e6917e-8733-4ddc-b446-ed85977117e8",
  "warehouse_id": "",
  "avg_cost_cents": 4990,
  "last_cost_cents": 5240,
  "created_at": "2026-10-11T14:30:00Z",
  "updated_at": "2026-10-11T14:30:00Z"
}

Campos da resposta

iduuid

Id do registro de custo.

vendor_iduuid

Seller dono.

product_iduuid

Produto.

warehouse_idstring

Depósito; vazio no custo geral.

avg_cost_centsinteger

Custo médio.

last_cost_centsinteger

Último custo.

created_atdatetime

Criação.

updated_atdatetime

Última gravação.

Erros: Gravar custo

Status	Quando	Corpo
400	Corpo não é um JSON válido.	`{"error":"invalid request body","detail":"invalid character 'b' looking for beginning of object key string"}`
400	`product_id` em branco.	`{"error":"vendorerp: product_id required"}`
400	Custo negativo.	`{"error":"vendorerp: avg_cost_cents must be >= 0"}`
404	O produto não existe ou não é do seller, ou o depósito não existe.	`{"error":"product not found"}`
401	Cabeçalho `Authorization` ausente, token inválido, expirado ou revogado.	`{"error":"missing authorization header"}`
403	O token não é de um usuário seller (por exemplo, é de administrador).	`{"error":"insufficient permissions"}`
403	O usuário não está vinculado a um seller, ou o cadastro do seller ainda está em análise (`vendor_pending_review`).	`{"error":"no vendor account associated with this user"}`

Veja também

Pedidos de compra