Componente Sankhya - Volumes Alternativos

O componente Volumes Alternativos do Produto consulta na Sankhya as unidades alternativas disponíveis para comercialização/expedição de um produto (ex.: UN, CX, FD), retornando a equivalência com a unidade base e, quando configurado, regras de fator de preço (multiplica/divide) e informações complementares como cubagem.

bot-server: versão 1.6.0

bot-component-service: versão 1.2.0

Doc Sankhya: https://developer.sankhya.com.br/reference/get_loadrecords

Esse componente é útil para:

• Listar opções válidas de unidade no bot (ex.: “Unidade” vs “Caixa”)

• Calcular equivalência de quantidade na unidade base

• Definir regras comerciais por volume alternativo

• Respeitar configurações por controle quando existirem (sabor/cor/tamanho)

Índice:

• Objetivo do componente
• Integração técnica
• Interface do componente (tela)
• Dados do produto
• Armazenamento
• Estrutura do retorno
• Exemplo de resposta
• Descrição dos campos retornados
• Contextualização de negócio
• Exemplo de requisição (Sankhya)
• Exemplos de uso no bot
• Listar unidades alternativas para escolha do usuário
• Converter quantidade para unidade base
• Aplicar fator de preço (quando configurado)
• Tratamento de erros
• Alerta técnico de paginação (Sankhya)
• Tela no Sankhya OM
• Boas práticas

• Dados do Cliente

• Obter pedidos

• Itens do Pedido

• Criar Pedido

• Preço do Produto

• Estoque do Produto

• Locais de Estoque

• Volumes Alternativos

• Obter Preferência

• Tabela de Preço

• Tipo de Operação

• Tipos de Negociação

• Detalhe do Produto

• Busca de Produto

• Adicionar ao Carrinho

• Alterar Quantidade no Carrinho

• Obter Itens do Carrinho

---

Objetivo do componente

Disponibilizar no fluxo do bot as unidades alternativas cadastradas no Sankhya para um produto, permitindo que o usuário escolha a unidade correta e que a automação siga regras coerentes com o ERP.

---

Integração técnica

A consulta é realizada via serviço da API Sankhya:

• CRUDServiceProvider.loadRecords

• Entidade: VolumeAlternativo

• Relacionamento para apresentação: Volume (DESCRVOL)

O filtro normalmente considera:

• Produto (CODPROD)

• Ativo (ATIVO = 'S')

• (Opcional) regras por controle, quando aplicável

---

Interface do componente (tela)

Dados do produto

Campo	Descrição
Código do produto*	Código único do produto no Sankhya (CODPROD). Obrigatório.
Controle (opcional)	Quando utilizado, permite filtrar volumes associados a uma variação (sabor/cor/tamanho), se existir cadastro por controle.

Observação: na prática, muitos ambientes não vinculam volume alternativo ao controle. Quando existir, é um refinamento importante.

---

Armazenamento

Campo	Descrição
Variável de armazenamento	Variável que receberá o retorno (ex.: volumesAlternativos).
Variável de escopo Global	Quando ativada, a variável fica acessível em todo o fluxo.

---

Estrutura do retorno

Exemplo de resposta

---

Descrição dos campos retornados

Campo	Descrição
hasMore	Indica se existem mais itens para paginação
size	Total de volumes alternativos retornados (considerando filtros)
content	Lista de volumes/unidades alternativas
content[].unitCode	Código do volume/unidade alternativa (ex.: UN, CX)
content[].unitDescription	Descrição do volume/unidade alternativa
content[].baseUnitQuantity	Equivalência com unidade base (ex.: 1 CX = 24 UN)
content[].priceFactor	Fator de preço associado ao volume alternativo
content[].priceFactorOperation	Operação do fator: M (multiplica) ou D (divide)
content[].active	Indica se o volume alternativo está ativo
content[].cubicMeters	Cubagem (m³) quando configurada
content[].productControl	Controle vinculado ao volume (quando aplicável)
error	Detalhes do erro quando falhar (nulo em sucesso)

---

Contextualização de negócio

Volumes alternativos (unidades alternativas) representam formas adicionais de comercialização/expedição do mesmo produto, definindo:

• Equivalência com unidade base (ex.: “Caixa” = 24 “Unidades”)

• Fator de preço (multiplicar/dividir), quando configurado

• Cubagem (m³), quando aplicável

• Possível variação por controle (quando o cadastro existir)

Essas informações podem ser verificadas diretamente no Sankhya em:

Produtos → aba “Unidades Alternativas”

---

Exemplo de requisição (Sankhya)

A consulta é feita usando CRUDServiceProvider.loadRecords na entidade VolumeAlternativo, filtrando por produto e ativo, retornando também descrição do volume via entidade relacionada Volume.

' \ --header 'appkey: 3a51f41d-ebc4-429f-a888-55ff9fb48d34' \ --header 'Content-Type: application/json' \ --data '{ "serviceName": "CRUDServiceProvider.loadRecords", "requestBody": { "dataSet": { "rootEntity": "VolumeAlternativo", "includePresentationFields": "N", "offsetPage": "0", "criteria": { "expression": { "$": "ATIVO = ? AND CODPROD = ?" }, "parameter": [ { "$": "S", "type": "S" }, { "$": "1236", "type": "I" } ] }, "entity": [ { "path": "", "fieldset": { "list": "CODVOL, QUANTIDADE, MULTIPVLR, ATIVO, M3, DIVIDEMULTIPLICA" } }, { "path": "Volume", "fieldset": { "list": "DESCRVOL" } } ] } } }' ]]>

---

Exemplos de uso no bot

Listar unidades alternativas para escolha do usuário

• “Você quer comprar em qual unidade?”

  • UN - Unidade

  • CX - Caixa

Exemplo de leitura:

---

Converter quantidade para unidade base

Se o usuário pedir 2 caixas e baseUnitQuantity = 24:

• total base = 2 * 24 = 48 unidades

---

Aplicar fator de preço (quando configurado)

Se:

• priceFactorOperation = M

• priceFactor = 1.2

Então o preço ajustado pode ser:

• precoFinal = precoBase * 1.2

Observação: em muitos cenários, o fator de preço é só informativo e o preço final deve ser calculado pelo serviço de preço (seu componente de Preço do Produto).

---

Tratamento de erros

Situação	Comportamento
Produto sem unidade alternativa	size = 0, content = []
Falha na API	error preenchido
Paginação	respeitar hasMore e offsetPage

Iremos disponibilizar exemplos de erro em breve.

---

Alerta técnico de paginação (Sankhya)

A API da Sankhya pode retornar novamente a página 0 caso você envie offsetPage > 0 quando hasMore já for false.
Regra prática:

---

Tela no Sankhya OM

---

Boas práticas

• Sempre filtrar por ATIVO = 'S'

• Usar unidades alternativas para seleção do usuário antes do cálculo de preço

• Se houver controle, considerar filtrar/validar productControl

• Evitar paginação desnecessária (normalmente retorna poucos registros)

• Dados do Cliente

• Obter pedidos

• Itens do Pedido

• Criar Pedido

• Preço do Produto

• Estoque do Produto

• Locais de Estoque

• Volumes Alternativos

• Obter Preferência

• Tabela de Preço

• Tipo de Operação

• Tipos de Negociação

• Detalhe do Produto

• Busca de Produto

• Adicionar ao Carrinho

• Alterar Quantidade no Carrinho

• Obter Itens do Carrinho