Manual do usuário e documentação técnica

Visão Geral

Visão geral do Taxcel Studio: objetivo e mensagem ao usuário.

Mensagem ao Usuário do Taxcel Studio

O Taxcel Studio é uma solução desktop desenvolvida pela Taxcel Soluções Fiscais S.A., projetada para apoiar profissionais da área fiscal e tributária na análise, tratamento e geração de informações fiscais de forma segura, eficiente e controlada.

A aplicação foi concebida com foco em segurança da informação, desempenho local, conformidade regulatória e integração controlada com serviços em nuvem, especialmente para funcionalidades avançadas como Inteligência Artificial.

Objetivo da Aplicação

O Taxcel Studio tem como principais objetivos:

• Apoiar a análise e manipulação de dados fiscais de forma local e segura;

• Garantir que dados não sejam transmitidos desnecessariamente pela rede;

• Oferecer recursos avançados de automação e inteligência sem acesso direto às bases de dados do cliente;

• Atender requisitos de conformidade com normas e boas práticas de segurança da informação.

Nós de importação

No Taxcel Studio, você pode importar dados de diferentes fontes e formatos para utilizá-los em seus fluxos de trabalho. A plataforma permite importar arquivos CSV, TXT, XML, PDF, OFX, JSON e planilhas Excel, além de obrigações fiscais, documentos fiscais eletrônicos, dados via API e informações provenientes de bancos de dados externos.

Após a importação, os dados são estruturados em tabelas e ficam disponíveis para tratamento, análise e utilização nas demais etapas do fluxo.

Importar CSV

Importa arquivos CSV, com valores separados por delimitadores, e converte os dados em uma tabela para utilização no fluxo. O recurso possui detecção automática de encoding, como UTF-8, Windows-1252 e Latin-1, permitindo que arquivos com acentos e caracteres especiais sejam interpretados corretamente.

1. Abra a configuração do nó Importar CSV.

2. Em Arquivo CSV, clique em Selecionar arquivo(s).

3. Na janela Abrir, selecione o arquivo (ou os arquivos) e clique em Abrir. Mais detalhes em Selecionar arquivos e pastas.

Também é possível arrastar o arquivo para a área indicada.

1. Em Delimitador de Dados, selecione Ponto e vírgula (;) ou Vírgula (,), conforme a separação utilizada no arquivo.

2. Em Separador de casas decimais, escolha Ponto (.) ou Vírgula (,) de acordo com os valores do arquivo.

3. Em Formato de data, selecione o formato correspondente aos dados do arquivo.

4. Em Range de linhas, mantenha Todas as linhas para importar o conteúdo integral ou desmarque a opção para informar o intervalo desejado. Em Range de colunas, mantenha Todas as colunas para importar todas.

5. Em Primeira linha é cabeçalho?, indique se a primeira linha do arquivo contém os nomes das colunas.

6. Clique em Executar e verifique o Status da última execução.

Importar Obrigações

Importa arquivos no formato PIPE, compostos por campos separados pelo caractere "|", como os utilizados em diversas obrigações fiscais brasileiras, incluindo as obrigações do SPED (EFD ICMS/IPI, EFD Contribuições, ECD e ECF) e os arquivos das Portarias CAT 42, 83 e 207, transformando suas informações em dados estruturados para utilização no fluxo.

1. Abra a configuração do nó Importar Obrigações.

2. Em Arquivo PIPE (.txt), clique em Selecionar arquivo(s).

3. Na janela Abrir, selecione o arquivo (ou os arquivos) e clique em Abrir. Mais detalhes em Selecionar arquivos e pastas.

Também é possível arrastar arquivos .txt para a área indicada.

1. Para importar os arquivos de uma pasta, clique em Selecionar pasta. Navegue até a pasta desejada, confira o campo Pasta e clique em Selecionar pasta para confirmar.

Janela Selecionar pasta do Windows, com campo Pasta e botões Selecionar pasta e Cancelar.

1. Em Tipo de Obrigação, escolha a opção correspondente ao arquivo: EFD_ICMS, EFD_CONTRIB, ECD_CONTABIL, ECF, CAT_42, CAT_83 ou CAT_207.

2. Confira os arquivos e o tipo de obrigação selecionados.

3. Clique em Executar e verifique o Status da última execução.

Importar XML (DFe)

Importa e interpreta arquivos XML fiscais brasileiros, como NF-e, CT-e, CF-e e DeRE, extraindo suas informações e convertendo os dados para um formato tabular que pode ser utilizado nas demais etapas do fluxo.

1. Abra a configuração do nó Importar XML (DFe).

2. Em Arquivos XML, clique em Selecionar arquivo(s).

3. Na janela Abrir, selecione o arquivo (ou os arquivos) e clique em Abrir. Mais detalhes em Selecionar arquivos e pastas.

Como alternativa, arraste-os para a área indicada.

1. Para importar os arquivos de uma pasta, clique em Selecionar pasta. Navegue até a pasta desejada, confira o campo Pasta e clique em Selecionar pasta para confirmar.

Janela Selecionar pasta do Windows, com campo Pasta e botões Selecionar pasta e Cancelar.

1. Em Tipo de XML, selecione NFe, CTe, CFe ou DeRE, conforme o arquivo.

2. Clique em Executar e verifique o Status da última execução.

Baixar NFS-e Nacional

O Taxcel Studio também permite realizar a importação de NFS-e Nacional diretamente do ambiente da Receita Federal, utilizando certificado digital para autenticação e acesso às informações. O recurso automatiza a busca dos documentos e os disponibiliza diretamente no fluxo, reduzindo a necessidade de processos manuais. Para realizar a importação, é necessário configurar os parâmetros solicitados, como CNPJ e certificado digital. Com essas informações definidas, o nó realiza a consulta e importa as NFS-e disponíveis para utilização nas demais etapas do processo.

1. Abra o nó Baixar NFS-e Nacional. O próprio nó importa os XMLs e gera as tabelas, sem exigir um nó Importar XML posteriormente.

2. Confira URL base, que vem preenchida por padrão com https://adn.nfse.gov.br, e preencha Endpoint de distribuição se necessário. Use {NSU} e {CNPJ} nos locais dos respectivos valores. Deixe o endpoint vazio para utilizar o padrão.

3. Para a configuração por CNPJ informado diretamente, deixe desmarcada a opção Usar dados de uma tabela (modo híbrido) e preencha CNPJ de consulta, com ou sem máscara.

4. Em Modo do certificado, escolha Instalado no Windows ou Arquivo .pfx. Para o certificado instalado, informe o Thumbprint obtido em certmgr.msc → Pessoal → Certificados → certificado → Detalhes → Impressão digital. Os espaços são ignorados e a senha não é solicitada nem armazenada nesse modo. Para Arquivo .pfx, carregue o arquivo do certificado e informe a senha.

Tela de configuração do nó Baixar NFS-e Nacional (parte 1 de 3).

1. Em Diretório de saída, informe uma pasta se desejar manter os XMLs baixados. Será criada uma subpasta por CNPJ. Deixe o campo vazio para importar os XMLs e descartá-los após o processamento.

2. Em Organização das tabelas, selecione Separadas por CNPJ para identificar as tabelas pelo padrão {NomeDoNo}_{CNPJ}_{elemento}.

3. Configure NSU inicial: deixe vazio ou informe 0 para continuar de onde parou, ou informe um valor para reprocessar a partir dele. Defina se deseja manter Continuar de onde parou marcado.

4. Expanda Avançado e defina Máximo de lotes por execução e Downloads simultâneos conforme a necessidade do processo.

Tela de configuração do nó Baixar NFS-e Nacional (parte 2 de 3).

1. Configure Pausa entre lotes (ms), Tentativas ao receber 429 e Pausa entre CNPJs (ms) conforme os intervalos de espera e as tentativas desejadas.

2. Se precisar de cabeçalhos adicionais, clique em Adicionar header, em Headers adicionais, e preencha Nome do header e Valor.

3. Para consultar CNPJs de uma tabela, conecte a tabela à entrada do nó e marque Usar dados de uma tabela (modo híbrido). O nó faz uma consulta por linha, utilizando um CNPJ por vez.

4. Clique em Executar e verifique o Status da última execução.

Tela de configuração do nó Baixar NFS-e Nacional (parte 3 de 3).

Baixar NF-e

O Taxcel Studio conta com um nó específico para realizar a importação de NF-e diretamente para o fluxo, de forma prática e automatizada. Por meio desse recurso, é possível importar os documentos fiscais a partir dos parâmetros definidos pelo usuário, sem a necessidade de importar os arquivos manualmente. Para utilizar a funcionalidade, é necessário configurar informações como CNPJ, estado e certificado digital. Após a configuração, o nó realiza a comunicação necessária para localizar e importar as NF-e correspondentes, disponibilizando os dados para uso nas próximas etapas do fluxo.

1. Abra a configuração de Baixar NF-e. O próprio nó importa os XMLs e gera as tabelas.

2. Em Ambiente, selecione o ambiente da consulta. Essa seleção também define a URL do Web Service.

3. Para informar os dados diretamente, mantenha Usar dados de uma tabela (modo híbrido) desmarcado. Preencha CNPJ destinatário, com ou sem máscara, e selecione UF (código IBGE).

4. Em Modo do certificado, escolha Instalado no Windows ou Arquivo .pfx. Para o certificado instalado, preencha Thumbprint do certificado com a impressão digital obtida em certmgr.msc → Pessoal → Certificados → certificado → Detalhes → Impressão digital; a senha não é solicitada nem armazenada nesse modo. Para Arquivo .pfx, carregue o arquivo do certificado e informe a senha.

Tela de configuração do nó Baixar NF-e (parte 1 de 3).

1. Configure Diretório de saída se quiser salvar os XMLs em disco. A pasta é opcional e contém uma subpasta por CNPJ. Sem diretório, os XMLs são importados e descartados.

2. Em Organização das tabelas, selecione Separadas por CNPJ para identificar as tabelas pelo padrão {NomeDoNo}_{CNPJ}_{elemento}.

Tela de configuração do nó Baixar NF-e (parte 2 de 3).

1. Configure NSU inicial e as opções Continuar de onde parou, Reiniciar do zero e Respeitar janela de espera da SEFAZ. Reiniciar ignora o NSU salvo; continuar mantém um arquivo de controle por CNPJ.

2. Em Filtros (aplicados após o download), informe Data início e Data fim caso deseje aplicar o filtro local pela data de emissão.

3. Em Tipos de documento, selecione NF-e completa (procNFe), Resumo da NF-e (resNFe), Evento (procEventoNFe) ou Resumo de evento (resEvento), conforme a necessidade. Deixe sem seleção para importar todos os tipos.

4. Para consultar CNPJs de uma tabela, conecte a tabela à entrada do nó e marque Usar dados de uma tabela (modo híbrido). O nó faz uma consulta por linha, utilizando um CNPJ por vez.

5. Clique em Executar e verifique o Status da última execução.

Tela de configuração do nó Baixar NF-e (parte 3 de 3).

Importar XML Genérico

Importa arquivos XML de diferentes estruturas, não se limitando aos documentos fiscais, e converte suas informações em formato tabular para utilização no fluxo.

1. Abra a configuração do nó Importar XML Genérico.

2. Em Arquivos XML, clique em Selecionar arquivo(s).

3. Na janela Abrir, selecione o arquivo (ou os arquivos) e clique em Abrir. Mais detalhes em Selecionar arquivos e pastas.

Também é possível arrastar os arquivos para a área indicada.

1. Para importar os arquivos de uma pasta, clique em Selecionar pasta. Navegue até a pasta desejada, confira o campo Pasta e clique em Selecionar pasta para confirmar.

Janela Selecionar pasta do Windows, com campo Pasta e botões Selecionar pasta e Cancelar.

1. Confira os arquivos selecionados.

2. Clique em Executar e verifique o Status da última execução.

Tela de configuração do nó Importar XML Genérico.

Importar TXT (Linha Inteira)

Importa arquivos TXT mantendo cada linha completa do arquivo em uma única coluna, sem interpretar layouts ou delimitadores. É indicado para arquivos de texto em que cada linha representa um registro completo, preservando o conteúdo original para utilização nas próximas etapas do fluxo. As linhas vazias são ignoradas automaticamente durante a importação.

1. Abra o nó Importar TXT (Linha Inteira).

2. Em Arquivo TXT (.txt), clique em Selecionar arquivo(s).

3. Na janela Abrir, selecione o arquivo (ou os arquivos) e clique em Abrir. Mais detalhes em Selecionar arquivos e pastas.

Como alternativa, arraste os arquivos .txt para a área indicada.

1. Para importar os arquivos de uma pasta, clique em Selecionar pasta. Navegue até a pasta desejada, confira o campo Pasta e clique em Selecionar pasta para confirmar.

Janela Selecionar pasta do Windows, com campo Pasta e botões Selecionar pasta e Cancelar.

1. Em Nome da coluna, informe o nome da coluna que receberá o conteúdo. Deixe vazio para utilizar linha.

2. Em Modo de leitura, selecione Linha a linha para que cada linha do arquivo corresponda a uma linha da tabela.

3. Em Modo de saída, selecione Uma tabela por arquivo para identificar cada tabela pelo padrão {NomeDoNo}_nomeDoArquivo.

4. Clique em Executar e verifique o Status da última execução.

Tela de configuração do nó Importar TXT (Linha Inteira).

Importar PDF

Extrai o texto de arquivos PDF, como DARF, PER/DCOMP e outros documentos, convertendo cada linha de texto em uma linha da tabela e utilizando a coluna PAGINA para indicar a página de origem. O recurso não interpreta automaticamente o layout do documento, sendo recomendado utilizar o modo Tabela única em conjunto com o nó Montar Tabela para estruturar vários arquivos com o mesmo padrão. PDFs escaneados como imagem, sem texto extraível, são identificados e reportados como erro.

1. Abra a configuração do nó Importar PDF.

2. Em Arquivo PDF (.pdf), clique em Selecionar arquivo(s).

3. Na janela Abrir, selecione o arquivo (ou os arquivos) e clique em Abrir. Mais detalhes em Selecionar arquivos e pastas.

Como alternativa, arraste os arquivos para a área indicada.

1. Para importar os arquivos de uma pasta, clique em Selecionar pasta. Navegue até a pasta desejada, confira o campo Pasta e clique em Selecionar pasta para confirmar.

Janela Selecionar pasta do Windows, com campo Pasta e botões Selecionar pasta e Cancelar.

1. Em Modo de saída, selecione Uma tabela por arquivo para gerar uma tabela por PDF, com a coluna PAGINA e a coluna de texto.

2. Em Nome da coluna, informe o nome que receberá cada linha extraída. Se o campo ficar vazio, o nome utilizado será linha.

3. Para reunir os arquivos em uma única tabela, selecione Tabela única. Esse modo não exige o preenchimento de campos adicionais.

4. Clique em Executar e verifique o Status da última execução.

Tela de configuração do nó Importar PDF.

Observação: PDFs escaneados (imagem) não têm texto extraível e serão reportados como erro.

Importar JSON

Importa arquivos JSON e interpreta sua estrutura, convertendo as informações em uma tabela que pode ser utilizada nas demais etapas do fluxo.

1. Abra a configuração do nó Importar JSON.

2. Em Arquivos JSON, clique em Selecionar arquivo(s).

3. Na janela Abrir, selecione o arquivo (ou os arquivos) e clique em Abrir. Mais detalhes em Selecionar arquivos e pastas.

Também é possível arrastá-los para a área indicada.

1. Para importar os arquivos de uma pasta, clique em Selecionar pasta. Navegue até a pasta desejada, confira o campo Pasta e clique em Selecionar pasta para confirmar.

Janela Selecionar pasta do Windows, com campo Pasta e botões Selecionar pasta e Cancelar.

1. Confira os arquivos selecionados.

2. Clique em Executar e verifique o Status da última execução.

Tela de configuração do nó Importar JSON.

Importar OFX

Importa arquivos OFX (Open Financial Exchange), formato utilizado principalmente para extratos bancários, e converte suas informações em uma tabela estruturada de transações.

1. Abra a configuração do nó Importar OFX.

2. Em Arquivos OFX, clique em Selecionar arquivo(s).

3. Na janela Abrir, selecione o arquivo (ou os arquivos) e clique em Abrir. Mais detalhes em Selecionar arquivos e pastas.

Também é possível arrastá-los para a área indicada.

1. Para importar os arquivos de uma pasta, clique em Selecionar pasta. Navegue até a pasta desejada, confira o campo Pasta e clique em Selecionar pasta para confirmar.

Janela Selecionar pasta do Windows, com campo Pasta e botões Selecionar pasta e Cancelar.

1. Confira os arquivos selecionados.

2. Clique em Executar e verifique o Status da última execução.

Tela de configuração do nó Importar OFX.

Importar Planilha

Importa planilhas Excel nos formatos .xlsx e .xls, convertendo seus dados em uma tabela para utilização no fluxo. Para arquivos em que os dados estejam transpostos, com os cabeçalhos na primeira coluna e as informações distribuídas nas colunas seguintes, é possível utilizar a orientação "Por Linha".

1. Abra o nó Importar Planilha.

2. Em Arquivos Excel, clique em Selecionar arquivo(s).

3. Na janela Abrir, selecione o arquivo (ou os arquivos) e clique em Abrir. Mais detalhes em Selecionar arquivos e pastas.

Como alternativa, arraste os arquivos para a área indicada.

1. Para importar os arquivos de uma pasta, clique em Selecionar pasta. Navegue até a pasta desejada, confira o campo Pasta e clique em Selecionar pasta para confirmar.

Janela Selecionar pasta do Windows, com campo Pasta e botões Selecionar pasta e Cancelar.

1. Em Orientação dos dados, selecione Por Coluna ou Por Linha. Utilize Por Linha para dados transpostos, com cabeçalhos na primeira coluna.

2. Em Range de linhas, mantenha Todas as linhas para importar todas. Para limitar a importação, desmarque a opção e digite o intervalo desejado no campo que aparece.

3. Em Range de colunas, mantenha Todas as colunas para importar todas. Para limitar a importação, desmarque a opção e digite o intervalo desejado no campo que aparece.

4. Clique em Executar e verifique o Status da última execução.

Tela de configuração do nó Importar Planilha.

Importar API

Importa dados de APIs REST externas por meio de requisições HTTP, como GET e POST, com suporte a parâmetros estáticos ou dinâmicos e diferentes formas de autenticação. Também permite utilizar o modo Híbrido, no qual a API é chamada uma vez para cada linha de uma tabela de entrada, possibilitando mapear os valores das colunas diretamente para os parâmetros enviados na requisição.

1. Abra Importar API e informe URL da API. Para uma URL dinâmica, use {chave} no local do valor que será substituído.

2. Selecione Método HTTP: GET ou POST. Em Tipo de Parâmetro, escolha Query String (PARAMS), Corpo JSON, Form URL-Encoded (BODY) ou RAW (corpo cru), conforme a API. Em Tipo de Resposta, escolha JSON (Importar para tabela) ou Arquivo (download).

3. Em Parâmetros Dinâmicos, clique em Adicionar parâmetro dinâmico e preencha Nome do parâmetro e Tipo (período).

4. Em Autenticação, selecione Tipo de Autenticação conforme a API: Bearer Token, API Key (Header), API Key (Query) ou Basic (Usuário e Senha). Preencha as credenciais exigidas.

Tela de configuração do nó Importar API (parte 1 de 2).

1. Em Certificado digital, selecione Modo do certificado: Não usar, Instalado no Windows ou Arquivo .pfx. Se utilizar um certificado instalado, selecione esse modo; se utilizar Arquivo .pfx, carregue o arquivo e informe a senha. Essa configuração é independente da autenticação por token ou API Key.

2. Em Headers Customizados, clique em Adicionar header e preencha Nome do Header e Valor.

3. Para utilizar os dados da tabela de entrada como parâmetros da API, expanda Modo Híbrido e marque Usar dados de tabela como parâmetros.

4. Clique em Executar e verifique o Status da última execução.

Tela de configuração do nó Importar API (parte 2 de 2).

Importar Banco de Dados

Conecta o fluxo a bancos de dados externos, como SQL Server, Oracle, MySQL e PostgreSQL, permitindo importar informações por meio de consultas SQL ou pela seleção direta de tabelas. No modo Query SQL, é possível trazer apenas os dados desejados utilizando filtros e condições, como WHERE. Já no modo Selecionar Tabelas, é possível importar tabelas inteiras diretamente para o fluxo.

1. Abra o nó Importar Banco de Dados e selecione Tipo de Banco, conforme o banco de origem.

2. Em Modo de Conexão, escolha Campos separados ou Connection String.

3. No modo Campos separados, preencha Servidor, Banco de Dados, Usuário e Senha. Informe Porta quando necessário; deixe vazia para utilizar a porta padrão do banco selecionado.

Recomendação: utilize uma conta de banco de dados com permissão somente de leitura, restrita às tabelas que o fluxo precisa consultar.

1. Para conectar por Connection String, selecione esse modo e cole a string de conexão do banco no campo que aparece, em vez de preencher os dados em campos separados.

Tela de configuração do nó Importar Banco de Dados (parte 1 de 2).

1. Em Modo de Importação, escolha Query SQL ou Selecionar Tabelas.

2. No modo Query SQL, escreva a consulta no campo Query SQL, utilizando as tabelas e condições correspondentes ao banco de origem.

3. No modo Selecionar Tabelas, informe a tabela que deseja importar no campo que aparece.

4. Clique em Executar e verifique o Status da última execução.

Tela de configuração do nó Importar Banco de Dados (parte 2 de 2).

Transformação e tratamento de dados

No Taxcel Studio, você pode editar e transformar seus dados de forma prática por meio de módulos especializados.

É possível utilizar Inteligência Artificial para gerar consultas, inserir colunas, filtrar informações, juntar ou concatenar tabelas (inclusive com mapeamento de colunas), remover duplicadas ou linhas em branco, pivotear e organizar colunas, escrever consultas em Query SQL ou Query Avançada, montar tabelas a partir de textos, dividir colunas com o Delimitador, substituir valores, agrupar com Group By, converter tipos de dados, categorizar valores, assinar XMLs e compactar ou converter arquivos em Base64, tornando o tratamento e a análise fiscal mais ágil e eficiente.

Transformar com AI

Após a importação dos arquivos, você pode conectá-los ao módulo de Inteligência Artificial. Nesse módulo, basta descrever em linguagem natural o que deseja, e a IA gera uma consulta (query) que é aplicada às tabelas selecionadas, disponibilizando o resultado na saída do nó. Os arquivos de origem não são alterados.

Para saber quais informações são enviadas ao modelo de IA, consulte a página Inteligência Artificial desta documentação.

1. Conecte e execute o nó anterior para disponibilizar as tabelas de entrada.

2. Abra Transformar com AI e selecione as tabelas que serão utilizadas.

3. Em Seu prompt, escreva a instrução para a transformação. Utilize @ para mencionar tabelas.

4. Escreva uma instrução curta e objetiva. Evite reunir várias etapas no mesmo prompt ou mencionar dados que não estão nas tabelas selecionadas.

Tela de configuração do nó Transformar com AI (parte 1 de 2).

1. Clique em Salvar prompt para registrar a instrução. A execução da query atua sobre as tabelas que antecedem este nó e disponibiliza os dados resultantes na saída.

2. Confira Query gerada pela IA e Créditos de IA restantes. Cada licença tem direito a 1.000 interações mensais com a IA; cada solicitação enviada consome uma interação. Ao atingir o limite, a IA poderá ser suspensa até a renovação ou contratação adicional. Dica: use prompts curtos e objetivos, com uma tarefa por vez, referenciando apenas dados das tabelas selecionadas.

3. Clique em Executar e verifique o Status da última execução.

Tela de configuração do nó Transformar com AI (parte 2 de 2).

Inserir Coluna

Neste módulo, você pode adicionar novas colunas ao arquivo para complementar, organizar e detalhar as informações conforme a necessidade da sua análise ou apuração. As colunas inseridas permitem enriquecer os dados existentes e adequar o arquivo às exigências do processo fiscal.

1. Conecte e execute o nó anterior para disponibilizar os dados. Abra Inserir Coluna e selecione a Tabela de entrada.

2. Informe Nome da nova coluna e selecione o Tipo de dado desejado.

3. Em Modo de cálculo, escolha Expressão ou Operação.

4. Para Expressão, preencha Expressão e, quando necessário, Valor base (opcional). Em uma expressão como (QTD * PRECO) - DESCONTO, utilize os nomes das colunas da sua tabela.

Tela de configuração do nó Inserir Coluna, modo Expressão.

1. Para Operação, escolha +, -, *, /, %, Diferença de dias entre datas ou Somar dias a uma data.

2. Clique em Adicionar coluna. A coluna será incluída em Colunas adicionadas, e o formulário será limpo para permitir outra configuração.

3. Repita o preenchimento para as demais colunas necessárias e confira Colunas adicionadas.

4. Clique em Executar e verifique o Status da última execução.

Tela de configuração do nó Inserir Coluna, modo Operação.

Inserir Coluna

Neste módulo, você pode adicionar novas colunas ao arquivo para complementar, organizar e detalhar as informações conforme a necessidade da sua análise ou apuração. As colunas inseridas permitem enriquecer os dados existentes e adequar o arquivo às exigências do processo fiscal.

1. Conecte e execute o nó anterior para disponibilizar os dados. Abra Inserir Coluna e selecione a Tabela de entrada.

2. Informe Nome da nova coluna e selecione o Tipo de dado desejado.

3. Em Modo de cálculo, escolha Expressão ou Operação.

4. Para Expressão, preencha Expressão e, quando necessário, Valor base (opcional). Em uma expressão como (QTD * PRECO) - DESCONTO, utilize os nomes das colunas da sua tabela.

Tela de configuração do nó Inserir Coluna, modo Expressão.

1. Para Operação, escolha +, -, *, /, %, Diferença de dias entre datas ou Somar dias a uma data.

2. Clique em Adicionar coluna. A coluna será incluída em Colunas adicionadas, e o formulário será limpo para permitir outra configuração.

3. Repita o preenchimento para as demais colunas necessárias e confira Colunas adicionadas.

4. Clique em Executar e verifique o Status da última execução.

Tela de configuração do nó Inserir Coluna, modo Operação.

Filtrar Dados

Neste módulo, você pode aplicar filtros para localizar, organizar e analisar dados e informações específicas do arquivo, facilitando a visualização e o tratamento apenas do que é relevante para o seu processo.

1. Conecte e execute o nó anterior para disponibilizar tabelas e colunas.

2. Abra Filtrar Dados e selecione Planilha / DataSource. Em Colunas a manter, defina os campos desejados.

3. Em Operador lógico entre filtros, escolha AND (&&) ou OR (||). Utilize AND quando todas as condições precisarem ser verdadeiras.

4. Em Adicionar filtro, selecione COLUNA e OPERADOR e preencha VALOR conforme a condição desejada.

5. Clique em Adicionar filtro e confira a lista Filtros adicionados. Repita o procedimento quando forem necessárias outras condições.

6. Confira o conjunto de filtros e a configuração do operador lógico.

7. Clique em Executar e verifique o Status da última execução.

Tela de configuração do nó Filtrar Dados.

Juntar Tabelas

Este módulo permite juntar dados de duas tabelas distintas, facilitando a integração de informações e a criação de uma base de dados mais completa.

1. Conecte e execute os nós que fornecerão os dados da entrada esquerda e da entrada direita.

2. Abra Juntar tabelas e defina Tabela 1 (Esquerda) e Tabela 2 (Direita).

3. Em Tipo de Junção (JOIN), selecione INNER, LEFT, RIGHT ou FULL.

4. Em Colunas de Junção, escolha a coluna da Esquerda, o operador de comparação e a coluna da Direita.

5. Use Adicionar chave quando forem necessárias outras condições de relacionamento.

6. Defina os campos de Colunas da Tabela 1 (Esquerda) no resultado e Colunas da Tabela 2 (Direita) no resultado, após as tabelas estarem disponíveis.

7. Confira as chaves e as colunas de saída.

8. Clique em Executar e verifique o Status da última execução.

Tela de configuração do nó Juntar Tabelas.

Remover Duplicadas

Neste módulo, você pode identificar e remover informações duplicadas do arquivo, garantindo maior consistência e confiabilidade dos dados.

1. Abra Remover Duplicadas e selecione Tabela de entrada.

2. Em Colunas-chave (usadas para identificar duplicatas), escolha uma coluna e clique em Selecionar.

3. Repita a seleção para compor o conjunto de colunas-chave. Para incluir todas, utilize Selecionar todos; para desfazer a seleção, use Limpar.

4. Confira as colunas selecionadas.

5. Clique em Executar e verifique o Status da última execução.

Tela de configuração do nó Remover Duplicadas.

Concatenar Tabelas

Este módulo permite concatenar tabelas para unir informações que estão separadas, consolidando os dados em uma única estrutura de forma simples e organizada.

1. Abra Concatenar Tabelas e selecione Tabela 1 (entrada esquerda) e Tabela 2 (entrada direita).

2. Em Adicionar mapeamento de colunas, escolha COLUNA TABELA 1 e COLUNA TABELA 2.

3. Preencha NOME NO RESULTADO com o nome da coluna resultante.

4. Clique em Adicionar mapeamento. Repita o procedimento para os demais pares de colunas necessários.

5. Confira a relação Mapeamentos adicionados.

6. Clique em Executar e verifique o Status da última execução.

Tela de configuração do nó Concatenar Tabelas.

Concatenar Tabelas (mapeado)

O módulo Concatenar Tabelas (mapeado) permite definir as colunas da tabela final e mapear as tabelas que serão concatenadas para essa estrutura. A ordem das colunas de destino determina sua ordem no resultado. Também é possível incluir uma coluna para identificar a tabela de origem.

1. Abra Concatenar Tabelas (mapeado).

2. Em Colunas de destino, digite o nome de uma coluna no campo Nome da coluna (ex.: CNPJ) e clique em Adicionar.

3. Crie as colunas na ordem desejada para o resultado. Adicione pelo menos uma coluna de destino antes de mapear as tabelas.

4. Em Tabelas a concatenar, selecione a tabela desejada para acessar seus campos e configure os mapeamentos de origem e destino.

5. Em Coluna de origem, marque Incluir coluna identificando a tabela de origem quando esse identificador for necessário.

6. Clique em Executar e verifique o Status da última execução.

Tela de configuração do nó Concatenar Tabelas (mapeado).

Observação: uma tabela inexistente no momento da execução é ignorada. Colunas de destino sem mapeamento em uma tabela ficam vazias (nulas) nas linhas daquela tabela.

Remover Linhas em Branco

Este módulo remove linhas em branco do arquivo, ajudando a organizar os dados e evitar erros no processamento das informações.

1. Abra Remover linhas em branco e selecione Tabela de entrada.

2. Em Colunas que não podem estar em branco, escolha uma coluna e clique em Adicionar.

3. Repita o procedimento para incluir as demais colunas que serão verificadas.

4. Confira a relação das colunas selecionadas na lista Coluna e Ação.

5. Clique em Executar e verifique o Status da última execução.

Tela de configuração do nó Remover Linhas em Branco.

Pivotear Tabela

Este módulo permite reorganizar os dados da tabela por meio do pivotamento, transformando e agrupando informações para facilitar a análise, a visualização e a consolidação dos dados.

1. Abra Pivotear Tabela e selecione Tabela Alvo.

2. Em Colunas Identificadoras, escolha uma coluna e clique em Selecionar. Repita para as demais; utilize Selecionar todos ou Limpar quando necessário.

3. Em Coluna Pivot, selecione a coluna que será utilizada no pivotamento.

4. Em Coluna de Valores, selecione a coluna com os valores a processar.

5. Em Função de Agregação, selecione SUM, AVG, MIN, MAX, COUNT ou ANY_VALUE.

6. Clique em Executar e verifique o Status da última execução.

Tela de configuração do nó Pivotear Tabela.

Organizador de Colunas

Permite selecionar e reorganizar as colunas de uma tabela, possibilitando remover campos desnecessários e definir a ordem em que as informações serão apresentadas nas próximas etapas do fluxo.

1. Abra Organizador de Colunas e selecione Tabela de entrada.

2. Em Colunas para organizar, escolha uma coluna no seletor Adicionar coluna... e clique em Adicionar.

3. Repita a seleção para as colunas que deseja manter, ou utilize Selecionar todas.

4. Arraste as colunas da lista para colocá-las na ordem desejada.

5. Para reiniciar a escolha, use Limpar e refaça a seleção.

6. Clique em Executar e verifique o Status da última execução.

Tela de configuração do nó Organizador de Colunas.

Query SQL

Permite criar consultas SQL personalizadas sobre as tabelas disponíveis no fluxo, oferecendo maior flexibilidade para usuários que precisam realizar filtros, cálculos, cruzamentos ou transformações mais complexas nos dados.

1. Abra Query SQL.

2. Em Tabelas no FROM, selecione uma tabela e clique em Adicionar. Adicione pelo menos uma tabela para habilitar o editor.

3. Na área Query SQL, configure a parte SELECT e confira as tabelas em FROM.

4. Complete a consulta com as cláusulas necessárias, como WHERE, GROUP BY, HAVING, ORDER BY, LIMIT ou INNER JOIN.

5. Revise a consulta e os nomes das tabelas e colunas.

6. Clique em Executar e verifique o Status da última execução.

Tela de configuração do nó Query SQL.

Query Avançada

Permite escrever consultas SQL personalizadas do zero, oferecendo maior liberdade e controle sobre a lógica utilizada no fluxo. Diferentemente da Query SQL, que disponibiliza funções e estruturas predefinidas para auxiliar na montagem da consulta, a Query Avançada permite criar toda a query manualmente, sendo indicada para usuários que desejam desenvolver comandos SQL mais específicos ou complexos.

1. Abra Query Avançada e consulte a relação Tabelas disponíveis.

2. Escreva a consulta no campo Query SQL, utilizando os nomes das tabelas e colunas do fluxo.

3. Preencha Nome da tabela de saída com o identificador desejado.

4. Confira a consistência entre a consulta e o nome da tabela de saída. Utilize uma consulta completa e adequada ao resultado desejado.

5. Clique em Executar e verifique o Status da última execução.

Tela de configuração do nó Query Avançada.

Montar Tabela

Estrutura linhas de texto, geralmente provenientes do nó Importar PDF, em formato de tabela, transformando cada campo definido por um rótulo âncora e uma regra de captura em uma coluna. O template configurado fica salvo no nó e pode ser reutilizado em vários documentos com a mesma estrutura, permitindo processar diversos PDFs de uma só vez. No modo de ocorrências, o primeiro campo definido é utilizado como referência para identificar o início de cada novo registro.

1. Abra Montar Tabela e selecione Tabela de entrada.

2. Em Coluna de texto, informe a coluna que contém as linhas a estruturar.

3. Em Coluna de documento, informe a coluna que identifica cada documento, como ARQUIVO no modo Tabela única do Importar PDF. Deixe vazio para tratar toda a tabela como um documento.

4. Em Modo de registro, escolha Um registro por documento ou Registros repetidos (ocorrências).

Tela de configuração do nó Montar Tabela (parte 1 de 2).

1. Em Campos de extração, preencha Nome da coluna e Texto âncora. A busca da âncora é por conteúdo e não diferencia maiúsculas de minúsculas.

2. Em Captura, escolha Mesma linha (após o rótulo), Linha seguinte, N linhas abaixo, Expressão regular ou Linha inteira.

3. Clique em Adicionar campo para incluir os demais campos. No modo de ocorrências, organize o primeiro campo como a referência para o início de cada novo registro.

4. Clique em Executar e verifique o Status da última execução.

Tela de configuração do nó Montar Tabela (parte 2 de 2).

Observação: a tabela final usa o padrão {NomeDoNo}_result, inclui DOCUMENTO e uma coluna por campo definido. Campo não encontrado fica nulo; o template é salvo no nó.

Delimitador

Divide o conteúdo de uma coluna de texto em diferentes partes, permitindo distribuí-las em novas colunas ou extrair apenas uma determinada parte do conteúdo por meio de uma substring.

1. Abra Delimitador e selecione Tabela de entrada.

2. Em Tipo de Operação, selecione Split para separar o texto ou Substring para extrair um trecho.

3. Em Coluna para separar, escolha a coluna que contém o texto a processar.

4. Para Split, preencha Delimitador com o caractere que separa o conteúdo.

5. Para Substring, informe um número em Índice Inicial e configure Comprimento. O Índice Inicial começa em 0, que corresponde ao primeiro caractere.

6. Clique em Executar e verifique o Status da última execução.

Tela de configuração do nó Delimitador.

Substituir Valores

Permite localizar e substituir valores existentes em uma ou mais colunas da tabela, possibilitando realizar substituições exatas ou parciais quando determinado texto estiver contido no valor original.

1. Abra Substituir Valores e selecione Tabela de entrada.

2. Em Substituições, selecione Coluna.

3. Preencha Valor Antigo com o conteúdo a localizar e Valor Novo com o conteúdo de substituição.

4. Em Modo, selecione Substituir trecho no texto, Se contém, Se for exatamente igual, Se estiver vazio, Se estiver nulo ou Se estiver nulo ou vazio.

5. Clique em Adicionar Substituição para incluir outras regras, preenchendo os mesmos campos em cada uma.

6. Confira as substituições.

7. Clique em Executar e verifique o Status da última execução.

Tela de configuração do nó Substituir Valores.

Group By

Agrupa os registros de uma tabela com base em uma ou mais colunas e permite aplicar funções de agregação sobre os dados, funcionando de maneira semelhante à cláusula Group By do SQL.

1. Abra Group By e selecione Tabela Alvo.

2. Em Colunas para Agrupar, escolha uma coluna e clique em Selecionar. Repita para as demais; utilize Selecionar todos ou Limpar quando necessário.

3. Em Colunas de Agregação, selecione a coluna e uma função: SUM, AVG, MIN, MAX, COUNT ou ANY_VALUE. Clique em Adicionar.

4. Repita a inclusão para as demais agregações necessárias.

5. Para aplicar uma condição antes da agregação, preencha o campo opcional Filtro.

6. Clique em Executar e verifique o Status da última execução.

Tela de configuração do nó Group By.

Conversão de Tipo

Converte o tipo de dado de uma ou mais colunas, permitindo, por exemplo, transformar textos em números ou datas, números em textos e realizar outras conversões necessárias para o tratamento das informações.

1. Abra Conversão de Tipo e selecione Tabela Alvo.

2. Em Conversões, escolha Coluna e Tipo Destino.

3. Clique em Adicionar Conversão para configurar outras colunas.

4. Confira todas as conversões.

5. Clique em Executar e verifique o Status da última execução.

Tela de configuração do nó Conversão de Tipo.

Categorizador

Cria colunas de categorização a partir dos valores de uma coluna de origem, permitindo associar cada valor a um rótulo de categoria por meio de valores fixos ou faixas numéricas. A nova coluna segue o padrão CATEGORIA_{NomeColuna}. Para classificações numéricas por intervalo, é possível utilizar o modo Range, como em 0-100 → Baixo e 101-500 → Médio.

1. Abra Categorizador e selecione Tabela de entrada.

2. Em Categorizações, escolha Coluna para categorizar.

3. Preencha Nome da coluna criada (opcional) se desejar um nome específico. Deixe vazio para utilizar CATEGORIA_<coluna de origem>.

4. Em Modo, escolha Valores fixos, Faixas (ranges) ou Texto (contém, começa com...).

5. Para Valores fixos, preencha os campos Valor e Categoria em Mapeamento valor → categoria. Utilize Adicionar valor para incluir outros pares.

6. Para Faixas (ranges) ou Texto (contém, começa com...), selecione o modo desejado.

7. Em Valor padrão (quando não se encaixa em nenhuma regra), informe a categoria a utilizar quando as regras não corresponderem ao conteúdo.

8. Clique em Adicionar categorização para configurar outra coluna de origem.

9. Clique em Executar e verifique o Status da última execução.

Tela de configuração do nó Categorizador.

Observação: o padrão de nome da coluna se aplica quando o campo opcional de nome permanece vazio.

Assinar XML

O módulo Assinar XML permite assinar digitalmente os XMLs importados no fluxo, a partir de uma coluna que contém um documento XML por linha.

1. Abra Assinar XML e selecione Tabela de entrada.

2. Em Coluna com o XML, selecione a coluna com o documento a assinar, um por linha.

3. Em Elemento a assinar, informe o elemento que contém o atributo de identificação, como infNFe, infDPS ou infEvento, conforme o documento.

4. Preencha Atributo de identificação e selecione Algoritmo de acordo com a especificação do documento.

Tela de configuração do nó Assinar XML (parte 1 de 2).

1. Em Modo do certificado, escolha Instalado no Windows (recomendado) ou Arquivo .pfx.

2. Para Instalado no Windows, informe Thumbprint do certificado. Obtenha a impressão digital em certmgr.msc → Pessoal → Certificados → certificado → Detalhes → Impressão digital. Nesse modo, a senha não é solicitada nem armazenada.

3. Para Arquivo .pfx, selecione o arquivo do certificado digital no campo correspondente e informe a senha no campo de senha.

4. Na janela Abrir, selecione o arquivo (ou os arquivos) e clique em Abrir. Mais detalhes em Selecionar arquivos e pastas.

5. Em Nome da coluna de saída, informe o nome desejado. Deixe vazio para utilizar XML_ASSINADO.

6. Defina Continuar quando uma linha falhar. Marque para ignorar as linhas com erro e registrá-las no log; desmarque para interromper o nó na primeira falha.

7. Clique em Executar e verifique o Status da última execução.

Tela de configuração do nó Assinar XML (parte 2 de 2).

Observação: o nó recusa XMLs que já possuam assinatura.

Compactar e Base64

O módulo Compactar e Base64 compacta o conteúdo de uma coluna e devolve o pacote codificado em Base64. A janela permite escolher o formato ZIP ou GZIP e definir se será gerado um pacote com todos os dados ou um pacote por linha.

1. Abra Compactar e Base64 e selecione Tabela de entrada.

2. Em Coluna com o conteúdo, escolha a coluna que será compactada, como a coluna produzida por Assinar XML.

3. Em Coluna para nome do arquivo, selecione a coluna com os nomes dos arquivos dentro do pacote. Deixe sem seleção para atribuir nomes sequenciais.

4. Preencha Extensão dos arquivos de acordo com o conteúdo a compactar.

5. Em Formato, selecione ZIP para reunir vários arquivos em um pacote ou GZIP para compactar um fluxo de conteúdo.

Tela de configuração do nó Compactar e Base64 (parte 1 de 2).

1. Em Agrupamento, escolha Um pacote com tudo para obter uma linha com o Base64 do pacote, ou Um pacote por linha para gerar um pacote por registro e manter as colunas originais na saída.

2. Preencha Nome da coluna de saída ou deixe vazio para utilizar PACOTE_BASE64.

3. Se desejar manter os pacotes em disco, configure a opção Salvar pacotes em disco utilizando o botão ....

4. Clique em Executar e verifique o Status da última execução.

Tela de configuração do nó Compactar e Base64 (parte 2 de 2).

Nós de exportação

No Taxcel Studio, você pode exportar os dados do fluxo para arquivos TXT, planilhas Excel com formatação, XML e JSON, gerar gráficos e tabelas dinâmicas, e enviar as informações para APIs externas, bancos de dados ou por e-mail.

Exportar TXT

Este módulo permite exportar a tabela gerada no fluxo para um arquivo no formato TXT. Basta selecionar a tabela de entrada, definir o caminho onde o arquivo será salvo e escolher o divisor que separará os valores de cada coluna. Após a execução, o arquivo TXT será gerado conforme as configurações definidas.

1. Abra Exportar TXT e selecione Tabela de entrada.

2. Em Modo de saída, escolha Consolidado (um arquivo) ou Um arquivo por linha.

3. No modo consolidado, em Caminho de destino, clique em Escolher caminho para salvar TXT.... Na janela de salvamento, escolha a pasta de destino, preencha Nome e clique em Salvar.

Janela Salvar como do Windows, com campos Nome e Tipo e botões Salvar e Cancelar.

1. Em Divisor, selecione vírgula (,), ponto e vírgula (;), \t (tab) ou barra vertical (|).

2. Para gerar um arquivo por registro, selecione Um arquivo por linha e configure o destino e a identificação dos arquivos.

3. Clique em Executar e verifique o Status da última execução.

Tela de configuração do nó Exportar TXT.

Exportar Planilha

Este módulo permite exportar dados de uma tabela para um arquivo de planilha (como XLSX). Você deve selecionar a tabela de entrada e as colunas que deseja exportar. É possível aplicar as seguintes opções:

• Negrito no cabeçalho

• AutoFit (ajuste automático da largura das colunas)

• Cor intercalada (facilita a leitura)

• Renomear colunas (opcional, para melhor organização e apresentação dos dados)

1. Abra Exportar Planilha.

2. Em Modo de saída, selecione Arquivo único (várias abas) ou Um arquivo por tabela.

3. Abra Abas / Tabelas e selecione os dados a exportar. Por padrão, todas as abas são exportadas com todas as colunas.

4. Expanda uma aba para personalizar seu nome, selecionar as colunas e definir as renomeações desejadas.

5. Em Opções de formatação, marque as opções desejadas: Negrito no cabeçalho, AutoFit (ajustar largura) e Cor intercalada.

6. Em Caminho de destino, clique em Escolher caminho para salvar planilha.... Na janela de salvamento, escolha a pasta de destino, preencha Nome e clique em Salvar.

Janela Salvar como do Windows, com campos Nome e Tipo e botões Salvar e Cancelar.

1. Clique em Executar e verifique o Status da última execução.

Tela de configuração do nó Exportar Planilha.

Exportar XML

Exporta as tabelas para XML, no modo simples (uma tabela plana) ou hierárquico (várias tabelas em documentos estruturados como NF-e). No modo hierárquico, o primeiro elemento do caminho deve ser igual em todas as tabelas - é a raiz de cada documento.

1. Abra Exportar XML e escolha Modo de estrutura: Simples (uma tabela, XML plano) ou Hierárquico (várias tabelas aninhadas).

2. No modo Simples, selecione Tabela de entrada e preencha Elemento de cada linha. Será gerado um elemento por linha da tabela.

3. No modo Simples, em Colunas como, escolha Elementos ou Atributos. Selecione as Colunas e clique em Selecionar; utilize Selecionar todos ou Limpar quando necessário. Deixe sem seleção para exportar todas.

4. Se desejar alterar o nome de uma coluna, abra Renomear colunas, selecione a coluna desejada e digite o novo nome no campo ao lado.

Tela de configuração do nó Exportar XML, modo Simples (parte 1 de 2).

1. No modo Hierárquico, configure Capa se precisar de um elemento externo ao documento. Preencha Elemento da capa e, opcionalmente, os pares de Atributos da capa, clicando em Adicionar. Sem capa, o documento começa pela tabela raiz.

2. Em Tabelas, adicione as tabelas que comporão o XML. Utilize Selecionar todas ou Remover todas para ajustar a seleção. Organize as tabelas na ordem desejada para os elementos irmãos no XML.

3. Configure os caminhos e os relacionamentos entre as tabelas utilizando as colunas de id e de id do pai, como row_id e parent_id das tabelas importadas.

4. No modo Hierárquico, utilize o mesmo primeiro elemento do caminho em todas as tabelas. Esse elemento é a raiz de cada documento; Elemento da capa define o envoltório externo, e Elemento raiz envolve vários documentos em arquivo único.

Tela de configuração do nó Exportar XML, modo Hierárquico (parte 1 de 2).

1. No modo Hierárquico, defina Prefixo do nome dos arquivos para os casos em que não houver uma coluna com o nome do arquivo. Por fim, informe o Caminho de destino e clique em Executar para gerar o XML.

Tela de configuração do nó Exportar XML, modo Hierárquico (parte 2 de 2).

1. Configure Elemento raiz para envolver todas as linhas no modo Simples ou todos os documentos no modo Hierárquico com arquivo único.

2. Em Opções, defina Omitir campos vazios e XML identado. Marque Omitir campos vazios para excluir do XML as colunas sem valor.

3. Em Modo de saída, escolha Arquivo único ou Um arquivo por registro e configure o destino correspondente.

4. Para arquivo único, em Arquivo de saída, clique em Escolher caminho para salvar XML.... Na janela de salvamento, escolha a pasta de destino, preencha Nome e clique em Salvar.

Janela Salvar como do Windows, com campos Nome e Tipo e botões Salvar e Cancelar.

1. Clique em Executar e verifique o Status da última execução.

Tela de configuração do nó Exportar XML, modo Simples (parte 2 de 2).

Observação: nomes de colunas são ajustados para nomes válidos de XML. As colunas de id e de id do pai não aparecem no XML.

Exportar JSON

Exporta a tabela para um arquivo JSON, em arquivo único ou um arquivo por linha.

1. Abra Exportar JSON e selecione Tabela de entrada.

2. Em Colunas, escolha uma coluna e clique em Selecionar. Repita para as demais ou use Selecionar todos. Organize as colunas na ordem desejada para a exportação; deixe sem seleção para exportar todas.

3. Se desejar renomear colunas, expanda Renomear colunas (opcional), selecione o campo desejado e digite o novo nome no campo ao lado.

4. Em Estrutura do JSON, escolha Array de objetos ou Objeto com campo de dados. Na segunda opção, preencha o nome do campo de dados no campo que aparece.

5. Em Tipos das colunas, selecione Respeitar tipos para manter números sem aspas, booleanos e nulos nativos, ou Tudo como texto.

Tela de configuração do nó Exportar JSON (parte 1 de 2).

1. Em JSON indentado, marque Gerar JSON indentado se desejar um arquivo mais legível. Essa opção aumenta o tamanho do arquivo.

2. Em Modo de saída, escolha Arquivo único ou Um arquivo por linha.

3. Para arquivo único, em Arquivo de saída, clique em Escolher caminho para salvar JSON.... Na janela de salvamento, escolha a pasta de destino, preencha Nome e clique em Salvar. Para Um arquivo por linha, configure os campos correspondentes.

Janela Salvar como do Windows, com campos Nome e Tipo e botões Salvar e Cancelar.

1. Clique em Executar e verifique o Status da última execução.

Tela de configuração do nó Exportar JSON (parte 2 de 2).

Exportar Gráfico

O módulo Exportar Gráfico recebe uma tabela de um nó anterior, permite escolher quais colunas serão usadas como base, valores, eixos e filtros, e então gera um gráfico no formato desejado (barras, linhas, pizza ou donut) a partir desses dados. Ele apenas transforma e exporta o gráfico, não cria dados por conta própria.

1. Abra Exportar Gráfico e selecione Nome da Tabela.

2. Em Colunas (base), escolha uma coluna e clique em Adicionar. Repita para as colunas necessárias.

3. Em Valores e Eixos, selecione cada campo entre as colunas adicionadas em Colunas (base) e clique em Adicionar na área correspondente. Organize os campos conforme a estrutura desejada.

4. Se precisar de filtros, selecione os campos em Filtros (opcional) e clique em Adicionar, como nas áreas Valores e Eixos.

5. Em Gerar gráfico?, mantenha Sim, gerar gráfico marcado para gerar o gráfico.

6. Em Tipo de gráfico, escolha Barras, Linhas, Pizza ou Donut.

7. Em Caminho de destino, clique em Escolher caminho para salvar.... Na janela de salvamento, escolha a pasta de destino, preencha Nome e clique em Salvar.

Janela Salvar como do Windows, com campos Nome e Tipo e botões Salvar e Cancelar.

1. Clique em Executar e verifique o Status da última execução.

Tela de configuração do nó Exportar Gráfico.

Exportar Tabela Dinâmica

O módulo Exportar Tabela Dinâmica recebe uma tabela de um nó anterior e permite organizar os dados de forma resumida e estruturada. Você pode escolher quais colunas serão utilizadas como valores, eixos e filtros, gerando uma tabela dinâmica a partir das informações existentes. O módulo apenas transforma e exporta os dados conforme a configuração definida, sem criar novas informações.

1. Abra Exportar Tabela Dinâmica e selecione Nome da Tabela.

2. Em Colunas (base), escolha uma coluna e clique em Adicionar. Repita para as demais colunas necessárias.

3. Em Valores e Eixos, selecione cada campo entre as colunas adicionadas em Colunas (base) e clique em Adicionar na área correspondente. Organize os campos conforme a estrutura desejada.

4. Se precisar de filtros, selecione os campos em Filtros (opcional) e clique em Adicionar, como nas áreas Valores e Eixos.

5. Em Caminho de destino, clique em Escolher caminho para salvar.... Na janela de salvamento, escolha a pasta de destino, preencha Nome e clique em Salvar.

Janela Salvar como do Windows, com campos Nome e Tipo e botões Salvar e Cancelar.

1. Clique em Executar e verifique o Status da última execução.

Tela de configuração do nó Exportar Tabela Dinâmica.

Exportar API

O módulo Exportar API permite enviar os dados de uma tabela do fluxo para uma API externa por meio de requisições POST, PUT, PATCH ou GET. Você pode configurar o envio dos dados em lote, reunindo todas as informações em uma única requisição, ou por linha, enviando cada registro individualmente. Dessa forma, é possível integrar os dados processados no Taxcel Studio com outros sistemas e serviços externos.

1. Abra Exportar API e informe URL da API. Use {Nome} para montar uma URL dinâmica; no modo Por linha, o valor vem da coluna correspondente à linha. Valores utilizados na URL não são enviados novamente no corpo ou na query string.

2. Em Método, selecione POST, PUT, PATCH ou GET. Em Tipo de Envio, escolha JSON, Query String (PARAMS), Form URL-Encoded (BODY) ou RAW (conteúdo da coluna no corpo), conforme a API de destino.

3. Em Modo de Envio, escolha Lote (envia tudo em uma chamada) ou Por linha (uma chamada por linha).

4. Revise Nome do campo de dados e selecione Tabela de entrada.

Tela de configuração do nó Exportar API (parte 1 de 3).

1. Após selecionar Tabela de entrada, escolha os campos disponíveis em Colunas para Enviar e clique em Selecionar, ou use Selecionar todos. Deixe sem seleção para enviar todas as colunas.

2. Em Mapeamento de Campos, clique em Adicionar mapeamento, selecione a coluna da tabela e digite o nome de destino no campo ao lado.

3. Em Parâmetros Estáticos, clique em Adicionar parâmetro, preencha Chave e Valor e selecione texto ou número. Em Parâmetros Dinâmicos, clique em Adicionar parâmetro dinâmico, preencha Nome e tipo de parâmetro e selecione texto ou número no campo ao lado.

4. Em Tipo de Autenticação, selecione Bearer Token, API Key (Header), API Key (Query) ou Basic (Usuário e Senha), conforme a API. Preencha as credenciais exigidas.

Tela de configuração do nó Exportar API (parte 2 de 3).

1. Em Certificado digital, escolha Não usar, Instalado no Windows ou Arquivo .pfx. Para Arquivo .pfx, carregue o arquivo do certificado e informe a senha. O certificado pode ser utilizado junto com a autenticação por token ou API Key.

2. Em Headers Customizados, clique em Adicionar header e preencha Nome do Header e Valor.

3. Clique em Executar e verifique o Status da última execução.

Tela de configuração do nó Exportar API (parte 3 de 3).

Exportar Banco de Dados

O módulo Exportar Banco de Dados permite enviar os dados de uma tabela do fluxo diretamente para um banco de dados externo. Ele oferece suporte aos bancos SQL Server, Oracle, MySQL e PostgreSQL, possibilitando integrar e armazenar as informações processadas no Taxcel Studio em bases de dados utilizadas por outros sistemas ou processos.

1. Abra Exportar Banco de Dados e selecione Tipo de Banco.

2. Em Modo de Conexão, escolha Campos separados ou Connection String.

3. No modo Campos separados, preencha Servidor, Banco de Dados, Usuário e Senha. Informe Porta quando necessário; deixe vazia para utilizar a porta padrão do banco selecionado.

Recomendação: utilize uma conta de banco de dados com permissão de escrita restrita à tabela de destino.

1. Para conectar por Connection String, selecione esse modo e cole a string de conexão do banco no campo correspondente.

Tela de configuração do nó Exportar Banco de Dados (parte 1 de 2).

1. Selecione Tabela de entrada e preencha Tabela de Destino com a tabela que receberá os dados.

2. Em Modo de Inserção, selecione Inserir (append), Limpar e inserir ou Recriar tabela. Inserir (append) adiciona dados sem apagar os existentes.

Atenção: as opções Limpar e inserir e Recriar tabela removem os dados existentes na tabela de destino antes da gravação. Utilize-as somente quando essa substituição for intencional e houver cópia de segurança dos dados.

1. Em Colunas para Exportar, selecione os campos desejados. Deixe sem seleção para exportar todas as colunas.

2. Em Mapeamento de Campos, selecione a coluna da tabela que deseja mapear e digite o nome de destino no campo ao lado.

3. Clique em Executar e verifique o Status da última execução.

Tela de configuração do nó Exportar Banco de Dados (parte 2 de 2).

Exportar E-mail

O módulo Exportar E-mail permite enviar os dados de uma tabela do fluxo por e-mail para um ou mais destinatários. As informações podem ser enviadas como uma tabela HTML diretamente no corpo do e-mail ou como anexo nos formatos CSV ou planilha Excel, permitindo compartilhar os dados processados no Taxcel Studio de acordo com a necessidade.

1. Abra Exportar E-mail e selecione Tabela de entrada.

2. Em Destinatários, digite um endereço e clique em Adicionar. Repita para os demais destinatários.

3. Preencha Assunto.

4. Em Formato de envio, escolha Texto no email, Arquivo CSV ou Planilha Excel.

5. Para Texto no email, preencha Mensagem de abertura (opcional) e Mensagem de encerramento (opcional) quando desejar.

Tela de configuração do nó Exportar E-mail (parte 1 de 2).

1. Em Colunas para exibir no email, escolha uma coluna e clique em Selecionar. Utilize Selecionar todos ou Limpar quando necessário. Deixe sem seleção para exibir todas as colunas.

2. Em Renomear colunas, selecione a coluna, digite o novo nome no campo ao lado e clique em Adicionar para salvar a alteração.

3. Mantenha Limite de linhas (opcional) sem restrição para enviar todas as linhas, conforme o padrão ilimitado. Para fixar um limite, informe a quantidade desejada nesse campo.

4. Para enviar um anexo, selecione Arquivo CSV ou Planilha Excel. Se desejar, utilize o campo opcional que aparece para renomear o arquivo carregado.

5. Clique em Executar e verifique o Status da última execução.

Tela de configuração do nó Exportar E-mail (parte 2 de 2).

Funcionalidades gerais

Recursos de uso geral do Taxcel Studio: seleção de arquivos, visualização de dados, gerenciamento de fluxos, automação, log de erros e anotações no canvas.

Selecionar arquivos e pastas

Vários nós e funcionalidades do Taxcel Studio utilizam a janela Abrir do Windows para selecionar arquivos. O procedimento é o mesmo em todos os casos.

1. Navegue até a pasta

Na janela Abrir, navegue até a pasta que contém os arquivos.

2. Selecione os arquivos

Selecione o arquivo ou os arquivos compatíveis com a operação e confira o campo Nome.

3. Confirme a seleção

Clique em Abrir para confirmar. Para sair sem escolher um arquivo, clique em Cancelar.

Janela Abrir do Windows, com campo Nome e botões Abrir e Cancelar.

Nos nós que oferecem a opção Selecionar pasta, é possível importar os arquivos de uma pasta inteira:

4. Selecione a pasta

Clique em Selecionar pasta e navegue até a pasta desejada.

5. Confirme a pasta

Confira o campo Pasta e clique em Selecionar pasta para confirmar.

Janela Selecionar pasta do Windows, com campo Pasta e botões Selecionar pasta e Cancelar.

Na maioria dos nós de importação, também é possível arrastar os arquivos para a área indicada na configuração do nó.

Preview

O Preview permite verificar as 10 primeiras linhas da tabela do respectivo nó. A funcionalidade está disponível para todos os nós da ferramenta e permite conferir os dados presentes em cada etapa. Dentro da janela, o seletor de nós permite percorrer os nós executados com sucesso.

1. Execute o nó que deseja conferir e aguarde o término da execução.

2. Selecione o nó no canvas e clique no ícone de olho, ou utilize o botão Preview no canto superior direito.

3. Confira as 10 primeiras linhas da tabela exibida.

4. Para consultar outro nó executado com sucesso, utilize o seletor de nós dentro da janela do Preview.

Janela de Preview com as primeiras linhas da tabela do nó selecionado.

Baixar um fluxo da biblioteca

Um fluxo consiste em um conjunto de nós interligados para compor um processo no Taxcel Studio. Ele pode ser construído pelo usuário e salvo para utilização posterior, ou obtido na Biblioteca de Fluxos. A biblioteca apresenta fluxos para download no formato .btx.

1. Acesse Biblioteca de Fluxos.

2. Role a página para localizar e selecionar o fluxo desejado ou utilize Buscar fluxos... e selecione o fluxo nos resultados.

3. Se necessário, filtre por CATEGORIA: Todos, PIS/COFINS, IRPJ, Contábil ou Outros.

4. Confira o título, a descrição e as etiquetas do fluxo escolhido.

5. Clique em Baixar fluxo (.btx) no cartão escolhido.

6. Após baixar o arquivo .btx, siga o procedimento Carregar um fluxo.

Tela da Biblioteca de Fluxos.

Salvar um fluxo

Salvar um fluxo permite guardar o processo montado pelo usuário para utilização posterior.

1. Conclua a montagem e a configuração do fluxo no canvas.

2. Clique no botão de Salvar.

3. Escolha a pasta de destino, preencha Nome com o nome do fluxo e clique em Salvar.

Janela Salvar como do Windows, com campos Nome e Tipo e botões Salvar e Cancelar.

Carregar um fluxo

Carregar um fluxo permite utilizar um processo previamente salvo ou baixado da biblioteca.

1. Clique no botão de Carregar.

2. Na janela Abrir, selecione o arquivo do fluxo (.btx) e clique em Abrir. Mais detalhes em Selecionar arquivos e pastas.

3. Confira os nós do fluxo carregado no canvas.

4. Revise os arquivos de origem e as configurações do fluxo antes da execução. Atenção: carregue somente fluxos da Biblioteca oficial ou de fontes confiáveis e confira os nós de exportação, API, banco de dados e e-mail antes de executar.

Automação

A Automação permite programar a execução de fluxos previamente definidos. É possível selecionar o arquivo do fluxo, definir sua recorrência e informar um e-mail para receber o resultado ao concluir a execução. Podem ser cadastradas várias automações. Para que a automação seja executada, o Taxcel Studio precisa estar aberto e a máquina ligada no horário programado.

1. Acesse Automação.

2. Na tela de automações, clique em Nova Automação.

Tela de Automação (parte 1 de 2).

1. Em Selecionar fluxo (.btx), escolha o arquivo que será executado.

2. Na janela Abrir, selecione o arquivo (ou os arquivos) e clique em Abrir. Mais detalhes em Selecionar arquivos e pastas.

3. Em Tipo de recorrência, selecione Todo dia, Dias da semana, Dia do mês ou Data específica.

4. Para Data específica, preencha Data de execução, no formato indicado dd/mm/aaaa, ou utilize o calendário.

5. Para Todo dia, Dias da semana ou Dia do mês, configure os campos da recorrência escolhida.

6. Em Email para notificação, informe o endereço que receberá o resultado ao concluir a automação.

7. Clique em Salvar. Para outra programação, utilize novamente Nova Automação.

Tela de Automação (parte 2 de 2).

Log de erros

O Log de erros registra falhas ocorridas durante a execução dos fluxos e auxilia a análise pelo suporte técnico. Os arquivos de log ficam em C:\Program Files (x86)\Taxcel\TaxcelStudio\Logs. Os arquivos têm o nome iniciado por log_erros_taxDB.

1. Acesse Log de erros.

2. Consulte os registros apresentados. Quando não há registros, a janela exibe Nenhum erro registrado.

3. Quando houver erros, clique em Copiar tudo para copiar o conteúdo do log.

4. Para localizar os arquivos de log, clique em Mostrar no Explorador de Arquivos.

5. Encaminhe ao suporte o registro solicitado. Ao terminar, clique em Fechar.

Atenção: os registros de log contêm apenas informações técnicas de erro, sem dados fiscais. Ao encaminhá-los, utilize somente os canais oficiais de suporte da Taxcel.

Janela Log de erros.

Anotações

As Anotações permitem organizar visualmente o fluxo no canvas por meio de quadrantes translúcidos, textos e blocos de notas, diferenciados por cores.

1. Acesse Anotações no canvas.

2. Escolha quadrante translúcido, texto ou bloco de notas. Insira o conteúdo e posicione o elemento.

3. Defina a cor e ajuste a organização das anotações.

**Documentação técnica

** Nesta seção do documento está contido o descritivo técnico do Taxcel Studio, seu funcionamento, requisitos técnicos, funcionais, de software e de hardware

Arquitetura Geral

Modelo de funcionamento, princípios de arquitetura e diagrama do Taxcel Studio.

Modelo de Funcionamento

O Taxcel Studio adota um modelo híbrido controlado, composto por:

• Execução local (on-premises do cliente) para processamento de dados fiscais;

• Serviços em nuvem exclusivamente para validação de licenças e execução de funcionalidades de Inteligência Artificial.

Princípios de Arquitetura

• Processamento de dados fiscais em memória (RAM); gravação em disco somente nas exportações e diretórios de saída configurados pelo usuário;

• Nenhuma transferência de dados fiscais para a nuvem da Taxcel, exceto o texto dos prompts e a estrutura das tabelas (nomes das colunas, sem os valores) enviados ao serviço de IA;

• Comunicação externa restrita, autenticada e criptografada.

Diagrama

A arquitetura do Taxcel Studio separa claramente o ambiente do cliente (on-premises) dos serviços externos seguros (nuvem):

• Aplicação on-premises (ambiente do cliente): front-end (UI/UX), serviços backend (módulos de importação, transformação e exportação de dados, módulo de assistência de IA, mecanismo de processamento de consultas), módulo de licenciamento e armazenamento de dados local;

• Serviços externos seguros (nuvem): serviço de validação de licença e serviço de geração assistida de consultas por IA, sem acesso aos dados do cliente;

• Comunicação entre ambientes: TLS 1.2 ou superior, criptografada e autenticada.

IMPORTANTE: os dados fiscais do cliente são processados integralmente no ambiente local. A Taxcel não recebe nem armazena dados fiscais do cliente: na nuvem da Taxcel ocorrem apenas a validação de licença e a geração assistida de consultas por IA. O envio de dados a sistemas externos (APIs, bancos de dados, e-mail, SEFAZ e ADN) ocorre somente quando o usuário configura os nós de integração correspondentes.

Segurança da Informação

Princípios de security by design: comunicação segura, proteção perimetral e tratamento de dados.

A segurança do Taxcel Studio foi projetada desde a concepção, seguindo o princípio de security by design.

Comunicação Segura

• Validação de licença realizada por conexão segura;

• Comunicação com o servidor de licenças utilizando TLS 1.2 ou superior;

• Uso de certificados digitais válidos e atualizados.

Proteção Perimetral

• Servidor de licenças protegido por Web Application Firewall (WAF);

• Mitigação contra ataques de DDoS;

• Mitigação contra ataques de brute force;

• Mitigação contra exploração de vulnerabilidades conhecidas;

• Mitigação contra tentativas de acesso não autorizado.

Tratamento de Dados

• Dados fiscais processados integralmente em RAM;

• Nenhum dado fiscal sensível é enviado para servidores da Taxcel, exceto o texto dos prompts e a estrutura das tabelas (nomes das colunas, sem os valores) enviados ao serviço de IA; o envio a sistemas externos ocorre somente por nós de integração configurados pelo usuário (API, banco de dados, e-mail, SEFAZ e ADN);

• A Taxcel não compartilha dados fiscais do cliente com terceiros. As credenciais configuradas nos fluxos (senhas, tokens, connection strings e senha de certificado) são sempre armazenadas de forma criptografada no arquivo do fluxo (.btx).

Inteligência Artificial (IA)

Como o Taxcel Studio usa IA de forma indireta, controlada e sem acesso às bases de dados do cliente.

Modelo de Uso da IA

As funcionalidades de Inteligência Artificial do Taxcel Studio seguem um modelo indireto e controlado:

• A IA não possui acesso direto à base de dados;

• Não existe conexão direta entre a IA e os bancos de dados do cliente;

• A IA atua exclusivamente como um motor de interpretação e geração de consultas, auxiliando na criação, explicação e otimização de fluxos. Cada licença contratada tem direito a 1.000 (mil) interações mensais com a IA; cada interação corresponde a qualquer solicitação enviada à IA. Ao atingir o limite, a IA poderá ser suspensa até a renovação ou contratação adicional.

Fluxo de Funcionamento da IA

1. O usuário fornece um prompt (comando ou pergunta);

2. O texto do prompt e a estrutura das tabelas (apenas os nomes das colunas, sem os valores ou dados contidos nelas) são enviados ao serviço de IA hospedado no Microsoft Azure, região East US 2 (eastus2);

3. A IA interpreta o contexto do prompt;

4. A IA constrói a query conforme regras previamente configuradas;

5. A execução da query ocorre localmente, sob controle do ambiente do cliente;

6. Os resultados permanecem no ambiente local.

Privacidade e Isolamento

1. Nenhum dado de resultado é reaproveitado ou armazenado pela IA;

2. Não há aprendizado contínuo a partir dos dados do cliente;

3. Cada execução é isolada e descartada ao final do processamento.

Integração com Taxcel Hub

Esta seção descreve como o Taxcel Studio obtém dados do Taxcel Hub (aplicação SaaS): o que é enviado, o que é recebido, como os dados trafegam, em que formato e quais mecanismos de segurança protegem o processo.

1. Visão geral

Para utilizar dados que estão no datalake do Taxcel Hub (como dados da apuração assistida, ao invés de exportar planilhas ou abrir acesso direto ao banco, o Taxcel Studio chama um serviço de extração do Hub, via HTTPS, que:

1. Autentica o usuário;

2. Executa uma consulta pré-definida (de um catálogo fechado) no banco do cliente;

3. lê o resultado em streaming, sem materializá-lo por inteiro;

4. converte o resultado em arquivos Apache Parquet (compactados com ZSTD) em blocos de poucas centenas de milhares de linhas;

5. entrega esses blocos ao Studio na mesma resposta HTTP, conforme ficam prontos.

O Studio grava cada bloco em disco e passa a consultar os dados localmente.

Pontos centrais da arquitetura:

• O Studio nunca envia query SQL. Envia um código de uma consulta do catálogo.

• O Studio nunca informa o banco. Informa a equipe; o servidor determina o banco.

• Conexão sempre iniciada pelo Studio, de dentro para fora, em HTTPS (porta 443). Não é necessário abrir nenhuma porta de entrada no ambiente do cliente.

2. Camada de transporte

3. Autenticação e sessão

Credencial

O usuário se identifica com e-mail e senha de API. A senha de API é gerada pelo Hub na criação do usuário, é independente da senha de login web e só o hash é armazenado. O Hub também valida que o usuário está confirmado e que a venda e a assinatura associadas estão ativas.

Token

O token é um JWT assinado com ES256 (ECDSA P-256 com SHA-256), chave assimétrica mantida no servidor. A validade (expiraEm) é de 3600 segundos por padrão.

O JWT não carrega dados do usuário: contém apenas um identificador de sessão opaco. Os dados do usuário (e-mail, equipes) são resolvidos no servidor a cada requisição - logo, o que o cliente alterar no token não ganha acesso a nada, e uma mudança de permissão (por exemplo, remoção de uma equipe) vale imediatamente, sem esperar o token expirar.

Cada autenticação cria uma sessão própria do Studio, independente da sessão web e da API pública: revogar uma não derruba as outras.

Nas demais chamadas, o token vai em Authorization: Bearer <token>. Não há cookies.

Falha de login: qualquer problema de credencial (senha errada, e-mail inexistente, usuário inativo) retorna a mesma resposta (403 Usuário/Senha incorretos), para que não seja possível descobrir quais e-mails existem.

O token é verificado na abertura de cada requisição. Uma extração já iniciada não é interrompida se o token expirar durante ela.

Autorização e isolamento entre clientes

Um usuário pode pertencer a mais de uma equipe, e cada equipe possui um banco de dados. A escolha de qual banco ler é feita assim:

1. GET /studio/equipes (autenticado) lista as equipes do usuário, com o inventário de arquivos já carregados em cada uma.

2. Na extração, o Studio informa o idEquipe desejado.

3. O servidor procura esse identificador dentro da lista de equipes do usuário autenticado, obtida no momento da requisição. Se não estiver na lista, a requisição é recusada (403). O banco é sempre derivado da equipe encontrada; nenhuma rota aceita um identificador de banco enviado pelo cliente.

Consequência: um usuário autenticado não consegue ler o banco de outro cliente, mesmo que conheça ou adivinhe identificadores.

Catálogo de consultas

O Studio não envia SQL. O servidor mantém um catálogo fechado de consultas, cada uma com código, grupo (assunto, ex.: apuracao), subgrupo opcional e a lista de parâmetros aceitos (nome, tipo, obrigatoriedade).

GET /studio/consultas (sem autenticação; o catálogo é igual para todos e não contém dados de cliente nem o SQL) devolve os grupos e as consultas, permitindo que o Studio monte a interface de escolha. ?grupo=<código> filtra por grupo.

Garantias de segurança do catálogo:

Código desconhecido, parâmetro ausente, parâmetro não declarado ou de tipo errado são recusados (400) antes de qualquer acesso ao banco.

Os parâmetros são repassados ao SQL Server como parâmetros nomeados do driver (@nome, com tipo declarado) - nunca concatenados no texto da consulta. Não há caminho para injeção de SQL.

As consultas são somente leitura (SELECT), com colunas explícitas.

O SQL pode ser reescrito pelo servidor sem alterar o Studio, pois este conhece só o código.

Protocolo de entrega dos dados

Requisição de extração: Erros detectados antes do primeiro byte da resposta são devolvidos com status HTTP próprio e corpo JSON: 400 (requisição ou consulta inválida), 401 (token ausente, inválido ou expirado), 403 (equipe não pertence ao usuário), 429 (limite de extrações simultâneas), 502 (banco do cliente indisponível), 500 (erro interno).

Resposta em quadros

Com status 200, o corpo é uma sequência de quadros em Transfer-Encoding: chunked. Cada quadro:

O prefixo de 4 bytes descreve o tamanho da etiqueta, não do quadro. O tamanho da carga Parquet vem dentro da etiqueta de bloco, no campo bytes.

Sequência de uma extração bem-sucedida:

schema → bloco (×N) → fim

Formato dos dados

Cada bloco é um arquivo Parquet completo, compactado com ZSTD, gerado no servidor.

Os blocos são cortados apenas por contagem de linhas (da ordem de 100 mil a 200 mil linhas, conforme o ambiente). O servidor não interpreta nem ordena o conteúdo: os blocos podem ser lidos em qualquer ordem e a união de todos é o resultado completo.

Mapeamento de tipos:

• Valores nulos são preservados.

Processamento no servidor

O servidor trabalha em pipeline com memória limitada, sem materializar o resultado:

• A leitura do banco usa streaming com contrapressão: se a rede do cliente está lenta, a leitura do banco pausa em vez de acumular memória.

• Cada bloco é escrito em arquivo temporário, enviado e apagado imediatamente após o envio. Os dados não são persistidos no servidor além desse trânsito.

• Se o Studio fechar a conexão, o servidor cancela a consulta no banco e remove qualquer arquivo temporário.

• Há um teto global de extrações simultâneas. Acima dele a resposta é 429 e o Studio tenta novamente depois.

• Em reinício programado, o serviço deixa de aceitar novas extrações e dá um prazo para as em curso terminarem; as que sobrarem recebem a etiqueta erro.

Segurança - resumo

Cache e consistência no lado do Studio

• O servidor informa um hashConsulta (SHA-256 de banco + consulta + parâmetros) na etiqueta schema. O Studio usa esse valor como identificador da pasta de cache.

• Cada bloco é gravado primeiro em uma área temporária e só é promovido ao cache ao receber fim, de modo que uma extração interrompida nunca deixa arquivos parciais parecendo válidos.

• O hash identifica a consulta, não a atualidade dos dados. A atualização dos dados é feita por nova extração.

Disponibilidade e limites

Requisitos de Rede e Ambiente

Portas, URLs, DNS e pré-requisitos de hardware e sistema operacional para instalar e rodar o Taxcel Studio.

Requisitos de Rede

Em ambientes com proxy corporativo, firewall ou VPN, é necessário liberar apenas os recursos estritamente necessários.

Portas de Comunicação

• TCP 443 (HTTPS - obrigatório).

URLs Necessárias

• https://taxcel.com.br/

• https://onpremises.taxcelapp.com

• https://AiTaxcel.services.ai.azure.com

Resolução de DNS

• Permitir resolução DNS para domínios hospedados em infraestrutura Microsoft Azure.

Requisitos de Ambiente

Para garantir o funcionamento adequado, estável e com desempenho satisfatório do Taxcel Studio, o ambiente do usuário deve atender aos seguintes pré-requisitos mínimos.

Sistema Operacional

• Microsoft Windows 10 (64 bits) ou superior, ou Windows Server compatível (mediante licença específica para ambientes compartilhados);

• Microsoft .NET Framework 4.8, devidamente instalado e atualizado.

Memória RAM

• Mínimo: 8 GB. Embora funcional, essa configuração compromete a fluidez e limita significativamente a experiência do usuário;

• Recomendado: 12 GB ou mais, especialmente para o processamento de arquivos de grande volume.

Processador

• Intel Core i5 (10ª geração ou superior) - recomendado para arquivos pequenos e médios;

• Intel Core i7 (10ª geração ou superior) - recomendado para arquivos grandes;

• AMD Ryzen (3ª geração ou superior) - adequado para ambos os cenários de uso.

Armazenamento

• Espaço mínimo livre em disco: 3 GB para instalação do software;

• Recomendado: manter pelo menos 10 GB de espaço livre para criação de fluxos e processamento de grandes volumes de dados.

Permissões do Usuário

• Permissão administrativa necessária apenas para instalação do software;

• Não é necessário privilégio de administrador para uso contínuo da aplicação.

Informações Técnicas

Modelo de execução, comunicação externa, logs, atualizações e limitações do Taxcel Studio.

Modelo de Execução

• Aplicação desktop executada localmente no ambiente do cliente;

• Processamento fiscal realizado em memória (RAM); dados só são gravados em disco quando o usuário configura exportações ou diretórios de saída.

Comunicação Externa

• Comunicação restrita aos serviços essenciais;

• Tráfego criptografado utilizando TLS 1.2 ou superior;

• Autenticação baseada em licença válida.

Logs e Telemetria

• O Taxcel Studio não coleta logs contendo dados fiscais;

• Logs técnicos limitam-se a erros de aplicação (sem conteúdo fiscal);

• Logs permanecem no ambiente local do cliente.

Atualizações de Software

• Atualizações distribuídas de forma controlada pela Taxcel; todos os executáveis e instaladores são assinados digitalmente;

• Processo de atualização não acessa dados do cliente;

• Recomenda-se aplicação das atualizações para correções de bugs, segurança e melhorias.

Limitações e Restrições

• O Taxcel Studio não realiza backup de dados fiscais;

• A responsabilidade pelo backup e governança dos dados é do cliente;

• O funcionamento das funcionalidades de IA depende de conectividade com a internet;

• Ambientes altamente restritivos devem validar previamente as liberações de rede.

Políticas de Uso de Licença

Orientações, restrições e regras aplicáveis ao licenciamento do Taxcel Studio.

Esta página tem como finalidade detalhar as orientações, restrições e regras aplicáveis ao licenciamento do Taxcel Studio, assegurando sua utilização em conformidade com os termos definidos.

Licença Convencional (Unitária)

A licença convencional (unitária) das soluções Taxcel é destinada exclusivamente para uso individual, atendendo aos seguintes critérios:

• Utilização em ambiente local;

• Uso por um único usuário;

• Instalação em máquina física dedicada.

Restrições de Uso

É expressamente proibida a instalação ou utilização da licença convencional (unitária) em ambientes virtualizados, compartilhados ou que permitam acesso remoto por múltiplos usuários, incluindo, mas não se limitando a:

• Máquinas Virtuais (VM);

• Ambientes VMware;

• Citrix;

• Hyper-V;

• Ambientes compatíveis com acesso remoto compartilhado (RDP ou similares);

• Windows Server;

• Máquinas convencionais com acesso via RDP habilitado para múltiplos usuários.

Uso em Ambientes Compartilhados ou Virtualizados

Para utilização das soluções Taxcel em ambientes compartilhados, virtualizados ou com acesso remoto multiusuário, o cliente deverá entrar em contato com o time comercial, a fim de conhecer as opções de licenciamento adequadas para esse tipo de cenário.