Componente Sankhya - Detalhe do Produto – Sankhya Gestão de Negócios

O componente Detalhe do Produto consulta no Sankhya as informações cadastrais completas de um produto, retornando dados como descrição, unidade padrão, marca, grupo, características, regras comerciais e eventuais controles (ex.: sabor, tamanho, cor).

Esse componente é usado para:

Exibir informações detalhadas do produto no bot
Validar dados antes de adicionar ao carrinho
Identificar controles e variações disponíveis
Obter regras comerciais como desconto máximo ou agrupamento mínimo

bot-server: versão 1.7.0

bot-component-service: versão 1.3.0

Índice:

Interface do componente (leitura da tela)
Integração técnica
Estrutura do retorno (componente)
Mapeamento técnico dos campos
Campo especial: controls
Exemplos de uso no bot
Tratamento de erros
Boas práticas

Objetivo do componente

Disponibilizar no fluxo do bot os dados oficiais do cadastro de produtos do Sankhya, garantindo que as informações exibidas ao usuário estejam alinhadas com o ERP.

Interface do componente (leitura da tela)

Parâmetros

Configuração da consulta de produto

Campo	Descrição	Origem Sankhya
Código do Produto*	Código único do produto no Sankhya	`TGFPRO.CODPROD`

Esse campo pode receber:

ou uma variável do fluxo:

{{codigoProduto}}

Armazenamento

Campo	Descrição
Variável de armazenamento	Nome da variável que receberá o resultado da consulta
Variável de escopo global	Permite reutilizar os dados em qualquer ponto do fluxo

Exemplo:

produtoDetalhe

Integração técnica

A consulta utiliza o serviço da API Sankhya:

CRUDServiceProvider.loadRecords

Entidade principal:

Produto (TGFPRO)

Entidade auxiliar:

Volume (TGFVOL) → utilizada para retornar a descrição da unidade.

Exemplo de requisição

curl --location 'https://api.sankhya.com.br/gateway/v1/mge/service.sbr?serviceName=CRUDServiceProvider.loadRecords&outputType=json' \
--header 'Authorization: Bearer <TOKEN>' \
--header 'appkey: <APPKEY>' \
--header 'Content-Type: application/json' \
--data '{
"serviceName": "CRUDServiceProvider.loadRecords",
"requestBody": {
"dataSet": {
"rootEntity": "Produto",
"includePresentationFields": "S",
"tryJoinedFields": "true",
"parallelLoader": "true",
"offsetPage": "0",
"criteria": {
"expression": { "$": "CODPROD = ? AND ATIVO = ?" },
"parameter": [
{ "$": "1242", "type": "I" },
{ "$": "S", "type": "S" }
]
},
"entity": [
{
"path": "",
"fieldset": {
"list": "CODPROD,REFERENCIA,DESCRPROD,CODVOL,CODGRUPOPROD,USALOCAL,CODLOCALPADRAO,CODMARCA,MARCA,AGRUPMIN,DESCMAX,ATIVO,CARACTERISTICAS,COMPLDESC,HOMEPAGE,GRUPODESCPROD"
}
},
{
"path": "Volume",
"fieldset": { "list": "DESCRVOL" }
}
]
}
}
}'

Estrutura do retorno (componente)

Produto encontrado

{
  "found": true,
  "data": {
    "code": 1236,
    "reference": 91236,
    "description": "GUARANÁ SANTANA",
    "descriptionComplement": null,
    "characteristics": "Teste Caracteristicas",
    "control": null,
    "usesLocation": false,
    "defaultLocationCode": null,
    "minimumGrouping": null,
    "maxDiscount": 50,
    "active": true,
    "controls": [
      {
        "name": "Tamanho",
        "options": [
          "500ML",
          "1L",
          "2L"
        ]
      }
    ],
    "homepageUrl": null,
    "discountGroup": "TESTE",
    "defaultUnit": {
      "code": "UN",
      "description": "Unidade"
    },
    "group": {
      "code": 300000
    },
    "brand": {
      "code": 241,
      "name": "MINEIRO"
    }
  },
  "error": null
}

Produto não encontrado

{
  "found": false,
  "data": null,
  "error": null
}

Mapeamento técnico dos campos

Campo	Descrição	Campo Sankhya	Tabela
data.code	Código do produto	CODPROD	TGFPRO
data.reference	Referência do produto	REFERENCIA	TGFPRO
data.description	Descrição do produto	DESCRPROD	TGFPRO
data.descriptionComplement	Complemento da descrição	COMPLDESC	TGFPRO
data.characteristics	Características do produto	CARACTERISTICAS	TGFPRO
data.control	Controle do produto	CONTROLE	TGFPRO
data.usesLocation	Indica uso de local	USALOCAL	TGFPRO
data.defaultLocationCode	Local padrão	CODLOCALPADRAO	TGFPRO
data.minimumGrouping	Agrupamento mínimo	AGRUPMIN	TGFPRO
data.maxDiscount	Desconto máximo permitido	DESCMAX	TGFPRO
data.active	Produto ativo	ATIVO	TGFPRO
data.homepageUrl	URL/Homepage	HOMEPAGE	TGFPRO
data.discountGroup	Grupo de desconto	GRUPODESCPROD	TGFPRO
data.defaultUnit.code	Unidade padrão	CODVOL	TGFPRO
data.defaultUnit.description	Descrição da unidade	DESCRVOL	TGFVOL
data.group.code	Grupo do produto	CODGRUPOPROD	TGFPRO
data.brand.code	Código da marca	CODMARCA	TGFPRO
data.brand.name	Nome da marca	MARCA	TGFPRO

Campo especial: controls

Quando o retorno da API Sankhya contém informações na estrutura _rmd, o componente interpreta esses dados e gera a lista:

data.controls

Essa lista representa controles ou variações do produto, por exemplo:

Tamanho
Sabor
Cor
Modelo

Exemplo:

Tamanho
 - 500ML
 - 1L
 - 2L

Exemplos de uso no bot

Exibir detalhes do produto

Produto: {{produtoDetalhe.data.description}}
Marca: {{produtoDetalhe.data.brand.name}}
Unidade: {{produtoDetalhe.data.defaultUnit.description}}

Verificar se produto possui controle

Se {{produtoDetalhe.data.controls}} existir
→ Solicitar escolha da variação

Validar desconto máximo permitido

Desconto máximo permitido: {{produtoDetalhe.data.maxDiscount}}%

Tratamento de erros

Situação	Comportamento
Produto inexistente	`found = false`
Produto inativo	não retornado quando filtro ativo
Falha na API	`error` preenchido

Boas práticas

Sempre validar found antes de usar os dados
Verificar se o produto possui controles antes de pedir escolha ao usuário
Utilizar unidade padrão ao calcular preço
Respeitar minimumGrouping quando houver

Esse artigo foi útil?

Usuários que acharam isso útil: 0 de 0

Pesquisa

Componente Sankhya - Detalhe do Produto