Page tree
Skip to end of metadata
Go to start of metadata

Este documento tem por objetivo definir, especificar e explanar sobre os critérios técnicos necessários para integração entre os sistemas de controle empresarial (ou qualquer outro software desejado) e o sistema TOTVS Automação Fiscal.

Para que se torne mais efetivo o entendimento deste documento é altamente recomendável que seja acessado o link abaixo para conhecimento de todo o escopo do produto:

TAF Home

Índice

Contexto de negócio

O TAF ( TOTVS Automação Fiscal ) foi criado com o objetivo de consolidar dados e layouts, a fim de fornecer recursos de validação e consistências desses dados para posterior envio as plataformas governamentais.

Este documento visa fornecer as especificações técnicas para que os softwares de gestão possam iniciar integração com o TAF.


Modelo Operacional

O software controlador dos processos empresarias gerará uma mensagem eletrônica contendo as informações fiscais, contábeis e trabalhistas, no formato pré-definido pela TOTVS, de maneira a garantir a integridade dos dados. Esta mensagem eletrônica será então submetida a processos de integração e validação de estrutura, com o intuito de consistir integridade e conteúdo da mensagem, definindo assim se esta está apta a ser importada ao sistema consolidador.

Após receber todos os dados necessários, o TAF submete as informações importadas a outros processos como validação e consistência de layout. O objetivo final é gerar os dados para importação/transmissão dos arquivos em formato pré-definido pela Secretaria de Fazenda Estadual de jurisdição do contribuinte emitente, Prefeitura ou Receita Federal.

De forma resumida existem quatro modelos de integração disponíveis para integração:

  1. Integração Online:
    Neste cenário o ERP envia as informações em real-time para o TAF, ou seja, no momento em que o usuário confirma a operação no ERP o TAF já é atualizado automaticamente. Este cenário somente é disponível para o produto Microsiga Protheus quando o ERP utilizar a mesma base (Dicionário de Dados/RPO) do produto TAF, ou seja, utiliza o TAF como módulo do sistema.

  2. Integração Banco a Banco:
    Neste cenário utiliza-se conexão banco-a-banco para realizar a integração das informações. Este conceito utiliza a própria ferramenta DBAcces/TopConnect. Com isso, a aplicação grava em uma tabela compartilhada e sob seu domínio, ou seja, no mesmo database, a mensagem criada por sua rotina de extração. Após gravá-lo, o TAF através de suas rotinas de monitoramento, processará as mensagens disponíveis e transportará para uma tabela de controle dentro de seu ambiente de processamento (TAF).

  3. Integração de Arquivo físico:
    Neste cenário o software de origem gera a mensagem de integração em um arquivo físico (TXT ou XML, dependendo do escopo da integração) e submete este arquivo a um processo de importação no TAF. Este processo pode ser feito manualmente ou de forma automática (agendada) no próprio TAF.

  4. Integração via Web Service

    Disponível à partir da release 12.1.17

    Neste cenário utiliza-se um serviço web disponibilizado pelo TAF para envio das mensagens de integração. Neste modelo o ERP deve, através do protocolo HTTP (HTTPS), enviar a mensagem ao Web Service do TAF (que deve estar previamente configurado e no ar) utilizando um método POST, e poderá utilizar de outros métodos para consulta e monitoramento das mensagens enviadas.



Sistemas Envolvidos

Qualquer ERP( Totvs e não Totvs ) é elegível de integração com o TAF, basta desenvolver a mensagem de integração baseada no Layout Único de Integração.

Para geração do E-Social o layout de integração com o TAF é o mesmo Layout disponibilizado pela Receita Federal e pode ser encontrado na página abaixo:

Layout Taf - eSocial


Arquitetura da Integração

Visão

Layout/Mensagem de Integração

Layout Único de Integração  do TAF tem como objetivo possuir a maior quantidade de informações para a geração das mais variadas obrigações acessórias, ou seja, o Layout foi elaborado de forma lógica, garantindo que de apenas uma integração diversas obrigações possam ser geradas dentro do TAF.

Além do Layout Único de Integração existe também escopos onde o TAF utiliza o próprio Layout da obrigação disponibilizada pelo Fisco para integração com os ERP´s, como por exemplo o e-Social.

Abaixo temos uma tabela demonstrando quais escopos utilizam o Layout Único do TAF e quais utilizam o próprio Layout da Receita.

Escopo
Layout Único
Layout da Receita

Informações Fiscais ( Ex: EFD ICMS/IPI, EFD Contribuições... )

SimNão

Informações Contábeis ( Ex: ECF, Apuração IRPJ/CSLL... )

SimNão

Informações Trabalhistas ( Ex: eSocial )

NãoSim


Estrutura da Tabela Compartilhada

A tabela compartilhada é criada após a execução da Wizard Inicial do TAF( Sempre executada no primeiro acesso ao TAF ), no banco do ERP seu nome será TAFST1, e ela possui os seguintes campos:

TAFFIL (Caracter): Código da Empresa/Filial do ERP, o código informado nesse campo depois será amarrado a filial do TAF que receberá as informações na integração;

TAFCODMSG (Caracter): Informa o tipo da mensagem que será gravada na linha, podendo ser 1 para arquivo texto ou 2 para XML;

TAFSEQ (Caracter): Quando a mensagem enviada superar 1MB, deve ser quebrada em duas linhas na tabela, nesse cenário esse campo deve ser incrementado com um sequencializador, iniciando em '001';

TAFTPREG (Caracter): Nome do Layout que será integrado, podendo ser tanto do Layout Totvs quando o nome do próprio registro de acordo com o Layout da Receita Federal

TAFKEY (Caracter): Chave do registro, a ser gerada de acordo com regra gerada pelo ERP para posterior recuperação da informação;

TAFMSG (Caracter): Mensagem a ser enviada para o TAF

TAFSTATUS (Caracter): Status do registro na tabela, sempre que gravado pelo ERP deve ser gravado como "1", o TAF seta para "2" quando o registro já foi integrado;

TAFTICKET (Caracter): Código de identificação do lote da integração. É opcional, e caso o ERP não informe o TAF gera um código aleatório no formato UUID.

TAFDATA (Caracter): Data para identificação do lote da integração. É opcional, e caso o ERP não informe o TAF gera automaticamente.

TAFHORA (Caracter): Hora para identificação do lote da integração. É opcional, e caso o ERP não informe o TAF gera automaticamente.

TAFOWNER (Caracter): Identificação do ERP dono do XML a ser integrado. É Opcional. 


Os demais campos são de controle do TAF, na tabela TAFST2:

TAFPRIORIT (Caracter): Prioridade de processamento do registro. Mais detalhes no tópico "Recursos de integração".

TAFSTQUEUE (Caracter): Status do registro na fila de processamento. Mais detalhes no tópico "Recursos de integração".

R_E_C_N_O_ (Numérico): Campo de controle interno ( TOTVS|DbAccess )

R_E_C_D_E_L_ (Numérico): Campo de controle interno ( TOTVS|DbAccess )

D_E_L_E_T_ (Numérico): Campo de controle interno ( TOTVS|DbAccess )


Exemplo da tabela TAFST1 populada:


API - Interfaces de Integração

API de Integração - Microsiga Protheus


API - Microsiga Protheus

As API's abaixo devem ser utilizadas somente para o modelo de integração nativa (online), ou seja, onde o TAF está sendo utilizado como módulo do sistema Microsiga Protheus.

APIDescriçãoDocumentação

TAFAPIERP

Serviço utilizado para invocar de forma automática os processos de integração do TOTVS Automação Fiscal.Acesse TAFAPIERP

TAFPrepInt

Serviço utilizado para integração de informações no Layout do eSocial.Acesse TAFPrepInt.

TAFProcLine

Serviço que recebe a mensagem que deve ser integrada ao TAF e realiza a cargas das tabelas de acordo com o Layout TOTVS.Acesse TAFProcLine

TAFGetStat

Serviço utilizado para consultar o status de determinado registro na base de dados do TAFAcesse TAFGetStat

TAFDelTicket

Serviço para excluir Tickets de integração com o TAF.Acesse TAFDelTicket


API de Integração - Outros Sistemas

APIDescriçãoDocumentação

WSTAFST2

Serviço que integra os produtos na tabela compartilhada TAFST2, permite a consulta do status de integração e cadastro dos registros através do TAFKEY ou TAFTICKET e permite a exclusão dos registros através do TAFTICKET.Acesse Web Service REST - Integração

WSTAFQueryElements

Serviço que permite que uma aplicação faça uma consulta generalizada na base de dados do TOTVS Automação Fiscal para obter uma série de registros/elementos através de um status pré-definido pela aplicação (de acordo com os status existentes no TAF) ou do tipo do registro (de acordo com os tipos existentes no TAF)Acesse Web Service REST - Consulta de Elementos

WSTAFGetXML

Serviço que permite que uma aplicação requisite ao TAF que retorne um ou mais dados dentro de uma estrutura XML, a mesma que foi (ou que será) enviada ao Governo. Caso o evento ainda não tenha sido transmitido ao Governo, será retornado o XML gerado pelo próprio TAF. Caso o evento já tenha sido transmitido e autorizado pelo Governo, será retornado o XML final (inclusive com a assinatura do TSS).Acesse Web Service REST - Retorno de XML

Regra de Execução da Integração para integrações que não utilizam o Layout Totvs

Quando é enviado para o TAF um XML do eSocial, por exemplo, o mesmo é submetido a uma regra que define se a operação será realizada ou não dentro do TAF, sempre que o retorno for negativo a Origem receberá um retorno com o erro, seja via gerenciador de integração ( Integração Banco a Banco ) ou um array com os erros encontrados ( Integração OnLine )

Regra de Execução da Integração para integrações que utilizam o Layout Totvs

Nessa integração o TAF sempre verifica o campo TAFKEY, caso seja uma TAFKEY já enviada previamente o TAF realiza o Replace do cadastro no TAF, caso contrário realiza a inclusão da informação.

sempre que ocorrer algum problema na integração a Origem receberá um retorno com o erro, seja via gerenciador de integração ( Integração Banco a Banco ) ou um array com os erros encontrados ( Integração OnLine )

Processos automáticos de integração e tranmissão do TAF

Tabela de processos de integração e modelos operacionais aplicáveis:

ProcessoDescriçãoIntegração OnlineBanco a bancoArquivo físicoWeb Service
TAFProc0Cópia de dados da tabela TAFST1 para TAFST2N/AManual/AutomáticoN/AN/A
TAFProc1Limpeza da tabela TAFST1N/AManual/AutomáticoN/AN/A
TAFProc2Integração de dados para tabelas de negócio (base oficial)AutomáticoManual/AutomáticoManual/AutomáticoManual/Automático
TAFProc3Validação e consistência de LayoutManual/AutomáticoManual/AutomáticoManual/AutomáticoManual/Automático
TAFProc4Transmissão de Eventos para o TSSManual/AutomáticoManual/AutomáticoManual/AutomáticoManual/Automático
TAFProc5Consulta de Eventos ao TSSManual/AutomáticoManual/AutomáticoManual/AutomáticoManual/Automático
TAFProc6Importação de arquivo físicoN/AManual/AutomáticoManual/AutomáticoN/A

Para maiores informações de como realizar a configuração dos Jobs de Integração acesse o lonk abaixo:

06. Efetue uma integração


Particularidade de Integração do eSocial

Comportamento das Integrações x Operação dos Eventos


Objetivo

Esta tabela tem como objetivo demonstrar os resultados que devem ser alcançados nos cenários possíveis de manutenção com relação aos eventos do eSocial no TAF.

 
Novo Registro

Evento Corrente:

Incluído

Evento Corrente:

 Alterado

Evento Corrente:

 Excluído

Situação Corrente:
Transmitido

Situação Corrente:

 Não Transmitido

InclusãoExecutaOperação não realizadaOperação não realizadaAnalisar duas próximas colunasExecutaOperação não realizada
AlteraçãoOperação não realizadaExecutaExecutaAnalisar duas próximas colunasOperação não realizadaExecuta
ExclusãoOperação não realizadaExecutaExecutaOperação não realizada

Detalhes

A lista abaixo traz mais detalhes sobre cada operação realizada na integração de eventos, conforme tabela acima.


1. Realizando uma nova inclusão no TAF:

  • Registro não existe no TAF:
         - Deve ser realizada a inclusão do registro;


  • Situação do Registro igual a "I" (Incluído):     

         - Não deve ser realizada a integração e no gerenciador deve aparecer a mensagem: 

           "A operação solicitada no XML está em desacordo com o cenário do registro na base do TAF"


  • Situação do Registro igual a "A" (Alterado):     

         - Não deve ser realizada a integração e no gerenciador deve aparecer a mensagem: 

           "A operação solicitada no XML está em desacordo com o cenário do registro na base do TAF";


  • Situação do Registro igual a "E" (Excluído):
         Registro já Transmitido ao RET:
              - Deve ser realizada a operação seguindo os conceitos citados em "Regras Gerais de Integração" 

                deste documento.

         Registro não transmitido ao RET:
             - Não deve ser realizada a integração e no gerenciador deve aparecer a mensagem:

              "A operação solicitada no XML está em desacordo com o cenário do registro na base do TAF" 

2. Realizando uma nova alteração no TAF:

  • Registro não existe no TAF:

         - Não deve ser realizada a integração e no gerenciador deve aparecer a mensagem: 

          "A operação solicitada no XML está em desacordo com o cenário do registro na base do TAF"


  • Situação do Registro igual a "I" (Incluído):     

         - Deve ser realizada a operação seguindo os conceitos citados em "Regras Gerais de Integração" deste documento.

  • Situação do Registro igual a "A" (Alterado):     
         - Deve ser realizada a operação seguindo os conceitos citados em "Regras Gerais de Integração" deste documento.

  • Situação do Registro igual a "E" (Excluído):
         Registro já Transmitido ao RET:

         - Não deve ser realizada a integração e no gerenciador deve aparecer a mensagem: 

    "A operação solicitada no XML está em desacordo com o cenário do registro na base do TAF"

         Registro não transmitido ao RET:

         - Deve ser realizada a operação seguindo os conceitos citados em "Regras Gerais de Integração" deste documento.

 

3. Realizando uma nova exclusão no TAF: 

  • Registro não existe no TAF:

         - Não deve ser realizada a integração e no gerenciador deve aparecer a mensagem: 

          "A operação solicitada no XML está em desacordo com o cenário do registro na base do TAF"


  • Situação do Registro igual a "I" (Incluído):     

         - Deve ser realizada a operação seguindo os conceitos citados em "Regras Gerais de Integração" deste documento.

  • Situação do Registro igual a "A" (Alterado):     
         - Deve ser realizada a operação seguindo os conceitos citados em "Regras Gerais de Integração" deste documento.

  • Situação do Registro igual a "E" (Excluído):
         Registro já Transmitido ao RET:

         - Não deve ser realizada a integração e no gerenciador deve aparecer a mensagem: 

    "A operação solicitada no XML está em desacordo com o cenário do registro na base do TAF"

         Registro não transmitido ao RET:

         - Não deve ser realizada a integração e no gerenciador deve aparecer a mensagem: 

    "A operação solicitada no XML está em desacordo com o cenário do registro na base do TAF"

4. Regras Gerais de Integração:

Quando o registro já existente no TAF não foi transmitido ao RET, ou seja, seu campo de Status é diferente de 2 ( Aguardando Retorno do Governo ) e 4 ( Autorizado pelo Governo ) a operação deve ser realizada normalmente na base de dados, caso já tenha sido enviado deve ser realizada a operação seguindo as regras abaixo:

Duplicar o registro, mantendo o atual e gerando uma nova linha na tabela com as regras abaixo

Último Recibo ( _PROTUL ) = O novo registro gerado deve ter esse campo vazio

Penúltimo Recibo ( _PROTPN ) = O novo registro deve ter nesse campo o valor do recibo do registro anterior com a mesma chave

Versão ( _VERSAO ) = O novo registro deve ter uma nova versão

Versão Anterior ( _VERANT ) = O novo registro deve ter o valor da versão do registro anterior com a mesma chave

Evento ( _EVENTO ) = O novo registro deve ter a operação que foi realizada

Ativo ( _ATIVO ) = O novo registro deve ter a situação igual a 1 ( Ativo ) e setar o registro anterior com a mesma chave para 2 ( Inativo ).


5. Complemento de dados ( integração multi ERP )

O TAF permite que diversos sistemas de origem realizem a integração de dados ao TAF, complementando informações de determinado evento na base de dados, inclusive quando se tratar do mesmo registro.

Exemplo: No cadastro de funcionário, um sistema X deseja incluir informações cadastrais e outro sistema Y deseja incluir informações do vínculo do empregado com o empregador. Neste caso, o sistema X deve enviar somente os campos (tags) relacionados ao conteúdo que deseja integrar ao TAF, e o sistema Y devem enviar somente os campos (tags) das informações do vínculo. Automaticamente os dados se complementam e tornam o registro na base de dados do TAF elegível para transmissão ao Governo.

Pontos de Atenção!

Esse comportamento é aplicado diante de algumas regras:

  • O complemento de informações enviados via integração é elegível apenas para dados de formulário, ou seja, informações do cabeçalho do Evento. Para informações de ocorrência 0:N, 1:N ou N:N essa regra não se aplica; para este tipo de registro, os dados serão sempre sobrepostos.
  • Para um campo (tag) não enviado, o dado é ignorado e a informação enviada em integração anterior é mantida. Para um campo (tag) enviado em branco, o dado é sempre considerado e a informação enviada em integração anterior é apagada.


6. Exclusão de Eventos (S-3000)

O TAF permite três modelos de integração para evento S-3000 do eSocial:


1 - Enviar o recibo do Evento na tag <nrRecEvt>

Caso o ERP possua em mãos o recibo do Evento, pode enviar ao TAF a exclusão através deste recibo.


2 - Enviar a chave do Evento na tag <nrRecEvt>

Quando a informação enviada dentro da tag <nrRecEvt> for a chave do registro ( e não o recibo ), deve existir o atributo tpOper onde deve ser informado o tipo de operação utilizado na exclusão do evento.
Opções:
U - Excluí o ultimo registro ( Apenas o Ativo )
Neste caso será excluído apenas o último registro ativo de acordo com a chave enviada.
T - Exclui todo o Histórico do Evento
Neste caso serão excluídos todos os registros relacionados a chave enviada, independente do status.

Exemplo: 
<nrRecEvt tpOper = “U”> Chave_do_evento </nrRecEvt>


3 - Enviar o TAFKEY do Evento na tag <nrRecEvt>

Basta enviar nesta tag o TAFKEY enviado na integração deste registro com o TAF.


Todas as opções são voltadas ao preenchimento da tag <nrRecEvt>. Todas as demais tags do evento devem ser preenchidas normalmente conforme Layout do eSocial.


Múltiplas Rúbricas

 Objetivo

 Integração do evento S-1010 (Rubricas) considerando o código identificador da tabela de rubricas no ERP origem.

Funcionamento 

Foi criado o cadastro Atualizações -> Cadastros eSocial -> Identificadores de Rubrica, onde é armazenado o código identificador da tabela enviado pelo ERP e gerado um código único e sequencial (ID). Esse código sequencial será utilizado pelo TAF na tag <ideTabRubr> do XML a ser transmitido ao RET .

 Isso possibilita a integração de rubricas onde o código identificador da tabela no ERP é maior que 8 caracteres, como previsto no manual do eSocial. 

 

Fila de Integração

 Objetivo

 Facilitar o gerenciamento de integração de Eventos para o software de origem dos dados, tornando o TAF responsável pelo armazenamento e reprocessamento de eventos.

Funcionamento

 De forma geral, o comportamento do TAF na integração de registros onde os eventos predecessores estão pendente de uma resposta do Governo, é rejeitá-los, garantindo assim a integridade dos dados dentro da base de dados.

 Contudo, para facilitar o gerenciamento destes eventos, o TAF permite ao ERP que envie esses eventos com a propriedade de Eventos de Fila. Desta forma, o TAF fica responsável por manter este evento em uma fila de integração, realizando tentativas de integração até que o evento predecessor tenha uma resposta definitiva do endpoint do Governo.

Como configurar a Fila de Integração?

Acesse Web Service REST - Integração e obtenha mais detalhes sobre a configuração da Fila de Integração no Serviço de Integração do TAF.

 Na prática, enquanto o evento predecessor estiver com status "Aguardando retorno", todas as tentativas de integração do registro geram um log e mantém este registro na fila de integração. Ao receber uma resposta do Governo, existem duas possibilidades:

  1. O Governo rejeita o evento predecessor: Neste caso o registro que está na fila de integração também é rejeitado pelo TAF para o ERP e é removido da fila de integração;
  2. O Governo autoriza o evento predecessor: Neste caso o registro que está na fila de integração é removido da fila de integração e há uma tentativa de integração no TAF. Ele pode ser aceito ou rejeitado, dependendo de sua estrutura.

 Exemplo: Existe na base de dados do TAF um registro de admissão ( S-2200 ) do funcionário A pendente de retorno do Governo. Neste momento, o ERP envia ao TAF um registro de Alteração Cadastral ( S-2205 ) do mesmo funcionário A. O evento S-2205 é colocado na fila de integração até que o evento S-2200 tenha uma resposta, e quando houver esse retorno por parte do Governo, o evento S-2205 entrará em um dos dois casos acima.


Imagem do Monitor de Integração ao tentar realizar diversas importação de um evento S-2205, que está aguardando uma resposta de evento predecessor S-2200.

 

Registros de log gerados pela Fila de Integração, onde após 3 tentativas de integração o evento predecessor foi rejeitado pelo Governo.