O que é TSI?

O serviço de integração do TAF ( TAF Service Integration ) é o novo mecanismo de integração ERP-Protheus Vs TAF.
O TSI foi criado exclusivamente para clientes que usam o TAF como módulo do ERP-Protheus, ou seja, ambos no mesmo banco de dados.

Pré Requisitos

• Requer um TOTVS Application Server build 7.00.170117A com geração superior a 23/09/2019.
• Requer um TOTVS DbAccess  igual ou superior a 19/11/2019
• Rodar o UpdDistr ( sdfbra.txt referente ao pacote acumulado do SIGATAF ).
• Wizard Config TAF ( para criar os campos "s_t_a_m_p_" nas tabelas do ERP, ex: SA1, SA2, SFT, etc... ).

Banco de Dados Homologados

• A integração On-line depende do novo campo S_T_A_M_P_ e sua criação está disponível para os Banco de Dados MSSQL, ORACLE e  POSTGRES.

O que é stamp?

Um campo interno para tabelas do DBAccess, não visíveis na estrutura de acesso pelo AdvPL, que registre um datetime e/ou timestamp para cada registro inserido e/ou alterado na base de dados. 
O tipo do campo criado na tabela é DATETIME (para MSSQL) e TIMESTAMP (para Postgres e Oracle)

Para recuperar o campo de controle S_T_A_M_P_ e recuperar a informação completa ( data e horário ), por exemplo no formato yyyy-mm-dd hh:MM:ss.mmm
( Ano com 4 dígitos, mês com 2 dígitos, dia com 2 dígitos, e horário completo (24h) com precisão de milissegundos, deve ser feito um CAST específico para retornar a informação como "C" Caractere no AdvPL,
para cada banco de dados, vide exemplos abaixo:

• MSSQL :      convert(varchar(23), S_T_A_M_P_ , 21 )
• POSTGRES : to_char(s_t_a_m_p_,'YYYY-MM-DD HH:MI:SS.MS') 
• ORACLE :    to_char(s_t_a_m_p_,'YYYY-MM-DD HH24:MI:SS.FF')

Confira mais sobre stamp na documentação do DbAccess: Implementação - Campo de controle adicional no DBAccess - S_T_A_M_P_

Implantação

Dicionário

• Atualmente o pacote centralizador do TSI no AtuSx é o 009134 (release 33). Porém já foi incorporado no segregado e agora está disponível no portal através do pacote acumulado 21/01/2022.
  No dicionário constam os campos stamp nas tabelas do TAF e a criação da tabela de log V5R.

Configuração Inicial Para utilização

• Pré Requisitos e banco de dados homologados.
• Rodar o UpdDistr com sdfbra do pacote acumulado para o metadados do TAF.

Configuração no SIGATAF

A wizard de configuração do TAF ganhou uma nova opção para criação dos campos S_T_A_M_P_
Para que a opção do "TSI - TAF SERVICE INTEGRATION" seja exibida no Wizard TAF, é necessário que exista pelo menos uma nota escriturada (Tabelas SF3 e SFT) cadastrada no sistema e rodar o UpdDistr antes.

• Após a atualização conforme especificado em Pré-requisitos, basta executar a wizard de configuração do TAF marcando a nova opção, [ ] TSI - TAF Integration Service

Execute a wizard, resultando em sucesso, será apresentada a tela com a mensagem conforme abaixo.

Tabelas Afetadas Criação STAMP

As tabelas do Protheus que sofrerão a criação do campo S_T_A_M_P_ são:

SB1, SFT, SF4, SB5, SA1, SA2, SA4, SAH, CT1, F2Q, CDN, CTT, SE1, SE2, CCF, SF1, SF2, SF3, CCE, SYD, CDH, SON, CKX, CDT e CDG.

Configuração no SIGACFG

O TSI deverá ser incluído no agendamento ( schedule ) como um serviço ( job ) sempre ativo.
Desta maneira, ao incluir ou alterar um novo cadastro ou movimento no ERP, o JOB se encarregará de executar a integração automaticamente de forma transparente ao usuário.
O controle é feito através da comparação dos campos do ERP-Protheus S_T_A_M_P_  Vs  XXX_STAMP do TAF.
Exemplo de configuração:

Índices do banco de dados sugeridos ( Performance )

CREATE NONCLUSTERED INDEX SFTT10ESP ON SFTT10(FT_FILIAL, [FT_NFISCAL] ,[FT_SERIE], [FT_CLIEFOR], [FT_LOJA],[FT_IDENTF3], [FT_ENTRADA],[FT_ESPECIE], R_E_C_N_O_, D_E_L_E_T_)

CREATE NONCLUSTERED INDEX SF3T10ESP ON SF3T10(F3_FILIAL, [F3_NFISCAL] ,[F3_SERIE], [F3_CLIEFOR], [F3_LOJA],[F3_IDENTFT], [F3_ENTRADA],[F3_ESPECIE], R_E_C_N_O_, D_E_L_E_T_)

CREATE NONCLUSTERED INDEX SFT010STP ON SFT010(FT_FILIAL, S_T_A_M_P_, R_E_C_N_O_, D_E_L_E_T_)

Par de Fontes e Tabelas

Processos

Projeto Interno ( DEVS )

O objetivo deste guia é ajudar os membros da equipe a entender a composição do projeto e como nos organizamos para planejar, desenvolver, testar e documentar o TAF TSI.
A documentação oficial publicada para os clientes consta em TSI - TAF Service Integration.
O projeto consta no diretório: .../Master/Fontes/TAF/Integração/TSI, sendo composto por fontes na raiz (genéricos) , subpasta ERP (extração dos módulos do protheus) e subpasta TAF (APIS que fazem operações nas tabelas legados do TAF).
O controle com o nome dos fontes, descrição e analista que desenvolveram o TSI, fica disponível no google docs \Tabelas TAF.

Divisão na execução do Desenvolvimento

Quando é necessário criar um novo leiaute no TSI, precisamos trabalhar em alguns pontos, são eles:

Extração do ERP

Aqui é contemplado a regra de extração apenas do ERP Protheus, que em muito(s) casos a(s) regra(s) consta(m) nos extratores:

• extrator fiscal (...\Master\Fontes\Livros Fiscais\Extrator\ExtFisxTaf.prw),
• extrator financeiro(...\Master\Fontes\Adm\FINA989.prw) ou
• extrator contábil (...\Master\Fontes\Adm\ECD\CTBS001.prw e CTBS103.prw).

1. Entender e elaborar a regra de extração.
   
   

2. Nessa etapa são levantados todos os campos necessários na extração,  a planilha interna com o layout consta em google drive em Layout TAF.xlsx
   
   
3. Aqui também é necessário utilizar o pacote centralizador do TSI no atusx, para criar o campo STAMP na tabela legado do SIGATAF.
   
   
4. Conforme DOD dessa tarefa, aqui também é esperado a geração do JSON com o conteúdo dos campos do layout nas tags pré definidas para integração.
   
   
5. Controle do Stamp criado na Tabela do ERP e Mecanismo de validação do STAMP entre Protheus x TAF finalizado.

Integração ERP e TAF ( Json x Hash )

Etapa onde o layout já está sendo extraído pelo TSI (geração do json mencionado na etapa 4 da extração do ERP) e agora será construído a integração das informações para o TAF.

1. Construir Hash do JSON para o TAF pai, filho e netos (se houver), o modelo dos fontes com hash consta em TAF\Integração\TSI\TAF\WSTAFXXX.prw.
   
   
2. Realizar o processo de gravação das tabelas do TAF, através de um mecanismo que irá receber os dados do JSON  (utilizar o motor de cadastro básico TAFA565 ou motor pai, filho e netos TAFA585).
   Integração do JSON com o TAF finalizado para o evento, iremos instanciar o modelo do respectivo cadastro que será integrado e alimentá-lo com as informações extraídas do Protheus.
   
   
3. Validar se o Commit foi possível (Tabelas do TAF gravadas com os dados do JSON), se sim grava o campo TAFSTAMP com o mesmo valor do STAMP trazido do Protheus para o respectivo evento
   (Controle do STAMP nas tabelas do TAF implementado), precisa ser a última instrução da função.
   
   Ponto de atenção: não é necessário instanciar o modelo a cada novo registro de integração, todo o processo acima precisa estar dentro de controle de transação, ou seja, se cair a conexão durante o processo
   o campo TAFSTAMP não será preenchido e o registro será reintegrado no novo processamento do TSI.
   
   
4. Gravação da tabela V5R para os erros de integração, caso não seja possível a integração gravar a tabela de "Erros de Integração TSI" (Tabela V5R), veja os principais itens a serem validados em estrutura de log.
   
   
5. Para auxiliar a equipe de suporte, ou na análise de um possível problema, devemos avaliar pontos onde é válido adicionar conouts (TAFCONOUT), ver em documentação oficial TAF Service Integration \ Análise Técnica \ Lista de Erros.
   
   
6. Colocar a rotina dentro do Schedule ( TAFA573 ).

Construção APIS

Aqui será construídas as APIS para substituir o layout TAF.

1. Construir API que recebe mensagem JSON e grava no cadastro MVC do TAF o respectivo leiaute.
   
   

2. Construir as APIs com os seguintes tipos de requisição:
   
   PUT ( pode receber um código ou uma lista para atualizar )
   http://localhost:8099/REST/api/tsi/v1/tsiCommonExternalTariff/63013000/?sourceBranch=T1D MG 01
   http://localhost:8080/rest/api/tsi/v1/tsiinvoice/?sourceBranch=T1D MG 01 (+Body)
   
   DELETE ( pode receber parâmetros ou uma lista para apagar ) 
   http://localhost:8080/rest/api/tsi/v1/tsiinvoice?sourceBranch=T1D MG 01&operationType=1&modelIdentificationCode=55&taxDocumentSeries=1&taxDocumentNumber=000000002 &fiscalDocumentDate=20201015&participatingCode=CSP000101
   http://localhost:8099/REST/api/tsi/v1/tsiCommonExternalTariff/?sourceBranch=T1D MG 01 (+Body)
   
   POST ( pode receber uma lista para inserir )
   http://localhost:8080/rest/api/tsi/v1/tsiinvoice/?sourceBranch=T1D MG 01 (+Body)
   http://localhost:8099/REST/api/tsi/v1/tsiCommonExternalTariff/?sourceBranch=T1D MG 01 (+Body)
   
   GETID ( pode retornar um único código )
   http://localhost:8099/REST/api/tsi/v1/tsiCommonExternalTariff/63013000/?sourceBranch=T1D MG 01
   http://localhost:8080/rest/api/tsi/v1/tsiinvoice/idTsiinvoice/?sourceBranch=T1D MG 01&taxDocumentNumber=NTSAIDA
   
   GETLIST ( pode retornar uma lista com paginação, tratar os parâmetros: HasNext, Page, PageSize, Do Código, Até Código, ordenação, etc... )
   http://localhost:8080/rest/api/tsi/v1/tsiinvoice/?sourceBranch=T1M SP 03&Page=1&PageSize=50&invoiceOf= &invoiceUp=ZZZZ
   http://localhost:8099/REST/api/tsi/v1/tsiCommonExternalTariff/?sourceBranch=T1D MG 01&commonExternalTariffOf=63013000&commonExternalTariffUp=63014000

   { "invoice": [ { "stamp": "2020-11-19 13:44:42.480", "finalDocumentNumber": "0000000003", "AIDFNumber": "", "electronicKeyDocument": "", "identificationSituation": "00", "federativeUnitOrigin": "SP", "shippingIndicator": "1", "valueOfGoods": 9000, "valueOfServices": 0, "documentType": "00", "fiscalDocumentDate": "15/10/20", "insuranceAmount": 0, "documentValue": 9000, "placeOfDelivery": "", "freight": 0, "untaxedAllowanceAmount": 0, "taxDocumentIssuer": "0", "taxDocumentSeries": "1", "valueReducedISSMaterials": 0, "modelIdentificationCode": "55", "participatingCode": "CSP000101", "taxDocumentNumber": "00000000", "typeOfPayment": "1", "amountOfAccessoryExpenses": 0, "discountAmount": 0, "operationType": "1", "taxDocumentEntryAndExitDate": "15/10/20", "otherExpenses": 0, "fiscalDocumentItems": [ { "itemNumber": "0001", "cfopIndicator": "5933", "itemAdditions": 0, "originIdentCode": "1", "operationNature": "503", "accountingValue": 6000, "socialSecurityExemption": "2", "itemAmount": 1, "itemValue": 6000, "discountValue": 0, "physicalMovement": "", "itemTotalValue": 6000, "acessoryExpense": 0, "unitOfMeasurement": "UN", "itemCode": "ISS", "serviceCode": "", "cityServiceCode": "", "serviceType": "", "dipamCode":"" } ] } ] }

3. Definimos que a tabela de log de erros será gravada nas integrações via REST para todas as validações necessárias, as mensagens precisam ser criadas a nível de usuário, sem nenhum detalhe técnico com relação ao erro encontrado.
   
   
4. Criar o mecanismo de integração via REST para as linhas e via função para o Protheus (item deve ser alinhado com a etapa de integração do ERP Protheus).
   
   
5. Layout Integrado na tabela específica do TAF.

OPEN API

Aqui serão catalogadas e disponibilizadas as APIS construídas para os nossos clientes.

Implementar a estrutura para a documentação do API.TOTVS.COM.BR. Utilizar o cost center como exemplo.

*Ainda não publicar mas ao final da entrega iremos sim publicar a API para uso dos clientes;

Poderá ser feito com o openAPI Preview in Browse ou com o swagger.

• Baixar o TTalk
  https://github.com/totvs/ttalk-standard-message
  cd C:\api
  git clone https://github.com/totvs/ttalk-standard-message.git

• TTALK STANDARD MESSAGE
  renomear para standard-message (constará uma pasta 1xAPI 1xSchemma)
  
  
• instalar (no terminal -->  npm install )

• Baixar tafintegrationservices_1-000j.json e TafIntegrationService_v1_000.json (estão anexos a issue de cada leiaute).
  Importante renomear com "_1"
  → tafintegrationservices_1-000j.json  em schemas → C:\api\standard-message\jsonschema\schemas
  → TafIntegrationService_v1_000.json em apis → C:\api\standard-message\jsonschema\apis

• baixar plugin x vs ( openapi-designer )
  
  
• Mudar referencia por causa do preview, alterar no v1
  de ./jsonschema/schemas
  para ../schemas
  Salvar
  
  
• ctrl + shift + P ( openApi Preview In Browse )
  
• Posicionar no V1
  Voltar o v1 para ./jsonschema/schemas
  de ../schemas
  para ./jsonschema/schemas
  Salvar
  
  
• executar npm run test
  de 32655 passing (2m)
  para 32656 passing
  
  
• Verificar se existe branch e subir, exemplo: oficial (master), homologação em definição*.

Dependência de Fontes

Lista dos fontes que não estão pasta $/Protheus_Padrao/Fontes_Doc/Master/Fontes/TAF/Integração/TSI do TFS mas foram alterados para o TSI.

Estrutura HashMap

O hash é montado nos fontes que constam na pasta TAF\Integração\TSI\TAF (API TSI). Para cada pai, possuímos o hash com informações genéricas para auxiliar na gravação do modelo.
Para cada tabela possuímos um hash com o "de/para" ( Tag x Campo). Todos os hashs são estáticos, ou seja a estrutura é montada apenas no início do chamado do programa.

• Exemplo de Informações Genéricas
  
  HMSet( oHash, 'm_o_d_e_l_' , 'TAFA062' )
  HMSet( oHash, 'm_o_d_e_l_C_2_0_', 'MODEL_C20' )
  HMSet( oHash, 's_o_u_r_c_e_' , 'TAFA062' )
  HMSet( oHash, 'a_r_e_a_' , 'C20' )
  HMSet( oHash, 'o_r_d_e_r_' , 1 )
  HMSet( oHash, 'k_e_y_' , cKey )
  HMSet( oHash, 's_e_e_k_' , cSeek )
  HMSet( oHash, 't_a_g_i_d_' , 'invoiceId' )
  
  Para cadastros ou movimentos, na estrutura pai, filho e neto, existem as tags de o model, submodel e submodel2, exemplo na utilização da apuração de ICMS:
  
  HMSet(oHash, 'm_o_d_e_l_' , 'MODEL_C2S')
  HMSet(oHash, 's_u_b_m_o_d_e_l_' , {{'MODEL_C2T'/*model filho*/,'adjustmentApuration' /* tag filho*/, 'HashC2T()' /* hash filho*/ }} )
  HMSet(oHash, 's_u_b_m_o_d_e_l_2' , {{'adjustmentApuration'/* tag filho*/,'MODEL_T02'/*model neto*/,'accumulatedAdjust'/*tag neto*/, 'HashT02()' /*hash neto*/}} )
  
  
• Exemplo com "de/para"
  
  Apenas o campo:          SetHashKey(oHashC20, "taxDocumentNumber"   ,"C20_NUMDOC" )
  
  Com consulta padrão:  SetHashKey(oHashC20, "participatingCode"         ,"C20_CODPAR#F3#")
  
  Tipo data:                      SetHashKey(oHashC20, "fiscalDocumentDate"      ,"C20_DTDOC#DT#" )

Estrutura LOG

Os erros são aglutinados e gravados em uma única linha na V5R (por chave do cadastro), substituindo o erro anterior caso exista.
Incluir VLDDATA para tratamento nos mesmos moldes do que foi feito no cadastro de nota fiscal.
Filial sendo gravada no campo V5R_CODFIL e não na V5R_REGCHAVE.
Caso o ajuste seja realizado e chave do registro seja "comitado" no TAF, o log é apagado na sequência.

As principais validações no TSI são por modelo do mvc (VldData) ou regras específicas:

• Por tipo de dados, ex: data, numérico, lógico ou caractere (FWNOSTRUCT);
  
  
• Obrigatório (OBRIGAT);
  
  
• Se código existe na consulta padrão F3 (NOTFOUND);
  
  
• Se o tamanho é excedido (FWNOWIDTH);
  
  
• Se o conteúdo consta no combox (FWNOLIST);
  
  
• Se o registro existe na origem (NOTEXIST);
  
  
• Se o conteúdo pode ser editado (FWWHEN);
  
  
• Regra de modelo específico, exemplo: Se a nota necessita de item (TAFHLPNF017);
  
  
• Se o commit do modelo é válido e não estoura o uniqline (UNIQUELINE);
  
  
• Se o formato de data é válido (DATE);
  
  
• Se é válido apagar uma chave estrangeira (FWFORMCANCEL);
  
  
• Se houve falha na atribuição de conteúdo (LOADVALUE)