Modulo_Business_Intelligence_Smart_Component

Executar Smart Component

Recurso para iniciar componentes configurados no Touch Comp ERP, com parâmetros, perfil de execução e, quando aplicável, arquivo de entrada.

1. Para que serve

Um Smart Component é uma funcionalidade configurável que pode consultar, transformar ou gerar informações do ERP. Este recurso permite selecionar um componente, escolher um perfil de parâmetros já salvo e executá-lo ou gerar uma prévia do resultado.

Os parâmetros e o resultado dependem do componente selecionado. Por exemplo, um componente pode gerar um arquivo, processar um arquivo enviado ou apenas executar uma rotina em segundo plano.

2. Antes de começar

Pré-requisito	Detalhe
Acesso ao recurso	O usuário precisa ter acesso ao menu e ao Smart Component que deseja utilizar.
Componente publicado/configurado	O componente e seus parâmetros devem estar cadastrados pela equipe responsável.
Perfil, quando necessário	Se a operação utiliza um perfil, ele deve pertencer ao Smart Component selecionado.
Arquivo de entrada, quando aplicável	Componentes que processam arquivos exigem que o arquivo seja enviado ao ERP antes da execução.

O contexto da execução — empresa, usuário e grupo de usuários — é obtido automaticamente a partir do usuário autenticado. Portanto, o mesmo componente pode apresentar resultados diferentes para empresas ou usuários diferentes.

3. Como usar pela tela do ERP

No menu de Business Intelligence, abra Executar Smart Component.
Selecione o Smart Component desejado.
Opcionalmente, escolha um perfil. O perfil recupera valores previamente configurados para os parâmetros.
Aguarde o carregamento dos parâmetros e preencha ou revise seus valores.
Quando estiver disponível, use Pré-visualizar para gerar uma amostra antes da execução.
Clique em Executar. Para componentes que recebem arquivo, envie o arquivo e confirme o processamento.
Acompanhe a conclusão na Central de Notificações/Tarefas. As execuções são realizadas em segundo plano.

Se um campo estiver bloqueado, ele foi configurado para não permitir alteração. Se estiver marcado como obrigatório, informe um valor válido antes de executar.

4. Entendendo os parâmetros

Os parâmetros são definidos pelo próprio Smart Component. Não existe uma lista única de campos que seja válida para todos os componentes.

Informação exibida	Como usar
Descrição	Nome amigável do parâmetro mostrado ao usuário.
Chave do parâmetro	Identificador técnico do campo. É o nome que deve ser usado na integração por API.
Valor	Valor atual, que pode vir do cadastro do componente ou do perfil selecionado.
Obrigatório	Indica se o valor deve ser informado para a execução.
Permite alteração	Indica se o valor predefinido pode ser alterado pelo usuário.
Valores fixos	Quando existentes, escolha uma das opções disponibilizadas.
Pesquisa	Quando o parâmetro referencia um cadastro do ERP, selecione o registro pela pesquisa. Para múltiplos registros, o ERP armazena os identificadores separados por `;`.

Parâmetros podem ser organizados em grupos e subgrupos. Ao integrar, percorra também os parâmetros filhos: cada item que possui chaveParametro representa um valor que pode ser enviado.

5. Resultados e acompanhamento

O retorno imediato confirma apenas que a solicitação foi aceita ou informa um erro de validação. O processamento pode continuar depois dessa resposta.

Situação	Significado
`SUCESSO`	A consulta foi concluída ou a execução foi colocada na fila.
`ERRO`	A solicitação não pôde ser processada; verifique `message` e `detailMessage`.
Tarefa em segundo plano	Consulte a Central de Tarefas/Notificações até a situação ficar `COMPLETE`, `ERROR` ou `DELETED_CANCELLED`.

Quando o componente gera arquivo, o arquivo fica disponível como resultado da tarefa. Alguns componentes podem gerar texto, dados estruturados ou apenas concluir uma ação, conforme sua configuração.

6. Integração por API

6.1 Endereço-base e autenticação

Todos os endpoints deste recurso exigem um usuário autenticado. Substitua https://<servidor> pelo endereço da sua instalação:

https://<servidor>/auth/business-intelligence/smart-component/iniciar-smart-component

Envie os cabeçalhos abaixo nas chamadas que possuem corpo JSON:

Authorization: Bearer <token-de-acesso>
Content-Type: application/json
Accept: application/json

Use um usuário com acesso ao Smart Component e aos dados que ele utiliza. O token determina a empresa, o usuário e o grupo usados na execução; não envie credenciais ou dados de contexto no corpo da requisição.

6.2 Descobrir parâmetros antes de executar

Esta é a etapa recomendada para integrações. Ela retorna os parâmetros efetivos do componente, inclusive valores do perfil escolhido.

GET /auth/business-intelligence/smart-component/iniciar-smart-component/get-parameters-id/{idSmartComponent}
GET /auth/business-intelligence/smart-component/iniciar-smart-component/get-parameters-id/{idSmartComponent}/{idPerfilSmartComponent}

Exemplo:

curl --request GET \
  --header "Authorization: Bearer <token-de-acesso>" \
  "https://<servidor>/auth/business-intelligence/smart-component/iniciar-smart-component/get-parameters-id/123/45"

O campo result é uma lista de listas de parâmetros. Cada item pode ter smartComponentsParamsFilhos; processe a estrutura recursivamente. Os principais campos são:

Campo	Uso na integração
`chaveParametro`	Chave a ser enviada no objeto `params`. Preserve exatamente maiúsculas, minúsculas e caracteres.
`valorParametro`	Valor atual/padrão. Pode ser reutilizado quando não houver alteração.
`valorObrigatorio`	`1` significa que o valor deve ser informado; `0`, que é opcional.
`permitirAlterarValor`	`1` permite alterar o valor padrão; `0` indica valor controlado pela configuração.
`classeParametro`	Tipo técnico esperado; use-o para converter o valor no sistema integrador.
`tipoInfValor`	Define a forma de entrada do valor (texto, data, número, pesquisa, lista etc.).
`valorFixo`	Opções permitidas. Envie o respectivo `valorParametro`, não apenas a descrição.
`classePesquisa`, `metodoPesquisa` e `permiteInfMultiplosObjetos`	Metadados para parâmetros que pesquisam cadastros do ERP. Para múltiplos itens, use os IDs separados por `;`, como `"10;25;41"`.

Exemplo simplificado de resposta:

{
  "status": "SUCESSO",
  "result": [[
    {
      "descricao": "Data inicial",
      "chaveParametro": "DATA_INICIAL",
      "valorParametro": "2026-09-01",
      "valorObrigatorio": 1,
      "permitirAlterarValor": 1,
      "classeParametro": "java.util.Date",
      "tipoInfValor": 0,
      "smartComponentsParamsFilhos": []
    }
  ]]
}

6.3 Formato do corpo de execução

As chamadas de execução recebem o mesmo contrato:

{
  "input": null,
  "perfilName": "Perfil mensal",
  "params": {
    "DATA_INICIAL": "2026-09-01",
    "DATA_FINAL": "2026-09-30",
    "IDS_FILIAIS": "10;25"
  }
}

Campo	Tipo	Obrigatório	Descrição
`input`	string, lista de strings ou `null`	Depende do endpoint	Dados de entrada do componente. Em execução ou prévia sem conteúdo externo, use `null`.
`perfilName`	string ou `null`	Não	Nome do perfil a aplicar. Quando o ID do perfil está na URL, informe o nome correspondente quando ele estiver disponível.
`params`	objeto `string: string`	Não^*	Mapa formado pelas chaves retornadas em `chaveParametro`. Os valores são enviados como texto.

^* Os parâmetros obrigatórios do componente devem ser enviados. Para evitar perdas de valores predefinidos, consulte os parâmetros primeiro e envie todos os valores relevantes, inclusive os filhos. O ERP combina os valores da chamada com o contexto do usuário autenticado.

6.4 Endpoints disponíveis

Finalidade	Método e rota	`input`	Retorno imediato
Importar dados por código do componente	`POST /import-data/{codSmartComponent}`	Texto	Resultado síncrono do componente. Há variante com `/{idPerfilSmartComponent}`.
Importar dados por ID	`POST /import-data-id/{idSmartComponent}`	Texto	Resultado síncrono do componente. Há variante com perfil.
Processar arquivo por ID	`POST /import-data-id-file/{idSmartComponent}`	Lista com uma chave de arquivo já enviada ao ERP	Dados de uma tarefa assíncrona em `result`. Há variante com perfil.
Executar componente	`POST /execute-smart-component-id/{idSmartComponent}`	Normalmente `null`	Dados da tarefa assíncrona em `result`, incluindo `taskId`. Há variante com perfil.
Gerar prévia	`POST /preview-smart-component-id/{idSmartComponent}`	Normalmente `null`	Dados da tarefa assíncrona em `result`, incluindo `taskId`. Há variante com perfil.
Consultar parâmetros	`GET /get-parameters-id/{idSmartComponent}`	—	Metadados e valores atuais dos parâmetros. Há variante com perfil.

Todas as rotas da tabela são relativas ao endereço-base da seção 6.1. A forma com perfil acrescenta /{idPerfilSmartComponent} ao fim da rota, por exemplo:

POST /execute-smart-component-id/123/45

6.5 Exemplo: executar um componente

curl --request POST \
  --header "Authorization: Bearer <token-de-acesso>" \
  --header "Content-Type: application/json" \
  --data '{
    "input": null,
    "perfilName": "Perfil mensal",
    "params": {
      "DATA_INICIAL": "2026-09-01",
      "DATA_FINAL": "2026-09-30",
      "IDS_FILIAIS": "10;25"
    }
  }' \
  "https://<servidor>/auth/business-intelligence/smart-component/iniciar-smart-component/execute-smart-component-id/123/45"

Exemplo de resposta de aceite:

{
  "status": "SUCESSO",
  "messages": [],
  "result": {
    "taskId": "<codigo-da-tarefa>",
    "status": "SUBMITTED",
    "descricao": "<descricao-da-tarefa>",
    "taskType": "TEXT_MSG"
  },
  "countOf": 1
}

O código da tarefa é result.taskId. Guarde esse valor para consultar o andamento e obter o resultado. Os campos status e taskType acima são apenas ilustrativos: podem variar conforme o momento da resposta e o tipo de resultado produzido.

6.6 Acompanhar a tarefa e obter resultado

As tarefas pertencem ao usuário autenticado. Use o result.taskId recebido na chamada de execução, prévia ou processamento de arquivo para consultar a tarefa:

GET /auth/async-tasks/get-task/{taskId}
GET /auth/async-tasks/get-task-result-str/{taskId}
GET /auth/async-tasks/get-task-result-resource/{taskId}

Consulte o status da tarefa até chegar a COMPLETE, ERROR ou DELETED_CANCELLED. Para listar as tarefas do usuário autenticado, use GET /auth/async-tasks/get-tasks.

Resultado da tarefa	Como obter
Texto, entidade ou dados serializados	`GET /auth/async-tasks/get-task-result-str/{taskId}`
Arquivo	`GET /auth/async-tasks/get-task-result-resource/{taskId}`

Uma chamada de resultado feita enquanto a tarefa ainda está em execução retorna ERRO. Aguarde e tente novamente com intervalo apropriado. Ao receber ERROR, registre a mensagem devolvida pela API em vez de tratar o processamento como concluído.

6.7 Processamento de arquivo

O endpoint import-data-id-file não recebe o arquivo binário diretamente. Seu campo input deve conter uma lista com exatamente uma chave de arquivo que já tenha sido criada pelo fluxo de upload do ERP:

{
  "input": ["<chave-do-arquivo-enviado>"],
  "perfilName": "Importação padrão",
  "params": {
    "MODO_IMPORTACAO": "VALIDAR"
  }
}

Enviar lista vazia ou mais de uma chave é inválido. O endpoint devolve em result os dados da tarefa criada, incluindo taskId; use esse valor para acompanhar a conclusão e baixar o resultado quando houver arquivo.

7. Boas práticas para integrações

Consulte get-parameters-id antes de cada tipo de execução novo, depois de alterações no componente e ao trocar de perfil.
Não mantenha uma lista fixa de chaves de parâmetros: a configuração do componente pode mudar.
Envie valores como texto e respeite o formato indicado por classeParametro, tipoInfValor e valorFixo retornados pela API.
Use IDs — não descrições — nos parâmetros de pesquisa; para múltiplos itens, separe os IDs por ponto e vírgula (;).
Trate status: ERRO, message e detailMessage como parte normal do contrato de resposta.
Para não disparar duplicidades, registre a data/hora, o componente, o perfil e os parâmetros enviados antes de repetir uma chamada após falha de rede.
Proteja o token de acesso e não o registre em logs, URLs ou mensagens de erro.

Referência técnica: ControllerIniciarSmartComponent.

Problemas e Soluções

Opção de Pré-visualização não aparece

Deve estar marcado em 1947_Smart_Component a opção de pre-visualizar. Vale lembrar que não são todos os Smarts que possuem esta opção. É importante consultar a documentação técnica dele para mais detalhes sobre o suporte a esta opção. A grande maioria dos Smarts de importação suportam esta opção. Por outro lado, os de importação sobre layout especificos não suportam, como por exemplo um Smart que importa XML de notas fiscais. Afinal o arquivo a ser importado é o próprio XML da nota fiscal.

E.ERP.1947.002 - Tipo do Smart Componente não é valido para esta operacao. O mesmo deve ser do tipo condizente com a solicitação:{Smart}

Este problema ocorre quando tenta-se utilizar o Smart para um proposito em que ele não foi cadastrado. O Smart possui os seguintes tipos:

Execução
Importação

Quando tenta-se utilizar um Smart de Importação, mas usando o botão/ação Execução ou vice-versa, esta mensagem aparece. Isso tem a ver como o Smart coi cadastrado no 1947_Smart_Componente e o tipo definido internamente no seu código(classe), que tem de ser compativeis.

Parâmetros não são memorizados

Somente são memorizados os parametros se selecionado um perfil, e posteriormente ser realizado alguma ação sobre o smart: pre-visualizar, executar ou importar.

Reimportação e Integridade de Dados

Ao utilizar Smart Components de importação, é comum que ocorram erros parciais (ex: algumas linhas importam e outras não). Para garantir a integridade e evitar duplicidade, siga estas diretrizes:

Sempre utilize a última planilha de retorno: Se o sistema gerou um erro, ele disponibiliza uma planilha com os logs. Utilize este arquivo específico para correções, pois ele contém a coluna de "Status de Importação" que o sistema utiliza como referência. Faça as devidas correções nesse mesmo arquivo se possível.
Inteligência de Status (Coluna de Status):
- Status 1 (Sucesso): O sistema ignora automaticamente essas linhas em uma nova carga. Mantenha-os na planilha, isso evita que dados já existentes sejam sobrescritos ou duplicados.
- Status 0 ou Vazio (Erro/Pendente): O sistema tentará processar apenas estas linhas. Faça as devidas correções conforme o erro específico apontado na primeira tentativa, em caso de dúvidas sobre a mensagem de erro, entre em contato com um desenvolvedor(gestão interna) ou através do suporte da Touch Comp.
Adicionando novas linhas: Se precisar incluir novos dados em uma planilha que já foi parcialmente processada, basta adicionar as novas linhas ao final do arquivo e deixar a coluna de Status vazia. O sistema entenderá que são novos registros e tentará a importação.
Importante: Nunca apague ou altere a estrutura de cabeçalho da planilha de retorno, pois o Smart Component depende dela para identificar onde cada dado deve ser gravado.

1957 Iniciar Smart Component