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-1250 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 1250 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.

Fora do escopo

• O HCM irá receber os eventos S-1250 e o evento ficará disponível no monitor FP9850 para transmissão ao Governo.

Fora do escopo

• Eliminação de S-1250  via integração.
• Eliminação de Autônomos via integração.
• Alteração de processos previamente cadastrados no HCM. Processos cadastrados no HCM, devem ser mantidos no HCM. 

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 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 processoS-1250.
• A integração não contemplará exclusão de registros 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 informações básicas para cadastramento do processo.

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

Parâmetros de Entrada:

Parâmetros e Chamada do Método:

Autenticação do tipo básica. 

Parâmetros e Chamada do Método:

Autenticação do tipo básica. 

Método Método POST.

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

Request da API: Exemplo do S-1200:

Image AddedImage Removed

Dados utilizados da API

Request da API: Exemplo do S-1210:

Image Removed

Dados utilizados da API

12096399850

1

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

{
    "messages": [],
    "length": null,
    "data": {
        "message": "Ocorreram Erros na Integração ",
        "details": [
            {
                "message": "Empresa precisa ser informada.",
                "detailedMessage": "",
                "code": "1",
                "type": "error"
            }
        ],
        "detailedMessage": "",
        "code": "56650",
        "type": "error"
    }
}

{
    "messages": [],
    "length": null,
    "data": {
        "message": "Ocorreram Erros na Integração ",
        "details": [
            {
                "message": "Empresa inexistente.",
                "detailedMessage": "",
                "code": "1",
                "type": "error"
            }
        ],
        "detailedMessage": "",
        "code": "56650",
        "type": "error"
    }
}

{
    "messages": [],
    "length": null,
    "data": {
        "message": "Ocorreram Erros na Integração ",
        "details": [
            {
     

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 'companyId' não informado.",
    		"code": "17006",
    		"type": "error"
}

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

           "

message": "

Estabelecimento precisa ser informado.",
                "detailedMessage": "",
                "code": "1",
                "type": "error"
            }
       

 ],
        "detailedMessage": "",
        "code": "

56650",

        "type": "error"
    }
}

{
    "messages": [],
    

"

length": 

null,
    "data": {
        "

message": "

Ocorreram Erros na Integração ",
        "details": [
            {
                "message": "

Estabelecimento inexistente 

ou 

não 

pertence a 

empresa informada.",
                

"

detailedMessage": "

",
               

"

code": "1",
                "type": "error"
            }
        ],
        "detailedMessage": "",
    

    "code": "

56650",

        "type": "error"
    }
}

{
    "messages": [],
    

"

length": 

null,
    "data": {
        "

message": "Ocorreram Erros na Integração ",
        "details": [
            {
                "message": "

XML 

precisa 

ser informado

.",
                

"

detailedMessage": "

",
             

   "code": "1",
                "type": "error"
            }
        ],
        "detailedMessage": "",
        "code": "

56650",

        "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.

EMS2:

• Verificar se os parâmetros de conexão foram cadastrados corretamente no CD0387: URL, Porta, Usuário e Senha.
• Verificar se os registros referentes a aquisição da produção rural foram gerados corretamente no programa CD2020 conforme o período desejado.