[PROJETO EM DESENVOLVIMENTO] Atenção! API ainda em desenvolvimento e portanto instável.
- eSocial-JT
- Introdução
- Guia rápido
- Visão geral da arquitetura da solução
- Características
- Configuração
- Instalação
- Configuração de serviços que usam certificado digital (assinatura de xml e envio para eSocial-Gov)
- 1. Instalação do esocial-jt-service e certificado no mesmo servidor
- 2. Instalação do esocial-jt-service sem certificado e usar serviços de outra instância do esocial-jt-service que possui um certificado
- 3. Instalação do esocial-jt-service sem certificado e usar serviços de outra aplicação que forneça api REST para assinatura e envio de lotes
- API Rest
- Sobre o projeto
- Dúvidas e contato
- Como contribuir
O eSocial-JT é o projeto que reúne as iniciativas do TST para atender às necessidades do sistema eSocial do Governo Federal. A solução foi desenvolvida em módulos auto contidos e independentes, que podem ser adaptados e utilizados em ambientes de qualquer organização, tanto pública quanto privada.
Em poucas palavras, o esocial-jt-service, módulo principal da solução, recebe um JSON com os dados de uma ocorrência dos sistemas de origem, tranforma em um evento do eSocial, cria e assina o arquivo XML, transmite para o eSocial-Gov e posteriormente consulta o resultado de processamento com eventuais erros.
Use este guia para obter rapidamente uma instância do esocial-jt-service em execução e enviar seu primeiro evento para o ambiente de Produção Restrita do eSocial-Gov.
- Git
- Docker
- Docker Compose
- Certificado Digital ICP-Brasil A1 válido (obrigatório mesmo para testes)
- Postman (opcional)
- Clone o projeto
$ git clone https://github.com/tst-labs/esocial.git
$ cd esocial
- Copie sua chave para a pasta
./configcom nomeesocial.pfx
$ cp local/da/chave/esocial.pfx ./config/esocial.pfx
- Copie o arquivo
./config/application.properties.examplepara./config/application.properties
$ cp ./config/application.properties.example ./config/application.properties
- Edite o arquivo de configuração
./config/application.propertiespara ficar de acordo com seu ambiente
esocialjt.cnpj-empregador=
esocialjt.ambiente=PRODUCAO_RESTRITA
esocialjt.arquivoCertificado=/config/esocial.pfx
esocialjt.senhaCertificado=
esocialjt.proxyServer=
esocialjt.proxyPort=
esocialjt.proxyUser=
esocialjt.proxyPassword=Obs.: Deixe em branco as configurações de
proxy, caso não se aplique
- Inicialize a aplicação com
docker-compose
docker-compose up
Obs.: O docker-compose sobe um banco postgres e a aplicação Java
- Verifique o log da aplicação se foi possível estabelecer comunicação com o eSocial-Gov
br.jus.tst.esocialjt.OnStartup : Testando conexão com eSocial...
br.jus.tst.esocialjt.OnStartup : Conexão com eSocial OK
- Verifique se a aplicação está no ar e se há comunicação com o eSocial-Gov acessando as urls
http://localhost:8080/esocial-jt-service/actuator/health
http://localhost:8080/esocial-jt-service/actuator/esocialhealth
-
Crie uma cópia do arquivo ./src/esocial-jt-service/src/main/resources/exemplos/informacoes_empregador.json
-
Edite com as informações referentes à instituição (o CNPJ deve ser o mesmo do proprietário do Certificado Digital)
-
Envie usando o método POST (via linha de comando ou Postman) para o endpoint:
http://localhost:8080/esocial-jt-service/ocorrencias
- Após alguns segundos, verifique o log da aplicação se o evento foi processado pelo eSocial-Gov
j.t.e.a.t.TarefaAtualizacaoProcessamento : Eventos processados: {PROCESSADO COM SUCESSO=1}
- Também é possível consultar o status fazendo uma requisição GET para o endpoint
http://localhost:8080/esocial-jt-service/ocorrencias
As demais seções deste documento fornecem mais detalhes sobre o funcionamento geral da solução, opções de instalação e configuração, API rest e guia de contribuição.
A figura abaixo ilustra uma visão geral arquitetura desta solução
- Sistemas de origem: São os sistemas de RH, Folha de Pagamentos e etc da instituição
- Conector: É o responsável por buscar os dados dos sistemas de origem, criar os arquivos json e enviar para o eSocial-JT. Cada instituição é responsável por criar seu conector da forma que lhe for mais conveniente, por exemplo, alterando os sistemas de origem para geração dos arquivos necessários ou utilizando ferramentas de ETL
- eSocial-JT: é o produto oferecido por este projeto e é o responsável por todo o ciclo de envio e consulta de processamento dos eventos enviados ao eSocial-Gov
- eSocial-Gov: aplicação do Governo Federal que recebe e processa os eventos do eSocial
Sendo assim, cada instituição deve:
- Instalar e configurar eSocial-JT (esocial-jt-service) em seu ambiente
- Criar seu Conector responsável por ler os dados de origem e enviar para o eSocial-JT em formato json
O projeto é dividido nos seguintes módulos:
- esocial-comunicacao: Pacote de mapeamento dos serviços do WSDL.
- esocial-esquemas: Schemas XSD do eSocial-GOV.
- esocial-jt-dominio: Modelos básicos do esocial-jt.
- esocial-jt-service: API RESTful para comunicação com eSocial-GOV. [mais informações...]
O esocial-jt-service, módulo principal eSocial-JT, foi construído em Java 8 utilizando o framework Spring Boot. É uma aplicação primordialmente de backend que fornece API RESTful trafegando dados no formato JSON.
Quando está em execução, o esocial-jt-service
- Recebe dados de uma ocorrência* no endpoint
POST/esocial-jt-service/ocorrencias - A cada 10 segundos verifica as ocorrências recebidas, gera os eventos e envia ao eSocial-Gov
- No próximo ciclo de 10 segundos consulta o resultado do processamento dos eventos enviados
- Além disso, fornece API para consulta do estado interno da aplicação.
Obs. 1: para não confundir os conceitos, os dados recebidos pelo esocial-jt-service são chamados de "ocorrencia" enquanto que os XMLs que são enviados para o eSocial-Gov são chamados de "eventos".
Obs. 2: Cada instituição deve alterar seus sitemas de origem (RH, Folha, etc) ou criar um conector para extrair os dados e enviar no formato JSON para o esocial-jt-service.
Obs. 3: O intervalo de 10 segundos pode ser alterado ou mesmo desabilitado via configuração
Obs. 4: Modelos dos arquivos json podem ser encontrados na pasta do projeto ./src/esocial-jt-service/src/main/resources/exemplos ou no endpoint
GET/esocial-jt-service/ocorrencias/exemplos
O esocial-jt-service é uma aplicação Spring Boot, portanto, é possível sobreescrever os parâmetros de configuração por qualquer método disponibiliado pelo framework. As formas mais recomendadas para este projeto são:
- Criação de arquivo
application.propertiesno subdiretório/configrelativo ao diretório de execução - Criação de arquivo
application.propertiesno diretório de execução - Variáveis de ambiente do Sistema Operacional ou Container
- Argumentos de linha de comando
- Alterando o
src/main/resources/application.propertiesdo projeto./src/esocial-jt-service(requer recompilação)
Obs. 1: Os métodos de configuração podem ser combinados entre si, observando-se a ordem de precedência
Obs. 2: A instalação em container utiliza uma adaptação da primeira abordagem
As configurações padrão estão disponíveis no arquivo src/main/resources/application.properties do projeto ./src/esocial-jt-service.
Obs.: Use esse arquivo como referência em caso de dúvidas sobre a configuração.
esocialjt.cnpj-empregador=
esocialjt.arquivoCertificado=
esocialjt.senhaCertificado=Obs.: é possível configurar serviços externos de assinatura e envio, fazendo que não seja necessário o uso de um certificado local (ver seções mais adiante)
#Define o ambiente para envio ao eSocial-Gov entre PRODUCAO e PRODUCAO_RESTRITA
esocialjt.ambiente=PRODUCAO_RESTRITA
#Periodo, em milissegundos, entre cada envio/consulta ao eSocial-Gov. 0 (zero) para desabilitar
esocialjt.periodoAutoMilis=10000
#Quantidade maxima de eventos por lote, entre 1 e 50
esocialjt.limite-eventos-por-lote=50
#Preencha caso queira usar servicos externos, assim nao ha necessidade de ter um certificado local
#Uma instalacao padrao fornece os servicos nos endpoints abaixo (aponte, por exemplo, para uma instalacao em homologacao)
esocialjt.urlServicoConsultaProcessamento=http://localhost:8080/esocial-jt-service/lote/consulta/
esocialjt.urlServicoEnvioLote=http://localhost:8080/esocial-jt-service/lote/acoes/enviar/
esocialjt.urlServicoAssinatura=http://localhost:8080/esocial-jt-service/xml/acoes/assinar/
#Preencha caso o certificado do transmisssor seja diferente do empregador a ser cadastrado no evento S1000.
#Ou seja, sera usado um certificado de uma Pessoa Fisica para envio dos eventos.
esocialjt.tpInscIdeTransmissor=2
esocialjt.nrInscIdeTransmissor= cpf do transmisssor
#Database - configuracao de banco de dados
spring.datasource.url=jdbc:postgresql://esocial-db/postgres
spring.datasource.username=postgres
spring.datasource.password=esocial
#Flyway - habilita ou desabilita a criacao automatica dos esquemas de banco de dados
spring.flyway.enabled=true
Documentação oficial do spring-boot
A forma mais direta de instalação é via docker-compose (ver Guia rápido). Abaixo são listadas outras opções de instalação.
Atualmente, o esocial-jt-service é testado com PostgreSQL mas em teoria é compatível com outros bancos. Os parâmetros de conexão devem ser passados no arquivo de configuração.
spring.datasource.url=
spring.datasource.username=
spring.datasource.password=Execute a aplicação com a configuração abaixo habilitada:
spring.flyway.enabled=trueObs.: É necessário que o usuário de banco de dados da aplicação tenha permissão para criação e alteração do esquema
- Desabilite o flyway
spring.flyway.enabled=false- Execute os scripts de criação do banco, localizados em src/esocial-jt-service/src/main/resources/db/migration/.
- Crie uma pasta contendo os arquivos
application.propertieseesocial.pfx - Execute o docker mapeando a pasta criada para a pasta
/configdo container
docker run -p "8080:8080" -v "/pasta/de/configuracao:/config" tstlabs/esocial-jt-service:latest
- JDK 8;
- Maven 3.3.9 (ou superior);
- Git 2.15.0 (ou superior);
- Clone o projeto
git clone https://github.com/tst-labs/esocial.git
- Faça build da aplicação Java utilizando o Maven
cd esocial/src
mvn clean install
-
Crie o arquivo
application.propertiescom as devidas configurações na pastasrc/esocial-jt-service/target. Não esquecer de indicar o caminho para o arquivo.pfxdo certificado digital. -
Execute a aplicação
java -jar ./src/esocial-jt-service/target/esocial-jt-service*.jar
- JDK 8;
- Maven 3.3.9 (ou superior);
- Git 2.15.0 (ou superior);
- Servidor de aplicação
- Clone o projeto
git clone https://github.com/tst-labs/esocial.git
- Faça build da aplicação Java utilizando o Maven com o perfil
war
cd esocial/src
mvn clean install -Pwar
- Configurar o servidor de aplicação e implantar o
war.
Para comunicação com o eSocial-Gov, é necessário um certificado digital válido, mesmo para o ambiente de Produção Restrita. Para flexibilizar o uso do certificado, o esocial-jt-service permite três configurações para essa funcionalidade:
- Instalação do esocial-jt-service e certificado no mesmo servidor
- Instalação do esocial-jt-service sem certificado e usar serviços de outra instância do esocial-jt-service que possui um certificado
- Instalação do esocial-jt-service sem certificado e usar serviços de outra aplicação que forneça api REST para assinatura e envio de lotes
Nesta configuração, o arquivo do certificado A1 deverá ficar disponível no sistema de arquivos da máquina que executa o esocial-jt-service. O caminho para o arquivo e a senha de acesso são passados no arquivo de configuração.
Exemplo de uso:
- Instalação em ambiente de homologação ou produção
- Instalação na máquina do desenvolvedor, desde que este tenha acesso ao arquivo do certificado digital e à senha.
Configuração:
esocialjt.arquivoCertificado=/path/to/certificado.pfx
esocialjt.senhaCertificado=senh@Obs.: as propriedades esocialjt.urlServicoEnvioLote, esocialjt.urlServicoConsultaProcessamento e esocialjt.urlServicoAssinatura não devem ser preenchidas neste caso.
2. Instalação do esocial-jt-service sem certificado e usar serviços de outra instância do esocial-jt-service que possui um certificado
Nesta configuração, uma instalação do esocial-jt-service manterá o arquivo e senha do certificado digital utilizando a configuração anterior. Outras instalações do esocial-jt-service poderão usar a api REST da primeira para fazer uso de serviços que necessitam de certificado digital.
Exemplo de uso:
- Uma instalação do esocial-jt-service, com certificado digital e senha, ficará disponível em ambiente controlado pela equipe de infraestrutura enquanto desenvolvedores configuram instalações locais para utilizar esse ambiente. O desenvolvedor não precisará ter acesso ao arquivo do certificado digital e à senha.
Configuração:
Supondo que a instalação do esocial-jt-service com certificado digital esteja disponível em 10.0.0.100 na porta 8080, as demais instalações devem fazer a seguinte configuração:
esocialjt.urlServicoConsultaProcessamento=http://10.0.0.100:8080/esocial-jt-service/lote/consulta/
esocialjt.urlServicoEnvioLote=http://10.0.0.100:8080/esocial-jt-service/lote/acoes/enviar/
esocialjt.urlServicoAssinatura=http://10.0.0.100:8080/esocial-jt-service/xml/acoes/assinar/3. Instalação do esocial-jt-service sem certificado e usar serviços de outra aplicação que forneça api REST para assinatura e envio de lotes
Dado que o esocial-jt-service usa os serviços da configuração anterior por meio de uma api REST, é possível criar um serviço independente para as mesmas funcionalidades, desde que atenda aos critérios estabelecido pelo eSocial-Gov. Tal serviço independente não é parte desta solução, cabendo a cada instiuição elaborar da forma que achar mais conveniente.
Exemplo de uso:
- A instituição cria uma aplicação (em Java, Javascript, PHP, etc) que disponibiliza uma api REST que assina um arquivo XML de evento usando seu certificado digital. Esta aplicação também recebe um XML de um lote e envia ao eSocial-Gov usando o protocolo HTTPS. Da mesma forma, a aplicação permite a consulta do resultado do processamento a partir de um número de protocolo. Assim, todas instalações do esocial-jt-service usarão esse serviço.
Configuração:
Supondo que a aplicação esteja disponível em 10.0.0.100 na porta 8080, as instalações do esocial-jt-service devem fazer a seguinte configuração:
esocialjt.urlServicoConsultaProcessamento=http://10.0.0.100:8080/consulta/
esocialjt.urlServicoEnvioLote=http://10.0.0.100:8080/enviar/
esocialjt.urlServicoAssinatura=http://10.0.0.100:8080/assinar/Relacionado ao recebimento ou consulta de ocorrências
- Receber ocorrência:
POST/esocial-jt-service/ocorrencias - Consultar todas ocorrências:
GET/esocial-jt-service/ocorrencias - Consultar ocorrência por ID:
GET/esocial-jt-service/ocorrencias/{id} - Consultar dados básicos das ocorrências:
GET/esocial-jt-service/ocorrencias/dados-basicos - Consultar exemplos de JSON de ocorrências:
GET/esocial-jt-service/ocorrencias/exemplos - Consultar exemplo de JSON de um tipo:
GET/esocial-jt-service/ocorrencias/exemplos/{tipo}
Serve para forçar um reenvio de um evento para o eSocial-Gov
- Enviar evento:
POST/esocial-jt-service/eventos/acoes/enviar
Controle manual da consulta do processamento no eSocial-Gov. Não precisa ser executado se a atualização automática está ativada.
- Consulta protocolo:
GET/esocial-jt-service/lote/consulta/{protocolo} - Atualiza todos lotes pendentes:
POST/esocial-jt-service/lote/acoes/atualizar-processamento - Atualiza lote por protcolo:
POST/esocial-jt-service/lote/acoes/atualizar-processamento/{protocolo} - Enviar lote para o eSocial-Gov:
POST/esocial-jt-service/lote/acoes/enviar/
Disponibiliza o serviço de assinatura de xml para uso por outra aplicação.
- Assinar xml:
POST/esocial-jt-service/xml/acoes/assinar/
Comandos exclusivos para o ambiente de produção restrita
- Limpar produção restrita:
POST/esocial-jt-service/producao-restrita/acoes/limpar
Controla, em tempo de execução, se a aplicação deve ou não executar tarefas automaticamente (envio para o eSocial-Gov, consulta do processamento, etc) . Também pode ser configurado no arquivo application.properties.
- Consultar status:
GET/esocial-jt-service/automacao - Configurar automação:
POST/esocial-jt-service/automacao
Verifica o status da aplicação
- Status da aplicação:
GET/esocial-jt-service/actuator/health - Informações sobre a aplicação:
GET/esocial-jt-service/actuator/info - Status da comunicação com eSocial-Gov:
GET/esocial-jt-service/actuator/esocialhealth
O Tribunal Superior do Trabalho está em uma fase avançada de desenvolvimento de uma solução para transmitir os dados da vida funcional dos seus servidores para o sistema eSocial do Governo Federal, atendendo às necessidades legais do Decreto N° 8.373, de 11 de Dezembro de 2014.
Essa iniciativa converge na publicação desse trabalho como projeto Open Source (OSS), uma vez que entendemos que essa solução pode ser reusada, trazendo economia de esforços em quaisquer entidades públicas ou privadas.
Esse pedaço da solução compreende:
- Recepção de ocorrências provenientes dos sistemas de origem, via API RESTful;
- Conversão dessas ocorrências em eventos do eSocial, no formato XML;
- Consulta do resultado do processamento dos eventos enviados; e
- Gerência dos detalhes de conexão com o eSocial-GOV (assinatura dos eventos, conexão com certificado, etc.).
Não tratamos nesse projeto de:
- Extração e/ou transformação de dados dos sistemas finalísticos das organizações usuárias;
- Manipulação de qualquer forma que seja dos dados recebidos; e
- Validação semântica dos dados recebidos.
Atualmente, o sistema já é capaz de receber dados de grande parte dos eventos, transmitir de forma automática para o eSocial-GOV e exibir o resultado do processamento (sucesso ou mensagens de erro).
A priorização dos eventos a serem transmitidos foi feita com base na necessidade atual do TST e demais órgãos da Justiça do Trabalho. No entanto, o projeto pode ser estendido para quaisquer tipos de eventos especificados pelo eSocial-GOV.
Pacote de esquemas : 2.5
Pacote de comunicação : 1.5
| Evento | Nome Evento | Versão | Situação | Resultado do envio para a produção restrita |
|---|---|---|---|---|
| S-1000 | Empregador/Contribuinte | 2.5 | Feito | Processado com sucesso |
| S-1005 | Estabelecimentos | 2.5 | Feito | Processado com sucesso |
| S-1010 | Rubricas | 2.5 | Feito | Processado com sucesso |
| S-1020 | Lotações Tributárias | 2.5 | Feito | Processado com sucesso |
| S-1030 | Cargos/Empregos Públicos | 2.5 | Feito | Processado com sucesso |
| S-1035 | Carreiras Públicas | 2.5 | Feito | Processado com sucesso |
| S-1040 | Funções/Cargos em Comissão | 2.5 | Feito | Processado com sucesso |
| S-1050 | Horários/Turnos de Trabalho | 2.5 | Feito | Processado com sucesso |
| S-1060 | Ambientes de Trabalho | 2.5 | Feito | Processado com sucesso |
| S-1070 | Processos Administrativos/Judiciais | 2.5 | Feito | Processado com sucesso |
| S-1080 | Operadores Portuários | 2.5 | NA | NA |
| Evento | Nome Evento | Versão | Situação | Resultado do envio para a produção restrita |
|---|---|---|---|---|
| S-1200 | Remuneração de trabalhador vinculado ao Regime Geral de Previdência Social | 2.5 | Feito | Processado com sucesso |
| S-1202 | Remuneração de servidor vinculado a Regime Próprio de Previdência Social – RPPS | 2.5 | Feito | Evento não reconhecido pelo eSocial-GOV |
| S-1207 | Benefícios previdenciários - RPPS | 2.5 | Feito | Evento não reconhecido pelo eSocial-GOV |
| S-1210 | Pagamentos de Rendimentos do Trabalho | 2.5 | Feito | Processado com sucesso |
| S-1250 | Aquisição de Produção Rural | 2.5 | NA | NA |
| S-1260 | Comercialização da Produção Rural Pessoa Física | 2.5 | NA | NA |
| S-1270 | Contratação de Trabalhadores Avulsos Não Portuários | 2.5 | NA | NA |
| S-1280 | Informações Complementares aos Eventos Periódicos | 2.5 | NA | NA |
| S-1295 | Solicitação de Totalização para Pagamento em Contingência | 2.5 | Feito | Processado com sucesso |
| S-1298 | Reabertura dos Eventos Periódicos | 2.5 | Feito | Processado com sucesso |
| S-1299 | Fechamento dos Eventos Periódicos | 2.5 | Feito | Processado com sucesso |
| S-1300 | Contribuição Sindical Patronal | 2.5 | NA | NA |
| Evento | Nome Evento | Versão | Situação | Resultado do envio para a produção restrita |
|---|---|---|---|---|
| S-2190 | Admissão de Trabalhador - Registro Preliminar | 2.5 | NA | NA |
| S-2200 | Cadastramento Inicial do Vínculo e Admissão/Ingresso de Trabalhador | 2.5 | Feito | Processado com sucesso |
| S-2205 | Alteração de Dados Cadastrais do Trabalhador | 2.5 | Feito | Processado com sucesso |
| S-2206 | Alteração de Contrato de Trabalho | 2.5 | Feito | Processado com sucesso |
| S-2210 | Comunicação de Acidente de Trabalho | 2.5 | Impl. futura | |
| S-2220 | Monitoramento da Saúde do Trabalhador | 2.5 | Impl. futura | |
| S-2230 | Afastamento Temporário | 2.5 | Feito | Processado com sucesso |
| S-2240 | Condições Ambientais do Trabalho - Fatores de Risco | 2.5 | Impl. futura | |
| S-2241 | Insalubridade, Periculosidade e Aposentadoria Especial | 2.5 | Impl. futura | |
| S-2250 | Aviso Prévio | 2.5 | NA | NA |
| S-2260 | Convocação para Trabalho Intermitente | 2.5 | NA | NA |
| S-2298 | Reintegração | 2.5 | Feito | Processado com sucesso |
| S-2299 | Desligamento | 2.5 | Feito | Processado com sucesso |
| S-2300 | Trabalhador Sem Vínculo de Emprego/Estatutário - Início | 2.5 | Feito | Processado com sucesso |
| S-2306 | Trabalhador Sem Vínculo de Emprego/Estatutário - Alteração Contratual | 2.5 | Feito | Processado com sucesso |
| S-2399 | Trabalhador Sem Vínculo de Emprego/Estatutário - Término | 2.5 | Feito | Processado com sucesso |
| S-2400 | Cadastro de Benefícios Previdenciários - RPPS | 2.5 | Feito | Evento não reconhecido pelo eSocial-GOV |
| S-3000 | Exclusão de eventos | 2.5 | Feito | Processado com sucesso |
| S-5001 | Informações das contribuições sociais por trabalhador | 2.5 | Feito | Evento totalizador gravado no formato XML |
| S-5002 | Imposto de Renda Retido na Fonte | 2.5 | Feito | Evento totalizador gravado no formato XML |
| S-5011 | Informações das contribuições sociais consolidadas por contribuinte | 2.5 | Feito | Evento totalizador gravado no formato XML |
| S-5012 | Informações do IRRF consolidadas por contribuinte | 2.5 | Feito | Evento totalizador gravado no formato XML |
Em caso de dúvidas, crie uma issue neste projeto para que se inicie uma discussão com os membros da equipe e demais usuários da aplicação.
Leia nosso guia de contribuição em andamento.