VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/B2B: preços e pedidos programados

Itens da tabela de preço

Lista, grava em lote, exporta e importa por CSV as linhas de preço (produto, quantidade mínima, preço fixo ou desconto) de uma tabela.

Os itens são as linhas da tabela: cada uma liga um produto a uma quantidade mínima (min_qty) e a um de dois valores, price_cents (preço unitário fixo, em centavos) ou discount_bps (desconto sobre o preço base, em pontos-base: 600 = 6%). A chave de uma linha é o par produto e min_qty, então um produto pode ter degraus: min_qty 1 a R$ 50,00, min_qty 10 a R$ 45,00 e assim por diante.

Para poucas linhas use PUT /items (JSON). Para catálogo grande use import (CSV). Todas as rotas exigem o módulo b2b-pricing e o privilégio manage_b2b ou manage_promotions.

Não existe rota para remover um item

A API grava e atualiza itens, mas não tem exclusão de linha. Para tirar itens, importe um CSV com mode=replace (apaga tudo e grava só o arquivo) ou duplique a tabela e trabalhe na cópia.

Listar itens

Devolve as linhas da tabela, ordenadas por nome do produto e min_qty, com nome e SKU do produto para exibição.

GET/api/v1/admin/b2b/price-lists/{id}/itemsAdmin

Lista os itens de uma tabela

Parâmetros de caminho

iduuidobrigatório
Id da tabela.

Parâmetros de consulta

qstring
Busca por trecho do SKU ou do nome do produto (sem diferenciar maiúsculas).
pageintegerpadrão: 1
Página, a partir de 1.
per_pageintegerpadrão: 50
Itens por página, de 1 a 200. Fora disso volta para 50.

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/admin/b2b/price-lists/3f0c1a52-8d7e-4c1b-9a64-2b5e7d9c1a10/items?q=mesa&per_page=50" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Itens devolvidos
json
{
  "items": [
    {
      "id": "91418c7f-7dae-42a9-8d3a-1bb52e6ed16e",
      "price_list_id": "3f0c1a52-8d7e-4c1b-9a64-2b5e7d9c1a10",
      "product_id": "5b6f1948-356b-4739-adfc-af8045b7b769",
      "product_name": "Mesa Plus Cinza",
      "sku": "SD-004487",
      "min_qty": 1,
      "price_cents": 26250
    }
  ],
  "total": 1
}

Campos da resposta

itemsarray
Linhas da página.
totalinteger
Total de linhas que casam com q, em todas as páginas.
iduuid
Id da linha.
product_iduuid
Produto.
product_namestring
Nome do produto; ausente se o produto foi removido.
skustring
SKU do produto; ausente se o produto foi removido.
min_qtyinteger
Quantidade mínima para a linha valer (a partir de 1).
price_centsinteger
Preço unitário em centavos. Ausente em linhas de desconto.
discount_bpsinteger
Desconto em pontos-base (1 a 10000). Ausente em linhas de preço fixo.

Erros

StatusQuandoCorpo
500Id que não é UUID ou falha de consulta{"error":"failed to list items","detail":"..."}

A rota não confere se a tabela existe: um UUID válido inexistente devolve {"items":[],"total":0}.

Gravar itens em lote

Cria ou atualiza várias linhas de uma vez. A chave é product_id mais min_qty: se a linha existe, o preço ou desconto é substituído; se não, é criada. O lote é tudo ou nada, numa transação.

PUT/api/v1/admin/b2b/price-lists/{id}/itemsAdmin

Cria ou atualiza itens em lote

Parâmetros de caminho

iduuidobrigatório
Id da tabela.

Corpo da requisição

itemsarrayobrigatório

Linhas a gravar.

product_iduuidobrigatório
Produto. Precisa existir, senão o lote inteiro é recusado.
min_qtyintegerobrigatório
Quantidade mínima, 1 ou mais.
price_centsinteger
Preço unitário fixo em centavos, zero ou mais. Informe este ou discount_bps.
discount_bpsinteger
Desconto de 1 a 10000. Informe este ou price_cents.

Exemplo de requisição

bash
curl -X PUT "$BASE_URL/api/v1/admin/b2b/price-lists/3f0c1a52-8d7e-4c1b-9a64-2b5e7d9c1a10/items" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "product_id": "5b6f1948-356b-4739-adfc-af8045b7b769", "min_qty": 1, "price_cents": 26250 },
      { "product_id": "5b6f1948-356b-4739-adfc-af8045b7b769", "min_qty": 10, "discount_bps": 800 }
    ]
  }'

Resposta

200Itens gravados
json
{ "upserted": 2 }

Campos da resposta

upsertedinteger
Quantas linhas foram criadas ou atualizadas.

Erros

StatusQuandoCorpo
400JSON inválido{"error":"invalid request body","detail":"..."}
422Linha sem preço nem desconto, com os dois, com desconto fora de 1 a 10000, preço negativo ou min_qty menor que 1{"error":"failed to upsert items","detail":"item 0 (<product_id>): exactly one of price_cents or discount_bps must be set"}
422Produto ou tabela inexistente{"error":"failed to upsert items","detail":"upsert item <product_id>: ..."}
Vale na hora para tabelas ativas

Gravar itens numa tabela active já muda o preço de quem a recebe. Se items for uma lista vazia a resposta é {"upserted":0} e nada muda.

Exportar itens em CSV

Baixa todas as linhas da tabela como arquivo CSV, ordenado por SKU. É o formato que a importação lê de volta, então serve para editar numa planilha e reimportar.

GET/api/v1/admin/b2b/price-lists/{id}/exportAdmin

Exporta os itens em CSV

Parâmetros de caminho

iduuidobrigatório
Id da tabela.

Exemplo de requisição

bash
curl -o tabela.csv "$BASE_URL/api/v1/admin/b2b/price-lists/3f0c1a52-8d7e-4c1b-9a64-2b5e7d9c1a10/export" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Arquivo CSV
text
sku;min_qty;price;discount_percent
SD-004487;1;262,50;
SD-004487;10;;8

O arquivo é UTF-8 com BOM (abre direto no Excel em português), separado por ponto e vírgula, com Content-Type: text/csv; charset=utf-8 e Content-Disposition: attachment. A coluna price vem em reais com vírgula (262,50, sem separador de milhar) e discount_percent em porcentagem (8, 12,5). Em cada linha só uma das duas colunas vem preenchida.

Erros

StatusQuandoCorpo
404UUID válido que não existe{"error":"price list not found"}
500Id que não é UUID{"error":"price list operation failed","detail":"..."}

Importar itens de um CSV

Envia um arquivo e a plataforma processa em segundo plano: a rota responde 202 na hora com um job_id. Importar milhares de linhas leva mais que o limite de uma requisição, por isso nunca é síncrono.

POST/api/v1/admin/b2b/price-lists/{id}/importAdmin

Importa itens de um CSV

Parâmetros de caminho

iduuidobrigatório
Id da tabela.

Parâmetros de consulta

modestringpadrão: merge
mergereplace
merge grava por cima (atualiza o que existe, cria o que falta, mantém o resto). replace apaga todos os itens da tabela antes de gravar o arquivo. Qualquer outro valor vira merge.

Corpo da requisição (multipart/form-data)

filefileobrigatório
Arquivo CSV. O separador (; ou ,) é detectado pelo cabeçalho.

O CSV precisa ter cabeçalho com as colunas (sem diferenciar maiúsculas):

ColunaObrigatóriaConteúdo
skuSimSKU de um produto ativo.
min_qtySimInteiro, 1 ou mais.
priceUma das duasPreço em reais no formato brasileiro: 1.234,56, 262,50, 99. Aceita R$ na frente.
discount_percentUma das duasPorcentagem maior que 0 e até 100: 8, 12,5, 10%.

Use ou price ou discount_percent como coluna no arquivo inteiro. Ter as duas colunas é recusado.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/admin/b2b/price-lists/3f0c1a52-8d7e-4c1b-9a64-2b5e7d9c1a10/import?mode=merge" \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@tabela.csv;type=text/csv"

Resposta

202Importação enfileirada
json
{ "job_id": "c8a1f0d2-4b7e-4f93-a6d5-0e2b9c1d7a33", "status": "processing" }

Acompanhe o andamento em GET /api/v1/admin/import/jobs/{job_id}. O trabalho passa por processing e termina em completed ou failed. Em completed, created_count traz as linhas gravadas e skipped_count as linhas recusadas, cada uma descrita em errors (número da linha e motivo, por exemplo sku "ABC-1" not found or inactive). Uma linha ruim não derruba as outras: a importação é parcial.

Erros

StatusQuandoCorpo
400Formulário inválido ou sem o campo file{"error":"missing file","detail":"..."}
404Tabela inexistente{"error":"price list not found"}
409Já há uma importação rodando nesta tabela{"error":"import already running","detail":"another import is already running for this price list"}
422Arquivo vazio, sem sku ou min_qty, sem coluna de valor, com as duas colunas de valor{"error":"invalid CSV","detail":"missing required columns: sku and min_qty"}
500Falha ao enfileirar{"error":"failed to start import","detail":"..."}
Preço com ponto decimal vira milhar

No CSV o ponto é separador de milhar e a vírgula é o decimal. 262.50 é lido como 26.250,00 reais, não 262,50. Sempre escreva 262,50. A gravação em lote por JSON (PUT /items) não tem esse problema porque usa centavos inteiros.

O modo replace apaga antes de conferir

Com mode=replace todas as linhas atuais são apagadas e só então as do arquivo são gravadas, na mesma transação. Se o arquivo tiver SKUs inexistentes, essas linhas ficam de fora e a tabela fica sem elas. Faça antes um export como backup.

Veja também

  • Tabelas de preço
  • Atribuições
  • Simulador e reajuste
Anterior
Ativar, arquivar e duplicar
Próxima
Atribuições de tabela de preço
Nesta página
  • Listar itens
  • Exemplo de requisição
  • Resposta
  • Erros
  • Gravar itens em lote
  • Exemplo de requisição
  • Resposta
  • Erros
  • Exportar itens em CSV
  • Exemplo de requisição
  • Resposta
  • Erros
  • Importar itens de um CSV
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também