📘 Integrações

O módulo Integrações é o painel de acionamento manual das trocas de dados entre o WebFoPag e os sistemas externos que dependem da folha. Quase tudo o que ele faz também acontece de forma automática, em rotina; a razão de existir das telas é permitir que uma pessoa dispare de novo um envio específico — para um empregado, um lote ou uma competência — quando a rotina falhou, quando um dado foi corrigido depois do envio, ou quando o destino precisa reprocessar.

Por isso os rótulos do menu trazem a expressão “Integração Manual” na maioria dos itens. O módulo não define as regras de negócio de cada destino: ele seleciona o público, monta o pacote e entrega ao mecanismo de transporte de cada integração.

A característica que mais define o módulo é que cada integração fala com o seu destino por um transporte diferente. Não existe um mecanismo único: há chamada de API REST com upload para blob, há publicação em fila de mensagens, há SQL direto sobre as tabelas do eSocial e há geração de planilha. Entender o módulo é entender esse mapa de transportes, porque ele determina onde o problema aparece quando um envio falha.

A segunda característica é que o recorte do público é o que as telas têm em comum. Boa parte delas monta uma seleção de empregados e autônomos por filial, contrato, departamento ou centro de resultado, e o comportamento muda conforme o tipo de estrutura gerencial da empresa logada: quando a empresa trabalha por centro de resultado, os campos de contrato e departamento saem de cena e o centro de resultado entra; caso contrário, ocorre o inverso.

A terceira é que o rastreamento é por evento, não por lote. Na integração de EPays, cada envio grava uma linha própria com um identificador único, a origem que disparou a integração, o usuário responsável e o status da atividade — o que permite auditar um empregado específico em vez de só saber que “o lote rodou”.

📄 1 - Submenus

• Integração Pessoa Física Envio manual dos dados cadastrais de pessoa física para o eSocial, com seleção de registros e marcação de deficiência. ⤷ Saiba Mais

• Reprocessar Ponto Reprocessamento da integração de ponto, acionado pelo integrador do Pontofopag. ⤷ Saiba Mais

• Integração Manual Connect eSocial Integração manual de eventos do eSocial para empregados e autônomos, com seleção do evento e da competência. ⤷ Saiba Mais

• Integração Manual Epays Envio manual de registros de empregado e de documentos para a plataforma EPays, com rastreamento por envio. ⤷ Saiba Mais

• Integração Manual Medicina Publicação manual de eventos para o sistema de medicina ocupacional, por seleção de empregados. ⤷ Saiba Mais

As telas de Integração Empréstimo eConsignado (IntegracaoEmprestimoConsignado.aspx) e de Integração Manual - Meu Workflow (IntegracaoMeuWorkFlow.aspx) integram o mesmo menu e estão descritas nas seções técnicas abaixo, mas ainda não têm página funcional própria; serão incluídas nesta lista quando a redação for concluída.

[!NOTE] As cinco páginas listadas acima existem, porém ainda estão marcadas como Aguardando desenvolvimento — a redação funcional de cada uma ainda não começou.

🔍 2 - Visão Técnica

As sete telas do módulo são páginas ASP.NET WebForms que herdam de BasePageWebFoPag, todas em Employer.Plataforma.Web.WebFoPag. O agrupamento é dado pelo bloco MenuArvoreIntegracoes de MenuMaisOpcoes.aspx, que é a definição autoritativa de quais telas pertencem ao módulo.

O que diferencia cada uma é o destino e o transporte:

Alguns comportamentos ajudam a entender o módulo:

• Três famílias de transporte, não uma. Fila de mensagens em Medicina e Meu Workflow; API REST em EPays; acesso direto às tabelas do eSocial em Conect. Quando um envio falha, o lugar onde investigar muda conforme a família: fila parada, erro HTTP da API, ou dado ausente na tabela de origem.
• A EPays autentica por parâmetro específico da empresa. O token é obtido em /api/auth/usuario com as credenciais guardadas nos parâmetros UsuarioAPIEPAYS e SenhaAPIEPAYS, recuperados por empresa. Ou seja, a credencial é por cliente, não global.
• O arquivo da EPays não vai pela mesma chamada. Depois de autenticar, o sistema pede um endereço de blob em api/blob e envia o conteúdo com PUT, marcando o cabeçalho de tipo de blob. O protocolo TLS é fixado explicitamente antes do envio.
• O evento do eSocial determina os campos da tela. Eventos de remuneração e de pagamento exigem mês e ano de competência; eventos de admissão e de desligamento não. A tela mostra ou esconde o período conforme o evento selecionado.
• A competência 13 tem caminho próprio. Na integração do Conect, informar mês 13 troca a consulta: em vez de buscar a remuneração pelo período de cálculo, a rotina busca pelos holerites do tipo de folha correspondente ao décimo terceiro dentro do ano informado.
• Autônomos entram por CPF, não por matrícula. A consulta de remuneração une o autônomo à tabela de pessoa física e casa o registro do eSocial pelo CPF, exigindo que a matrícula esteja ausente — é o que separa o autônomo do empregado dentro da mesma estrutura.
• A estrutura gerencial muda a tela. Empresas que trabalham por centro de resultado escondem contrato e departamento; as demais escondem centro de resultado. O padrão se repete em mais de uma tela do módulo.
• O rastreamento da EPays é por envio. Cada integração grava identificador único, origem, usuário, status e data de execução, permitindo auditar o histórico de um empregado específico.

2.1 🧾 Banco de Dados

Estrutura das Tabelas

• employer.TAB_Integracao_Epays_Rastreamento: histórico de envios para a EPays. Colunas mapeadas na BLL: Idf_Integracao_Epays_Rastreamento (chave), Idf_Empregado, Des_Guid_Rastreamento (identificador único do envio), Des_Origem_Integracao (até 100 caracteres), Dta_Cadastro, Idf_Usuario, Idf_Status_Atividade e Dta_Execucao.
• employer.ESO_Remuneracao: remuneração no formato do eSocial, base dos eventos de remuneração. É unida ao empregado, ao holerite e ao período de cálculo, e é a partir dela que a integração do Conect monta o conjunto de eventos.
• employer.ESO_Remuneracao_Outras_Empresas, employer.ESO_Remuneracao_Beneficio e employer.ESO_Remuneracao_Beneficio_Dependente: desdobramentos da remuneração do eSocial, removidos e recompostos durante a reintegração manual de um evento.
• employer.TAB_Holerite: holerite do empregado, usado para localizar a remuneração da competência e para o caminho específico do décimo terceiro pelo tipo de folha.
• employer.TAB_Autonomo e employer.TAB_Pessoa_Fisica: autônomo e seus dados pessoais; o vínculo com o eSocial é feito por CPF.
• employer.TAB_Arquivo_Gerado_Empregado e employer.TAB_Arquivo_Gerado_Lote: arquivos gerados por empregado e por lote, referenciados no controle do que já foi produzido.
• plataforma.TAB_Periodo_Calculo: período de cálculo, usado para filtrar a competência por mês e ano de início.
• plataforma.TAB_Status_Atividade: domínio de status das atividades, referenciado pelo rastreamento da EPays.

O caminho de leitura é: seleção de público (empregado ou autônomo) → employer.ESO_Remuneracao filtrada por plataforma.TAB_Periodo_Calculo → envio pelo transporte da integração → registro do resultado, que na EPays fica em employer.TAB_Integracao_Epays_Rastreamento.

2.2 Exemplos de Consultas

As consultas abaixo foram executadas e validadas no banco. São somente de leitura e permitem filtrar empregado, origem, status e período de cadastro.

1. Histórico de integrações EPays

USE PLATAFORMA_EMPLOYER;

DECLARE @Idf_Integracao_Epays_Rastreamento INT = NULL;
DECLARE @Idf_Empregado INT = NULL;
DECLARE @Des_Guid_Rastreamento VARCHAR(100) = NULL;
DECLARE @DataInicial DATE = '2026-01-01';
DECLARE @DataFinal DATE = '2026-08-31';

SELECT TOP (200)
    R.Idf_Integracao_Epays_Rastreamento, R.Idf_Empregado,
    R.Des_Guid_Rastreamento, R.Des_Origem_Integracao, R.Dta_Cadastro,
    R.Idf_Usuario, R.Idf_Status_Atividade, R.Dta_Execucao
FROM employer.TAB_Integracao_Epays_Rastreamento AS R
WHERE (@Idf_Integracao_Epays_Rastreamento IS NULL OR R.Idf_Integracao_Epays_Rastreamento = @Idf_Integracao_Epays_Rastreamento)
  AND (@Idf_Empregado IS NULL OR R.Idf_Empregado = @Idf_Empregado)
  AND (@Des_Guid_Rastreamento IS NULL OR R.Des_Guid_Rastreamento = @Des_Guid_Rastreamento)
  AND R.Dta_Cadastro >= @DataInicial
  AND R.Dta_Cadastro < DATEADD(DAY, 1, @DataFinal)
ORDER BY R.Dta_Cadastro DESC, R.Idf_Integracao_Epays_Rastreamento DESC;

2. Resumo das integrações EPays por origem e status

USE PLATAFORMA_EMPLOYER;

DECLARE @Idf_Empregado INT = NULL;
DECLARE @Idf_Status_Atividade INT = NULL;
DECLARE @Des_Origem_Integracao VARCHAR(100) = NULL;
DECLARE @DataInicial DATE = '2026-01-01';
DECLARE @DataFinal DATE = '2026-08-31';

SELECT
    R.Des_Origem_Integracao, R.Idf_Status_Atividade,
    COUNT(*) AS QuantidadeEnvios,
    COUNT(DISTINCT R.Idf_Empregado) AS QuantidadeEmpregados,
    MIN(R.Dta_Cadastro) AS PrimeiroEnvio,
    MAX(R.Dta_Cadastro) AS UltimoEnvio,
    SUM(CASE WHEN R.Dta_Execucao IS NULL THEN 1 ELSE 0 END) AS EnviosSemExecucao,
    SUM(CASE WHEN R.Dta_Execucao IS NOT NULL THEN 1 ELSE 0 END) AS EnviosExecutados
FROM employer.TAB_Integracao_Epays_Rastreamento AS R
WHERE (@Idf_Empregado IS NULL OR R.Idf_Empregado = @Idf_Empregado)
  AND (@Idf_Status_Atividade IS NULL OR R.Idf_Status_Atividade = @Idf_Status_Atividade)
  AND (@Des_Origem_Integracao IS NULL OR R.Des_Origem_Integracao = @Des_Origem_Integracao)
  AND R.Dta_Cadastro >= @DataInicial
  AND R.Dta_Cadastro < DATEADD(DAY, 1, @DataFinal)
GROUP BY R.Des_Origem_Integracao, R.Idf_Status_Atividade
ORDER BY QuantidadeEnvios DESC, UltimoEnvio DESC;

3. Última integração EPays por empregado e origem

USE PLATAFORMA_EMPLOYER;

DECLARE @Idf_Empregado INT = NULL;
DECLARE @Des_Origem_Integracao VARCHAR(100) = NULL;
DECLARE @Idf_Status_Atividade INT = NULL;
DECLARE @DataInicial DATE = '2026-01-01';
DECLARE @DataFinal DATE = '2026-08-31';

WITH UltimaIntegracao AS
(
    SELECT
        R.Idf_Integracao_Epays_Rastreamento, R.Idf_Empregado,
        R.Des_Guid_Rastreamento, R.Des_Origem_Integracao, R.Dta_Cadastro,
        R.Idf_Usuario, R.Idf_Status_Atividade, R.Dta_Execucao,
        ROW_NUMBER() OVER
        (
            PARTITION BY R.Idf_Empregado, R.Des_Origem_Integracao
            ORDER BY R.Dta_Cadastro DESC, R.Idf_Integracao_Epays_Rastreamento DESC
        ) AS Ordem
    FROM employer.TAB_Integracao_Epays_Rastreamento AS R
    WHERE (@Idf_Empregado IS NULL OR R.Idf_Empregado = @Idf_Empregado)
      AND (@Des_Origem_Integracao IS NULL OR R.Des_Origem_Integracao = @Des_Origem_Integracao)
      AND (@Idf_Status_Atividade IS NULL OR R.Idf_Status_Atividade = @Idf_Status_Atividade)
      AND R.Dta_Cadastro >= @DataInicial
      AND R.Dta_Cadastro < DATEADD(DAY, 1, @DataFinal)
)
SELECT TOP (200)
    Idf_Integracao_Epays_Rastreamento, Idf_Empregado,
    Des_Guid_Rastreamento, Des_Origem_Integracao, Dta_Cadastro,
    Idf_Usuario, Idf_Status_Atividade, Dta_Execucao,
    CASE WHEN Dta_Execucao IS NULL THEN 'Sem execução' ELSE 'Executada' END AS SituacaoExecucao
FROM UltimaIntegracao
WHERE Ordem = 1
ORDER BY Dta_Cadastro DESC, Idf_Empregado, Des_Origem_Integracao;

💻 3 - Código Fonte

3.1 - Arquivos, classes e estruturas

• MenuMaisOpcoes.aspx: define o bloco MenuArvoreIntegracoes, que determina quais telas compõem o módulo e com quais rótulos. A tela de Reprocessar Ponto aparece também no menu de Serviços de Campo.
• IntegracaoPessoaFisica.aspx / .aspx.cs: seleção de registros de pessoa física para envio ao eSocial, mantendo em estado de tela as listas de selecionados e de portadores de deficiência.
• ServicosCampoReprocessarPonto.aspx / .aspx.cs: reprocessamento da integração de ponto, com permissão própria de reprocessar.
• IntegracaoConectNovo.aspx / .aspx.cs: escolha do evento eSocial, do período e do público, com adição separada de empregados e de autônomos por modais de filtro.
• IntegracaoEPaysRegistroEmpregado.aspx / .aspx.cs: envio de registro de empregado para a EPays; convive com as telas irmãs de documentos, por empregado e por lote.
• IntegracaoMedicina.aspx / .aspx.cs: seleção de empregados e publicação do evento na fila de medicina.
• IntegracaoEmprestimoConsignado.aspx / .aspx.cs: integração de empréstimo consignado, com geração de planilha.
• IntegracaoMeuWorkFlow.aspx / .aspx.cs: publicação de eventos para o Meu Workflow por mensageria.
• Employer.Plataforma.BLL.WebFoPag.IntegracaoConectEsocial: concentra as consultas que montam os eventos do eSocial, incluindo o tratamento do décimo terceiro e a união de empregados e autônomos.
• Employer.Plataforma.Plugins.WebFopag.Integracoes.IntegracaoEpays: cliente da API da EPays — obtenção de token, solicitação do endereço de blob e upload do arquivo.
• Employer.Plataforma.BLL.IntegracaoEpaysRastreamento (_P1, _P2): entidade do rastreamento de envios da EPays.
• Apoio: Etec.Service.Util.Integracoes.RabbitMQ e Etec.Service.Util.Enumeradores.EventMap (fila e mapa de eventos), Employer.PlataformaServices.Messaging (mensageria do Meu Workflow), Employer.Plataforma.Integrador.IntegracaoPontofopag (integrador de ponto), ParametroEspecifico (credenciais por empresa) e os modais ucModalFiltroEmpregados e ucModalFiltroAutonomos.

3.2 - Principais métodos e fluxo de execução

• Autenticação na EPays: GetToken envia usuário e chave para /api/auth/usuario e devolve o token; as credenciais vêm de ParametroEspecifico pelos parâmetros UsuarioAPIEPAYS e SenhaAPIEPAYS, resolvidos pela empresa informada. As exceções são reescritas com status HTTP, identificador da empresa e usuário, o que torna o erro rastreável sem abrir o corpo da resposta.
• Envio do arquivo na EPays: GetBlob recupera o endereço e o token de blob; UploadArquivo monta a URL com o nome do arquivo, define o tipo de blob e o tipo de conteúdo, fixa o protocolo TLS e envia por PUT. Falhas leem o corpo da resposta e o incluem na mensagem de erro.
• Montagem do evento no Conect: a consulta popula uma tabela de remunerações a partir de tabelas temporárias de empregados e de autônomos selecionados na tela, filtrando pelo mês e ano do período de cálculo. Quando o mês informado é 13, a origem passa a ser o holerite do tipo de folha do décimo terceiro no ano.
• Limpeza antes de reintegrar: antes de recompor o evento, a rotina remove os desdobramentos já existentes — remuneração de outras empresas e benefícios com seus dependentes — para as remunerações que serão reprocessadas.
• Seleção de público: as telas mantêm em estado de página as listas de selecionados e abrem modais de filtro que devolvem os identificadores escolhidos; o comportamento dos filtros acompanha o tipo de estrutura gerencial da empresa.
• Permissões: cada tela carrega a sua lista de permissões no início e a consulta antes de habilitar as ações. O reprocessamento de ponto tem permissão dedicada.

🏗️ 4 - Layered Architecture em C#

• Apresentação: as sete páginas .aspx com seus code-behinds, herdando de BasePageWebFoPag, com grids paginadas, modais de filtro de empregados e de autônomos, e estado de seleção mantido na própria página.
• Aplicação e integração: Employer.Plataforma.Aplicacao.WebFoPag.Integracoes.ESocial e Employer.Plataforma.Integrador.IntegracaoPontofopag encapsulam o diálogo com os destinos; Employer.Plataforma.Plugins.WebFopag.Integracoes.IntegracaoEpays implementa o cliente HTTP da EPays.
• Mensageria: Etec.Service.Util.Integracoes.RabbitMQ e Employer.PlataformaServices.Messaging publicam eventos para Medicina e Meu Workflow, com o mapa de eventos definindo o que cada mensagem representa.
• Negócio: Employer.Plataforma.BLL.WebFoPag.IntegracaoConectEsocial e Employer.Plataforma.BLL.IntegracaoEpaysRastreamento concentram, respectivamente, a montagem dos eventos do eSocial e o histórico dos envios.
• Acesso a dados: as entidades expõem LoadObject, Listar, Save e Delete sobre DataAccessLayer com comandos parametrizados; a integração do Conect usa consultas extensas declaradas como constantes na própria classe, apoiadas em tabelas temporárias montadas a partir da seleção da tela.

🧪 5 - Sugestões de Cenários de Teste e Validações (QA)

5.1 - Interface e componentes

• Abrir cada uma das sete telas pelo menu Integrações e confirmar que o rótulo apresentado corresponde ao do bloco de menu.
• Entrar com empresa que utiliza centro de resultado e conferir que contrato e departamento ficam ocultos e o centro de resultado aparece; repetir com empresa que não utiliza e conferir o inverso.
• Na integração do Conect, selecionar um evento de remuneração e conferir que mês e ano ficam visíveis; selecionar um evento de admissão ou de desligamento e conferir que o período some.
• Adicionar empregados pelo modal de filtro, fechar e reabrir a tela, e conferir se a seleção é preservada.
• Adicionar autônomos pelo modal correspondente e conferir que a lista é mantida separada da de empregados.
• Filtrar por ativos, por inativos e por ambos, e conferir o conjunto retornado em cada caso.
• Acionar a integração sem nenhum registro selecionado e conferir a mensagem apresentada.

5.2 - Regras de negócio

• Integrar um evento de remuneração para uma competência com holerite calculado e conferir que o evento é montado para os empregados selecionados.
• Informar mês 13 e conferir que a origem passa a ser o holerite do décimo terceiro do ano informado, e não o período de cálculo.
• Integrar um autônomo e conferir que o vínculo é feito por CPF e que registros com matrícula preenchida ficam de fora.
• Reintegrar manualmente um evento já enviado e conferir que os desdobramentos anteriores foram removidos antes da recomposição, sem duplicar benefícios ou dependentes.
• Integrar para uma competência sem remuneração correspondente e registrar o comportamento observado.
• Na EPays, disparar um envio e conferir que foi criada uma linha de rastreamento com identificador único, origem, usuário e status.
• Disparar dois envios seguidos para o mesmo empregado e conferir que geram identificadores de rastreamento distintos.
• Na Medicina e no Meu Workflow, disparar o evento e confirmar a publicação na fila; conferir o comportamento quando a fila está indisponível.
• No Empréstimo eConsignado, gerar a planilha e conferir o conteúdo contra o público selecionado.
• No Reprocessar Ponto, reprocessar um período já integrado e conferir o efeito no destino.

5.3 - Permissões, concorrência e casos de borda

• Acessar cada tela sem a permissão de visualização correspondente e conferir o barramento.
• Tentar reprocessar ponto sem a permissão dedicada de reprocessamento e conferir o bloqueio.
• Na EPays, configurar os parâmetros UsuarioAPIEPAYS e SenhaAPIEPAYS com valor inválido e conferir que a mensagem de erro identifica empresa e usuário sem expor a chave.
• Remover o parâmetro de credencial da empresa e conferir o comportamento na obtenção do token.
• Simular indisponibilidade da API da EPays e conferir que o erro registra o status HTTP e que o rastreamento reflete a falha.
• Simular falha no upload para o blob e conferir que a mensagem inclui a resposta do serviço.
• Disparar a mesma integração em duas sessões simultâneas para o mesmo público e registrar o comportamento observado, pois os arquivos analisados não demonstram bloqueio explícito de execução concorrente.
• Selecionar um volume grande de empregados e observar o tempo de resposta e o comportamento das tabelas temporárias.

⚖️ 6 - Embasamento Legal e Regras de RH

Prestação de informações trabalhistas pelo eSocial

• Fundamento: Decreto 8.373/2014 — Planalto.
• Relação com o módulo: o decreto institui o Sistema de Escrituração Digital das Obrigações Fiscais, Previdenciárias e Trabalhistas, unificando a prestação de informações e padronizando transmissão, validação, armazenamento e distribuição. É o que dá sentido às telas de integração manual de eventos do eSocial e ao próprio conceito de evento identificado por código, como os de remuneração, de pagamento, de admissão e de desligamento tratados neste módulo. O acionamento manual não substitui a rotina automática nem altera prazos: serve para reenviar o que ficou pendente. A responsabilidade pelo conteúdo e pela tempestividade da informação permanece com a área responsável.

Correção e reenvio de informação já prestada

• Fundamento: Decreto 8.373/2014 — Planalto.
• Relação com o módulo: a padronização do ambiente nacional pressupõe que a informação prestada possa ser corrigida e retransmitida de forma controlada. É o que justifica o desenho de reintegração deste módulo, em que os desdobramentos do evento são removidos antes de o evento ser recomposto, evitando que uma correção conviva com o registro anterior. O rastreamento por envio, com usuário e data, apoia a demonstração de quem reenviou o quê e quando.

📌 Status: Concluído
👤 Responsável: Equipe de QA