Documentação de Preços

Visão Geral

O módulo de Preços é responsável pela gestão financeira dos itens do catálogo, permitindo a definição de valores de venda e preços de comparação para cada produto. 💰

Para otimizar o gerenciamento de grandes inventários, a plataforma utiliza um modelo de processamento em lote (Batch).

Isso significa que as operações de atualização e remoção são projetadas para receber múltiplos registros em uma única requisição, reduzindo o overhead de rede e garantindo maior performance. 🚀

Cada preço está intrinsecamente ligado a uma Política Comercial, permitindo que o mesmo produto possua valores distintos dependendo do canal de venda (ex: B2B, B2C, Marketplace). 🏢

As operações de preço são críticas e possuem mecanismos de proteção, como o Throttle (limite de requisições), para garantir a estabilidade do sistema durante atualizações massivas.

Além disso, o sistema limpa automaticamente os caches relacionados para que os novos valores sejam refletidos imediatamente na loja. 🔄

O acesso a este módulo é restrito e exige o escopo de segurança PRODUCT_PRICE_WRITE para qualquer operação de modificação. 🔒

Funcionamento do Lote (Batch)

Ao enviar uma requisição de atualização, o sistema processa cada item do array de forma individualizada. 📋

Caso um item específico apresente erro (ex: produto não encontrado), o processamento dos demais itens continua normalmente, e a resposta retornará um relatório detalhado indicando o sucesso ou a falha de cada registro processado. ✅

Notas e Considerações

É fundamental garantir que o productId e o tradePolicyId informados em cada item do lote estejam corretos, pois a combinação destes dois campos é o que define univocamente qual preço será afetado. ⚠️

O sistema também permite a configuração de centavos fixos, garantindo que as atualizações automáticas mantenham o padrão visual de preços da loja (ex: sempre terminar em .90). 🛠️

Atualização de Preços em Lote

Descrição

Este endpoint permite a atualização simultânea de preços para uma lista de produtos. 🚀

A operação é otimizada para integrações de ERP e ferramentas de gestão, permitindo enviar um array de objetos onde cada item especifica o produto, a política comercial e o novo valor ou regra de alteração. 💰

O sistema suporta diferentes tipos de alteração, permitindo definir o preço final diretamente ou aplicar modificações baseadas em regras específicas. Além disso, é possível configurar o preço de comparação ("Preço De") e a disponibilidade para venda. 🛒

Um recurso avançado disponível é o de centavos fixos, que permite arredondar automaticamente os valores atualizados para um padrão visual desejado (ex: .99). 🛠️

A resposta deste endpoint é um relatório detalhado de cada item processado no lote, facilitando a identificação de erros pontuais sem interromper a operação global. ✅

Para executar esta operação, é obrigatório o escopo PRODUCT_PRICE_WRITE. 🔒

---

Parâmetros

Headers Obrigatórios

Parâmetros de Corpo (JSON)

O corpo da requisição deve conter um objeto com a chave products, contendo um array de itens.

Exemplo de Requisição

1curl --request PUT \
2  --url {{MAIN_URL}}/products/prices \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --data '{
5    "products": [
6      {
7        "productId": 101,
8        "tradePolicyId": 1,
9        "changeValue": 150.00,
10        "type": "Value",
11        "comparisonPrice": 200.00,
12        "availableForSale": true
13      },
14      {
15        "productId": 102,
16        "tradePolicyId": 1,
17        "changeValue": 10.50,
18        "type": "PercentageIncrease",
19        "fixCents": 0.90
20      }
21    ]
22  }'

✅ Resposta de Sucesso

O retorno é uma lista com o status de cada item processado.

1[
2  {
3    "productId": 101,
4    "tradePolicyId": 1,
5    "comparisonPrice": 200.0,
6    "changeValue": 150.0,
7    "fixCents": 0.90,
8    "type": "Value",
9    "availableForSale": true,
10    "error": null
11  }
12]

⚠️ Possíveis erros:

Remoção de Preços em Lote

Descrição

Este endpoint permite a exclusão em massa de preços configurados no catálogo. 🗑️

Através dele, é possível remover o vínculo de preço de múltiplos produtos em políticas comerciais específicas em uma única operação. Isso é especialmente útil para limpeza de dados ou descontinuação de tabelas de preços em canais de venda específicos. 🏢

Assim como na atualização, a remoção em lote processa cada item de forma independente e retorna o status final da operação (true/false). 🔄

A execução desta operação exige o escopo de segurança PRODUCT_PRICE_WRITE. 🔒

---

Parâmetros

Headers Obrigatórios

Parâmetros de Corpo (JSON)

O corpo da requisição deve conter um objeto com a chave products, contendo um array de itens de identificação.

Exemplo de Requisição

1curl --request DELETE \
2  --url {{MAIN_URL}}/products/prices \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --data '{
5    "products": [
6      {
7        "productId": 101,
8        "tradePolicyId": 1
9      },
10      {
11        "productId": 102,
12        "tradePolicyId": 2
13      }
14    ]
15  }'

✅ Resposta de Sucesso

1true

⚠️ Possíveis erros: