Páginas filhas
  • DI Integração Backoffice - API recebe evento S-1250 do recebimento - Datasul (EMS x HCM)

Versões comparadas

Chave

  • Esta linha foi adicionada.
  • Esta linha foi removida.
  • A formatação mudou.
Comentário: Migration of unmigrated content due to installation of a new plugin

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-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:

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

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 S-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 ruralProductionAcquisitions;
  • Utilizar a chamada do método Post e do Serviço ruralProductionAcquisitions;
  • Preenchimento dos parâmetros obrigatórios da API;

Parâmetros de Entrada:

Parâmetro

Valor de Exemplo

Obrigatório

Tipo

Valor Default

Descrição
authorization usuario:senhaSim

header


autenticação é importante para o funcionamento correto da API em casos de ambientes com autenticação Http Basic.
contentrequest da apisimbody

Estrutura json com informações de cadastro do processo:

Propriedades Obrigatórias:

Dados do S-1250:

  • companyId : CNPJ da empresa a qual o pertence o S-1250.
  • companyCode: Empresa a qual o pertence o S-1250.
  • BranchIdbranchCode: Estabelecimento o qual pertence o S-1250.
  • perApur: Período de apuração do valores contidos nos arquivos.
  • tpAmb: Identificação do Ambiente, informado na base.
  • XMLMessage: Arquivo XML do S-1250 em Base64.



Parâmetros e Chamada do Método:

Autenticação do tipo básica. 

Método POST.

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

Request da API

Image RemovedImage Added

Dados utilizados da API

Propriedade API RESTCAMPO HCMDESCRIÇÃOFormato / Exemplo
companyIdcod_id_federCNPJ da empresa"52045697000110"
companyCodecdn_empresaEmpresa para o qual o autônomo emitiu a nota. pertence o S-1250"123"
BranchIdbranchCodecod_estabEstabelecimento para o qual o autônomo emitiu a nota. pertence o S-1250"1"
autonomousNamenom_pessoa_fisicNome da pessoa física do autônomo. "José da Silva"
dateOfBirthdat_nascimentoData de nascimento do autônomo. "1950-02-01"
autonomousIdcod_id_federCPF do autônomo. 67886374070
RegistrationNumbercdd_func_inssMatrícula INSS do autônomo.12096399850
perApurNão se aplicaData Período de apuração dos movimentos enviados no arquivodo valores contidos nos arquivos."2019-06-17201906"
InternalId (listMov)Não se aplicaNúmero do documento no HCM"556366367"
seriesKeyNão se aplicaSérie do documento no HCM "Des55"
sourceIdNão se aplicaChave do título no financeiro. "vog-1-123456-01"
indMV (nfoMV)Não se aplicaIndicativo se o autônomo é múltiplo vinculo na empresa da nota.1
tpInsc (remunOutrEmpr)Não se aplicaTipo de inscrição. 

1

nrInscNão se aplicaNúmero da inscrição32155966288
codCategcdn_categoriaCódigo da categoria do autônomo perante o eSocial. 701
vlrRemunOENão se aplicaValor de remuneração em outra empresa referente ao mês/ano de apuração. 3250.00
vlrRecolhidoOENão se aplicaValor de INSS recolhido em outra empresa.

120.00 

tpTrib (procJudTrab)Não se aplicaTipo de tributação caso o autônomo tenha processo trabalhista.1
nrProcJudNão se aplicaNúmero do processo jurídico. 2334546778788
codSuspNão se aplicaCódigo de suspensão do processo trabalhista11
ideDmDev (dmDev)Não se aplica"014|5663|8292"
codCateg (dmDev)Não se aplicaCódigo da categoria que o autônomo perante o eSocial.701
tpInsc (ideEstabLot)Não se aplicaTipo de inscrição1
nrInscNão se aplicaNúmero da inscrição123456790
codLotacaoNão se aplicaCódigo da lotação do autônomo"1-002-5656-22-1'"
qtdDiasAvNão se aplicaQuantidade de dias aviso30
identRubr (itensRemun)Não se aplicaIdentificador da rubrica1
codRubrNão se aplicaCódigo da rubrica1604
vrRubrNão se aplicaValor da rubrica5000.00
ideTabRubrNão se aplicaIdentificação tab rubrica0001
grauExp (infoAgNocivo)Não se aplicaGrau e exposição1
codCBO (infoComplCont)Não se aplicaCódigo do CBO99999
natAtividadeNão se aplicaNatureza da atividade do autônomo1
qtdDiasTrabNão se aplicaQuantidade de dias trabalhados0
tmAmbidi_tip_ambienIdentificação do Ambiente, informado no FP0560Valores Válidos: 1, 2.
XMLMessageNão se aplicaXml do evento S-1250 em base 64"PGVTb2NpYWw+CjxldnRBcVByb2QgSUQgPSAiSUQ1NDY1NDY1NDU2NDU2NDU2NTQiPgo8aWRlRXZlbnRvPgo8aW5kUmV0aWY+MTwvaW5kUmV0aWY+CjxpbmRBcHVyYWNhbz4xPC9pbmRBcHVyYWNhbz4KPHBlckFwdXI+MjAxOS0wODwvcGVyQXB1cj4KPHRwQW1wPjE8L3RwQW1wPgo8cHJvY0VtaT4xPC9wcm9jRW1pPgo8L2lkZUV2ZW50bz4KPGlkZUVtcHJlZ2Fkb3I+Cjx0cEluc2M+MTwvdHBJbnNjPgo8bnJJbnNjPjUzMjU1Nzg3ODwvbnJJbnNjPgo8L2lkZUVtcHJlZ2Fkb3I+CjxpbmZvQXF1aXNQcm9kPgo8aWRlRXN0YWJBcXVpcj4KPHRwSW5zY0FkcT4xPC90cEluc2NBZHE+Cjxuckluc2NBZHE+NTEyMTE0NTQ1PC9uckluc2NBZHE+Cjx0cEFxdWlzPgo8aW5kQXF1aXM+MTwvaW5kQXF1aXM+Cjx2bHJUb3RBcXVpcz4yMTAwLjAwPC92bHJUb3RBcXVpcz4KPGlkZVByb2R1dG9yPgo8dHBJbnNjUHJvZD4yPC90cEluc2NQcm9kPgo8bnJJbnNjUHJvZD42NDg3ODU0NTU1PC9uckluc2NQcm9kPgo8dmxyQnJ1dG8+MTA1MC4wMDwvdmxyQnJ1dG8+Cjx2ckNQRGVzY1BSPjAuMDA8L3ZyQ1BEZXNjUFI+Cjx2clJhdERlc2NQUj4wLjAwPC92clJhdERlc2NQUj4KPHZyU2VuYXJEZXNjPjAuMDA8L3ZyU2VuYXJEZXNjPgo8L2lkZVByb2R1dG9yPgo8aWRlUHJvZHV0b3I+Cjx0cEluc2NQcm9kPjI8L3RwSW5zY1Byb2Q+Cjxuckluc2NQcm9kPjg5Nzg5NzMyMTQ0PC9uckluc2NQcm9kPgo8dmxyQnJ1dG8+MTA1MC4wMDwvdmxyQnJ1dG8+Cjx2ckNQRGVzY1BSPjAuMDA8L3ZyQ1BEZXNjUFI+Cjx2clJhdERlc2NQUj4yMS4wMDwvdnJSYXREZXNjUFI+Cjx2clNlbmFyRGVzYz4xMC41MDwvdnJTZW5hckRlc2M+CjwvaWRlUHJvZHV0b3I+CjwvdHcz4KPC9pZGVFc3RhYkFxdZm9BcXVpc1Byb2Q+CQcm9kPgo8L2VTb2NpYWw="



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

Erro

Mensagem

Solução

API RESPONSE
17006

1

Parâmetro '

companyId

companyCode' não informado

Verificar se a propriedade json

companyId

companyCode está preenchida no pacote enviado .

Bloco de código
themeEclipse
linenumberstrue
collapsetrue
{
   
 "
message
messages": [],
    "
Parâmetro 'companyId' não informado.",
length": null,
    "data": {
    
"code
    "message": "
17006
Ocorreram Erros na Integração ",
    
"type
    "details": 
"error" }17006

Parâmetro 'branchId' não informado.

Verificar se a propriedade json branchId existe e está com valor válido conforme leiaute do eSocial.    Bloco de código
themeEclipse
linenumberstrue
collapsetrue
{
[
            {
                "message": "
Parâmetro
Empresa 
'branchId'
precisa 
não
ser 
informado
informada.",
               
 "
code
detailedMessage": "
17006
",
                "
type
code": "
error
1"
}17006

Empresa EMP e/ou Estabelecimento 100 informados como parâmetro não foram encontrados na tabela do TOTVS Datasul HCM.

Verificar se as propriedades json companyId e branchId estão preenchido corretamente e se os valores existem na base de dados do RH. Bloco de código
themeEclipse
linenumberstrue
collapsetrue
{ "message": "Empresa EMP e/ou Estabelecimento 100 informados como parâmetro não foram encontrados na tabela do TOTVS Datasul HCM."
,
                "type": "error"
            }
        ],
    
"code
    "detailedMessage": "
17006
",
        "code": "56650",
        "type": "error"
    }
}
17006
1Parâmetro '
codCateg
companyCode'
da tag 'dmDev' não informado.Verificar no json do S-1200 se a propriedade 'codCateg' filha da propriedade 'dmDev' está preenchida.
não é validoVerificar se a empresa existe no HCM
Bloco de código
themeEclipse
linenumberstrue
collapsetrue
{
    
"messages": [],
    "length": null,
    "data": {
        "message": "Ocorreram Erros na Integração ",
    
"Parâmetro 'codCateg' da tag 'dmDev' não informado."
    "details": [
            {
                "message": "Empresa inexistente.",
                "detailedMessage": "",
    
            "code": "
17006
1",
                "type": "error"
            }
        ],
        "detailedMessage": "",
        "code": "56650",
        "type": "error"
    }
}
17006
1

Parâmetro '

eSocialAutonomousCategory

branchCode' não informado.

Verificar
no json do S-1210
se a
propriedade 
propriedade json '
eSocialAutonomousCategory
branchCode' está preenchida
.
Bloco de código
themeEclipse
linenumberstrue
collapsetrue
{
   
 "
message
messages": [],
 
"Parâmetro
 
'eSocialAutonomousCategory'
 
não
 
informado."
"length": null,
    
"
code
data": {
 
"17006",
       "message": "Ocorreram Erros na Integração ",
        "
type
details": 
"error" }17006Não foi encontrado a categoria: 'xyz' na tabela de Categoria do eSocial.Verificar se a categoria informada corresponde as categorias da tabela do eSocial. Bloco de código
themeEclipse
linenumberstrue
collapsetrue
{
[
            {
                "message": 
"Não foi encontrado a categoria: 'xyz' na tabela de Categoria do eSocial.",
"Estabelecimento precisa ser informado.",
                "detailedMessage": "",
                "code": "
17006
1",
                "type": "error"
}17006A Categoria informada exige a geracação do S-2300, sendo assim, é obrigatório o autônomo também estar cadastrado no FP1500.

Verificar se o autônomo é MV e se está cadastrado no FP1500. Algumas categorias do eSocial exige o S-2300.

Segue link explicativo: e-Social - Geração do Evento S-2300 - Trabalhador sem Vínculo de Empregado

Bloco de código
themeEclipse
linenumberstrue
collapsetrue
{ "message": "A Categoria informada exige a geracação do S-2300, sendo assim, é obrigatório o autônomo também estar cadastrado no FP1500.",
            }
        ],
        "detailedMessage": "",
        "code": "
17006
56650",
        "type": "error"
    }
}
17006
1Parâmetro '
grauExp
branchCode'
é obrigatório quando a categoria for 731, 734 e 738.
não é validoVerificar se a propriedade do json '
grauExp' está sendo preenchida quando a categoria for 731, 734 e738
branchCode' está preenchido com o valor correto.
Bloco de código
themeEclipse
linenumberstrue
collapsetrue
{
   
 "messages": [],
    "length": null,
    "data": {
        "message": "Ocorreram Erros na Integração ",
    
"Parâmetro 'grauExp' é obrigatório quando a categoria for 731, 734 e 738.", "code": "17006
    "details": [
            {
                "message": "Estabelecimento inexistente ou não pertence a empresa informada.",
                "detailedMessage": "",
                "
type
code": "
error" }17006Parâmetro 'identRubr' não informado ou está com o valor igual a zero.Verificar se a propriedade do json 'identRubr' está preenchido, esse campo é obrigatório. Bloco de código
themeEclipse
linenumberstrue
collapsetrue
{ "message": "Parâmetro 'identRubr' não informado ou está com o valor igual a zero."
1",
                "type": "error"
            }
        ],
    
"code
    "detailedMessage": "
17006
",
        "code": "56650",
        "type": "error"
    }
}
17006
1Parâmetro
'qtdDiasAv'
XMLMessage não informado
ou está com o valor igual a zero.
Verificar se
a propriedade do json 'qtdDiasAv' está sendo preenchido quando a classificação tributária do empregador for igual a "22".
foi informado o xml em Base 64 na propriedade XMLMessage do json
Bloco de código
themeEclipse
linenumberstrue
collapsetrue
{
    "messages": [],
    "length": null,
    "data": {
   
     "message": "
Parâmetro 'qtdDiasAv' não informado ou está com o valor igual a zero.", "code": "17006",
Ocorreram Erros na Integração ",
        "details": [
            {
                "message": "XML precisa ser informado.",
                "detailedMessage": "",
                "
type
code": "
error" }17006Número da Matrícula INSS já está cadastrada para o Autônomo " 99999Verificar se a propriedade do json 'RegistrationNumber' está preenchido com o valor correto, pois na base de dados do RH já deve ter outro CPF usando a mesma Matrícula INSS Bloco de código
themeEclipse
linenumberstrue
collapsetrue
{ "message": "Número da Matrícula INSS já está cadastrada para o Autônomo " 99999."
1",
                "type": "error"
            }
        ],
    
"code
    "detailedMessage": "
17006
",
        "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.