INTEGRAÇÃO

Contexto de Negócio (Introdução)

Cada vez mais o mercado exige que as operações complexas e manipulação de dados ainda mais ágeis e com custos reduzidos. Com o RH não é diferente, por isso os pagamentos pertinentes aos autônomos que foram cadastrados no EMS, precisam ser enviados para o eSocial de forma transparente para o usuário. 

Frente a esta necessidade, foi criada uma interface que possibilite automatizar o envio do arquivo S-1200/S-1210 para o eSocial, através de uma interface de integração. 

Sistemas Envolvidos

• HCM (módulo Folha de Pagamento): O módulo Folha de Pagamento visa efetuar os cálculos da folha de pagamento para os funcionários, mantendo o controle sobre os valores referentes aos eventos relativos a estes funcionários.

• EMS (módulo Recebimento): O módulo Recebimento visa agilizar e assegurar o recebimento dos materiais da empresa, possibilitando todos os controles necessários dos materiais.

Integração

O objetivo desta integração é permitir que a área do RH, recebam os arquivos S-1200/S-1210 de outros sistemas especializados na área, reduzindo assim o trabalho de inclusão manual de todas as informações dentro do sistema;

• Arquitetura (Tecnologia)
  
  • Esta integração é 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.

A partir do leiaute S-1.2 o S-1210 passou a integrar os dependentes no programa FP0840 na nova aba de dependentes que é acessada pelo botão eSocial, e para que o botão eSocial fique habilitado é necessário que o parâmetro Envio Movimentos Autônomos pela Folha de Pagamento (FP2160) esteja marcado mesmo que utilize a forma de integração de autônomos pelo backoffice.

eSocial - XML S-1200 - Válido apenas para a geração do Layout S-1.0 ou superior:

No bloco <itensRemun> irão constar todas as Rubricas, inclusive as de IR.

A tag <indApurIR> será gerada pela Folha e com valor fixo igual a 0.

A tag <indGuia> será gerada pela Folha de acordo com a regra de validação do layout, porém somente quando a Classificação Tributária for igual a 22 e a Inscrissão diferente de CNO.

APB - E-Social - Cadastro de rubricas no programa CD0387

Sistemas Envolvidos

• HCM (módulo Folha de Pagamento): O módulo Folha de Pagamento visa efetuar os cálculos da folha de pagamento para os funcionários, mantendo o controle sobre os valores referentes aos eventos relativos a estes funcionários.

• EMS (módulo Recebimento): O módulo Recebimento visa agilizar e assegurar o recebimento dos materiais da empresa, possibilitando todos os controles necessários dos materiais.

Integração

O objetivo desta integração é permitir que a área do RH, recebam os

Escopo

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

arquivos S-1200/S-1210

Fora do escopo

• Eliminação de Autônomos ou Pessoas Físicas via integração.
• Gerar a mensagem com XML para envio ao Governo - a mensagem com XML deverá ser gerada após integração no FP9824 Geração Mensagem Periódico Remuneração, uma vez que o autônomo pode ser um funcionário também do empregado e as mensagens S-1200 e S-1210 são consolidadas por CPF e por mês/ano de apuração. 

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

• Versões mínima do TOTVS/Datasul: 12.1.27
• Estrutura de rede estável, para que haja trafego de dados sem interrupção
• Datasul devidamente configurado e serviço Rest habilitado em seu server, com acesso à internet. 

Processos

O Sistema requisitante enviará as informações via Json para a interface de integração, desta forma será validado as informações contidas no Json, e caso necessário, irá cadastrar o autônomo  no HCM. Caso tenha êxito na geração do registro, será retornado o status 201, com a mesma estrutura de Json confirmando sua gravação, caso contrário enviará as informações de inconsistências citadas nos próximos tópicos.

Limitações / Restrições Gerais

• Com o objetivo de manter a estrutura e a agilidade da estrutura Rest, o Web Service Rest receberá registro individual de cada pagamento (S-1210) ou remuneração (S-1200). Sendo que cada pagamento ou remuneração pode ter mais uma ou mais notas do autônomo, desde que sejam do mesmo mês/ano de apuração. 
• A integração não contemplará exclusão de Pessoas Físicas (FP1440) ou Prestadores (FP0840) no HCM - para isso o usuário deverá acessar o HCM e excluir manualmente o mesmo e seus devidos relacionamentos. 

Como realizar a chamada da API REST

Para realizar a integração, é necessário as seguintes informações básicas:

• Preenchimento do EndPoint da API esocialPayments;
• Utilizar a chamada do método POST e do Serviço esocialPayments;
• Preenchimento dos parâmetros obrigatórios da API;

de outros sistemas especializados na área, reduzindo assim o trabalho de inclusão manual de todas as informações dentro do sistema;

• Arquitetura (Tecnologia)
  
  • Esta integração é 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.

Escopo

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

• A validação das informações contida nos arquivos S-1200/S-1210 antes do envio para o Governo.
• Caso o Autônomo mencionado nos arquivos não estiver cadastrado no FP1440/FP0840, através da integração será cadastrado o Autônomo no FP1440/FP0840 conforme informações contidas nos arquivos.
• A integração irá gerar as tabelas intermediárias de remuneração ou de pagamento conforme arquivo integrado. Estes registros podem ser consultados no FP9825 Conferência Remuneração/Pagamentos eSocial.

Fora do escopo

• Eliminação de Autônomos ou Pessoas Físicas via integração.
• Gerar a mensagem com XML para envio ao Governo - a mensagem com XML deverá ser gerada após integração no FP9824 Geração Mensagem Periódico Remuneração, uma vez que o autônomo pode ser um funcionário também do empregado e as mensagens S-1200 e S-1210 são consolidadas por CPF e por mês/ano de apuração. 

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

• Versões mínima do TOTVS/Datasul: 12.1.27
• Estrutura de rede estável, para que haja trafego de dados sem interrupção
• Datasul devidamente configurado e serviço Rest habilitado em seu server, com acesso à internet. 

Processos

O Sistema requisitante enviará as informações via Json para a interface de integração, desta forma será validado as informações contidas no Json, e caso necessário, irá cadastrar o autônomo  no HCM. Caso tenha êxito na geração do registro, será retornado o status 201, com a mesma estrutura de Json confirmando sua gravação, caso contrário enviará as informações de inconsistências citadas nos próximos tópicos.

Limitações / Restrições Gerais

• Com o objetivo de manter a estrutura e a agilidade da estrutura Rest, o Web Service Rest receberá registro individual de cada pagamento (S-1210) ou remuneração (S-1200). Sendo que cada pagamento ou remuneração pode ter mais uma ou mais notas do autônomo, desde que sejam do mesmo mês/ano de apuração. 
• A integração não contemplará exclusão de Pessoas Físicas (FP1440) ou Prestadores e Dependentes (FP0840) no HCM - para isso o usuário deverá acessar o HCM e excluir manualmente o mesmo e seus devidos relacionamentos. 

Como realizar a chamada da API REST

Para realizar a integração, é necessário as seguintes informações básicas:

• Preenchimento do EndPoint da API esocialPayments;
• Utilizar a chamada do método POST e do Serviço esocialPayments;
• Preenchimento dos parâmetros obrigatórios da API;

Parâmetros de Entrada:

Tipo/Naturezas de Rúbricas vinda do EMS:

A rubrica enviada na integração deverá estar cadastrada no HCM no programa FP0020.

Parâmetros e Chamada do Método:

Autenticação do tipo básica. 

Método POST.

{protocolo}://{host}/api/rh/v1/esocialPayments

Request da API: Exemplo do S-1200:

Image Added

Dados utilizados da API

Request da API: Exemplo do S-1210:

Image Added

Dados utilizados da API

Parâmetros de Entrada:

Parâmetro

Valor de Exemplo

Obrigatório

Valor Default

header

Estrutura json com informações para poder gerar as tabelas intermediárias de remuneração (S-1200) ou pagamento (S-1210): 

Propriedades Obrigatórias:

Dados do S-1200 e S-1210:

• file : Indicativo de qual arquivo o Json se refere.
• companyId : CNPJ do estabelecimento para o qual o autônomo prestou serviço.
• companyCode: Código da Empresa a qual o autônomo prestou serviço.
• branchCode: Estabelecimento o qual o autônomo prestou serviço.
• dateOfBirth: Data de nascimento do autônomo.
• autonomousId: CPF do Autônomo.
• registrationNumber: Número da matrícula do INSS
• perApur: Período de apuração do valores contidos nos arquivos.

Dados do S-1200:

• codCateg: Código da categoria que o autônomo se enquadra dentro do eSocial.

Dados do S-1210:

• esocialAutonomousCategory: Código da categoria que o autônomo se enquadra dentro do eSocial.

Parâmetros e Chamada do Método:

Autenticação do tipo básica. 

Método POST.

{protocolo}://{host}/api/rh/v1/esocialPayments

Request da API: Exemplo do S-1200:

Image Removed

Dados utilizados da API

"12345670000134"

Se não enviar a tag ou enviar em branco, o HCM irá considerar como 2.5 (significa que o cliente não atualizou os programas no backoffice para o layout S-1.0).

Quando não informado o leiaute, porém no sistema HCM estiver informado o layout, será apresentada a mensagem:

"Leiaute não informado. No eSocial esta sendo utilizado o leiaute XXX" (layout informado no FP0560, botão eSocial, campo leiaute eSocial)".

Se o leiaute informado na tag estiver divergente do sistema HCM (layout informado no FP0560, botão eSocial, campo leiaute eSocial), será emitida a mensagem: "O leiaute informado, XXX é diferente do que está cadastrado no eSocial, YYY"

1

120.00 

1

No bloco <itensRemun> vão constar todas as Rubricas, inclusive as de IR.

Request da API: Exemplo do S-1210:

Image Removed

Dados utilizados da API

Situações de Erros Tratados

O envio de dados inesperados nos parâmetros de entrada da API REST pode ocasionar alguns erros. Desta forma, foram criados alguns tratamentos de erros, listados abaixo, cada um com sua respectiva mensagem e solução.

Tratamento de erros de integração Datasul HCM:

Mensagens de Pré-Validação

{
   			"message": "Parâmetro 'companyCode' não informado.",
    		"code": "17006",
    		"type": "error"
}

{
   			"message": "Parâmetro 'branchCode' não informado.",
    		"code": "17006",
            "type": "error"
}

{
   			"message": "Empresa EMP e/ou Estabelecimento 100 informados como parâmetro não foram encontrados na tabela do TOTVS Datasul HCM.",
    		"code": "17006",
            "type": "error"
}

{
   			"message": "Parâmetro 'codCateg' da tag 'dmDev' não informado.",
    		"code": "17006",
            "type": "error"
}

{
   			"message": "Parâmetro 'eSocialAutonomousCategory' não informado.",
    		"code": "17006",
            "type": "error"
}

{
   			"message": "Não foi encontrado a categoria: 'xyz' na tabela de Categoria do eSocial.",
    		"code": "17006",
            "type": "error"
}

{
   			"message": "Para categoria informada  é obrigatório  o envio da mensagem S-2300 ao eSocial , sendo assim, seu cadastro e envio devem ser realizados através da Folha de Pagamento.",
    		"code": "17006",
            "type": "error"
}

{
   			"message": "Parâmetro 'identRubr' não informado ou está com o valor igual a zero.",
    		"code": "17006",
            "type": "error"
}

{
   			"message": "Parâmetro 'qtdDiasAv' não informado ou está com o valor igual a zero.",
    		"code": "17006",
            "type": "error"
}

{
   			"message": "Número da Matrícula INSS já está cadastrada para o Autônomo " 99999.",
    		"code": "17006",
            "type": "error"
}

{
   			"message": "Não encontrado o Código Suspensão:  11 para o processo: 55779911334466550123",
    		"code": "17006",
            "type": "error"
}

{
   			"message": "A Remuneração/Pagamento está em período ainda não obrigado ao envio dos periódicos ao governo. Verifique data das fases no botão Complemento do FP0560 - Manutenção Estabelecimento do empregador.",
    		"code": "56714",
            "type": "error"
}

{
   			"message": Informe um(a) valor dedução dependente válido(a). Está diferente da tabela de IRF/INSS Geral do período",
    		"code": "158",
            "type": "error"
}

OBS: Estas mensagens de validações serão retornadas sempre que algum campo passado que seja obrigatório ou que algum campo enviado tenha sua origem de dados em outra tabela e não seja localizado na mesma ou não estejam de acordo com o leiaute do eSocial. Vale lembrar que são apenas exemplos de mensagens de erros e podendo variar o nome da propriedade enviada.

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, clientlog, log do appServer ou algo que possa identificar a origem do problema.