INTEGRAÇÃO EsocialBranches - Consulta de Eventos

Contexto de negócio (Introdução)

Cada vez mais o mercado exige que as operações complexas e manipulação de dados sejam ainda mais ágeis e intuitivas. Neste contexto, surgiu a necessidade da criação de uma interface que possibilite automatizar o envio dos dados das empresas para o governo,de forma rápida, clara e sem que o cliente necessite adquirir um módulo adicional do sistema. Desta forma, o desenvolvimento de um Monitor de Eventos foi necessário para a entrega das obrigações fiscais das empresas para o governo, de modo que as informações que trafegam nele possam ser enviadas em lotes de eventos e depois consultados através de relatórios específicos para cada tipo de serviço.

A utilização do Middleware, como interface de comunicação, possibilitou maior segurança e velocidade de acesso às informações, já que se utilizam de APIs REST na troca de dados. O novo visual do Monitor THF também foi outro passo importante na questão da usabilidade do cliente, que passou a realizar o envio dos eventos fiscais com um número menor de passos e de forma mais intuitiva.

De modo geral, o eSocial do futuro simplifica os processos de seus clientes, em relação ao cumprimento de suas obrigações fiscais, o tornando mais seguro, simples e rápido.

Maiores informações podem ser acessas em: https://tdn.totvs.com/x/oaT9Hw.


Sistemas Envolvidos

  • Protheus - SIGAGPE (Gestão de Pessoal): Módulo responsável pela gestão dos dados dos funcionários, folha de pagamento e dentre outros cadastros pertinentes aos colaboradores.


Integração

O objetivo desta integração é permitir que o Monitor THF, consiga listar os eventos cadastrados pelo usuário no Protheus.

  • Arquitetura (Tecnologia)
    • A integração no Protheus é feita por intermédio de comunicação direta com os Web Services REST (Representation State Transfer) utilizando o formato JSON (JavaScript Object Notation) de serialização de dados, e que através da ativação do serviço do REST do Protheus esteja disponível para utilizar o serviço.
  • Premissas e Propriedades
    • O requerente da API será responsável pela requisição e transformação da informação recebida;
    • Será implementado um controle de paginação a fim de facilitar o envio da informação para o solicitante. Neste processo o solicitante deverá informar qual é o tamanho da informação solicitada e qual página ela solicita;
    • Cabe a integração informar se existem mais páginas a serem solicitadas.


Escopo

Por intermédio desta integração será disponibilizada a seguinte funcionalidade:

  • Consulta de Eventos;


Fora do escopo

  • Automatização de Cadastramento de Eventos.
  • O serviço de disponibilização de dados de Eventos apenas retorna os dados solicitados, não cabendo à API tratar a informação depois de ser entregue ao solicitante;

Pré-requisitos instalação/implantação/utilização

  • Versões mínima do Protheus: 12.1.25;
  • Possuir acesso à Internet, caso o sistema que venha a utilizar a integração com a aplicação Protheus que faça uso da mesma;
  • Estrutura de rede estável, para que haja trafego de dados sem interrupção;
  • Protheus devidamente configurado e serviço Rest habilitado em seu server;
  • Binário Lobo Guará;
  • Certificado Digital Configurado, de acordo com a documentação: https://tdn.totvs.com/x/dau2Hg.
  • Configuração dos parâmetros utilizados pelo Monitor THF, disponível na documentação: https://tdn.totvs.com/x/TIp-Hw.


Ativação/Desativação da integração

Para utilizar a integração será necessário realizar a devida configuração do Webservice Rest no Protheus, com o formato apresentado na seguinte documentação: Exemplo de Configuração de Webservice REST.

Controle de Ambiente

Exige que os seguintes pontos sejam revisados:

  • Protheus com sua arquitetura devidamente estruturada;
  • Módulo Gestão de Pessoal configurado com os parâmetros do eSocial.

Controle de Versão

O grupo TOTVS, representado por suas marcas, irá administrar as demandas de evolução dos leiautes e demais ajustes, acordando junto aos solicitantes o prazo de liberação de release.

Todas as evoluções programadas deverão ser discutidas e aprovadas pelas áreas antes do início do desenvolvimento e somente serão desenvolvidas em caso de concordância das áreas e alinhamento com as diretivas definidas pelo contrato de Integração.

Suporte

O suporte aos recursos da Integração será de responsabilidade da linha MicroSiga Protheus, onde será analisada pela equipe de suporte da TOTVS.

Fluxo das Informações

Esta integração traz a funcionalidade exclusivamente de consulta de eventos do eSocial.

Cadastro

Esta integração contempla apenas a consulta e envio dos dados de Eventos.

Processos

O Monitor THF realizará o consumo da API com dados básicos que serão utilizados como parâmetros para consultar a base de eventos do eSocial e retornar um conjunto de informações para o requisitante.

Limitações / Restrições Gerais

  • A integração não contemplará inclusão, alteração ou exclusão de registros no Protheus, para isso o usuário deverá acessar o ERP e efetuar as devidas ações manualmente.


Como realizar a chamada da API REST

Para realizar a integração é necessário informar informações básicas de consulta para o retorno dos eventos, são elas:

  • Preenchimento do EndPoint da API EsocialEvents;
  • Utilizar a chamada do método GET com o preenchimento dos parâmetros obrigatórios da API.

Formatos de Data

As Entradas e Saídas de dados tipo data (Date) acompanham o formato padrão YYYY-MM-DDThh:mm


Parâmetros

Para o método GET não é necessário informar nenhum parâmetro para essa API, pois todos os eventos serão retornados.


Definições da API:

Parâmetros e Chamada do Método:

Para a realização de testes foi utilizado a ferramenta POSTMAN e após a configuração do server Protheus com o serviço API Rest, a  requisição deverá ser semelhante a imagem abaixo:

Estrutura: { protocolo } : // { endereço servidor Rest } : { Porta Rest } / rest / api / rh / { versão } / EsocialEvents /

Exemplo: http://localhost:8060/rest/api/rh/esocial/v1/EsocialEvents/


Retorno da API:

{
  	 "items": [
        {
            "eventCode": "S-1000",
            "eventDescription": "Informações do Empregador/Contribuinte/Órgão Público"
        },
        {
            "eventCode": "S-1005",
            "eventDescription": "Tabela de Estabelecimentos, Obras ou Unidades de Órgãos Públicos"
        },
        {
            "eventCode": "S-1010",
            "eventDescription": "Tabela de Rubricas"
        },
        {
            "eventCode": "S-1020",
            "eventDescription": "Tabela de Lotações Tributárias"
        },
        {
            "eventCode": "S-1030",
            "eventDescription": "Tabela de Cargos/Empregos Públicos"
        },
        {
            "eventCode": "S-1035",
            "eventDescription": "Tabela de Carreiras Públicas"
        },
        {
            "eventCode": "S-1040",
            "eventDescription": "Tabela de Funções/Cargos em Comissão"
        },
        {
            "eventCode": "S-1050",
            "eventDescription": "Tabela de Horários/Turnos de Trabalho"
        },
        {
            "eventCode": "S-1060",
            "eventDescription": "Tabela de Ambientes de Trabalho"
        },
        {
            "eventCode": "S-1070",
            "eventDescription": "Tabela de Processos Administrativos/Judiciais"
        },
        {
            "eventCode": "S-1200",
            "eventDescription": "Remuneração de trabalhador vinculado ao Regime Geral de Previd. Social"
        },
        {
            "eventCode": "S-1210",
            "eventDescription": "Pagamentos de Rendimentos do Trabalho"
        },
        {
            "eventCode": "S-1280",
            "eventDescription": "Informações Complementares aos Eventos Periódicos"
        },
        {
            "eventCode": "S-1295",
            "eventDescription": "Solicitação de Totalização para Pagamento em Contingência"
        },
        {
            "eventCode": "S-1298",
            "eventDescription": "Reabertura dos Eventos Periódicos"
        },
        {
            "eventCode": "S-1299",
            "eventDescription": "Fechamento dos Eventos Periódicos"
        },
        {
            "eventCode": "S-1300",
            "eventDescription": "Contribuição Sindical Patronal"
        },
        {
            "eventCode": "S-2190",
            "eventDescription": "Admissão de Trabalhador - Registro Preliminar"
        },
        {
            "eventCode": "S-2200",
            "eventDescription": "Cadastramento Inicial do Vínculo e Admissão/Ingresso de Trabalhador"
        },
        {
            "eventCode": "S-2205",
            "eventDescription": "Alteração de Dados Cadastrais do Trabalhador"
        },
        {
            "eventCode": "S-2206",
            "eventDescription": "Alteração de Contrato de Trabalho"
        },
        {
            "eventCode": "S-2210",
            "eventDescription": "Comunicação de Acidente de Trabalho"
        },
        {
            "eventCode": "S-2220",
            "eventDescription": "Monitoramento da Saúde do Trabalhador"
        },
        {
            "eventCode": "S-2230",
            "eventDescription": "Afastamento Temporário"
        },
        {
            "eventCode": "S-2250",
            "eventDescription": "Aviso Prévio"
        },
        {
            "eventCode": "S-2260",
            "eventDescription": "Convocação para Trabalho Intermitente"
        },
        {
            "eventCode": "S-2298",
            "eventDescription": "Reintegração"
        },
        {
            "eventCode": "S-2299",
            "eventDescription": "Desligamento"
        },
        {
            "eventCode": "S-2300",
            "eventDescription": "Trabalhador Sem Vínculo de Emprego/Estatutário - InícioS"
        },
        {
            "eventCode": "S-2306",
            "eventDescription": "Trabalhador Sem Vínculo de Emprego/Estatutário - Alteração Contratual"
        },
        {
            "eventCode": "S-2399",
            "eventDescription": "Trabalhador Sem Vínculo de Emprego/Estatutário - Término"
        },
        {
            "eventCode": "S-3000",
            "eventDescription": "Exclusão de eventos"
        }
    ]
}


Informações das propriedades de retorno da API:

PROPRIEDADES API RESTDESCRIÇÃO

eventCode

Código do Evento no eSocial

eventDescription

Descrição do Evento


Checklist de suporte da aplicação

Itens a serem verificados durante o atendimento:

  • Verificar se os pré-requisitos foram atendidos para a chamada da API;
  • Verificar se na chamada da API o EndPoint, o nome do serviço e todos os campos obrigatórios foram informados;
  • Verificar se o retorno da API apresenta algum erro tratado (códigos e mensagens de erro citados neste documento) e consultar a solução na mesma tabela que descreve o erro;
  • Em caso de Erro não tratado, verificar se possui alguma informação de banco de dados, conexão com o servidor ou algo que possa identificar a origem do problema.


Anexos