Child pages
  • DI Integração Backoffice - API recebe movimento do financeiro - Datasul (EMS x HCM)

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: 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-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.

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.Alteração de processos
  • previamente cadastrados no HCM. Processos cadastrados no HCM, devem ser mantidos no HCMGerar 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 processo.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 registros 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 para cadastramento do processo.:

  • Preenchimento do EndPoint da API esocialPayments;
  • Utilizar a chamada do método Post e POST e do Serviço esocialPayments;
  • 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: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.
  • BranchIdbranchCode: 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:

Dados utilizados da API

Propriedade API RESTCAMPO HCMDESCRIÇÃOFormato / Exemplo
companyIdcod_id_federCNPJ do estabelecimento para o qual o autônomo prestou serviço. O CNPJ somente será verificado, se o Json não tiver preenchido o companyCode e branchCode. 

"12345670000134"

companyCodecdn_empresaEmpresa para o qual o autônomo emitiu a nota. "123"
BranchIdbranchCodecodcdn_estabEstabelecimento para o qual o autônomo emitiu a nota. "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
RegistrationNumberregistrationNumbercdd_func_inssMatrícula INSS do autônomo.12096399850
perApurNão se aplicaData de apuração dos movimentos enviados no arquivo."2019-06-17"
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. 233454677878855779911334466550123
codSuspNão se aplicaCódigo de suspensão do processo trabalhista11
ideDmDev (dmDev)Não se aplicaIdentificação do Demonstrativo. "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 tabela de rubrica0001
grauExp (infoAgNocivo)Não se aplicaGrau e exposição1
000001
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


Request da API: Exemplo do S-1210:

Dados utilizados da API

Propriedade API RESTCAMPO HCMDESCRIÇÃOFormato / Exemplo
companyIdcod_id_federCNPJ do estabelecimento para o qual o autônomo prestou serviço. O CNPJ somente será verificado, se o Json não tiver preenchido o companyCode e branchCode. "12345670000134"
companyCodecdn_empresaEmpresa para o qual o autônomo emitiu a nota. "123"
BranchIdbranchCodecodcdn_estabEstabelecimento para o qual o autônomo emitiu a nota. "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
RegistrationNumberregistrationNumbercdd_func_inssMatrícula INSS do autônomo.

12096399850

eSocialAutonomousCategorycdn_categoriaCódigo da categoria que o autônomo perante o eSocial.721
perApurNão se aplicaData de apuração dos movimentos enviados no arquivo."2019-06-17"
vrDedDepNão se aplicaValor de dedução dos dependentes 500.00
InternalId 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"
dtPgto (infoPgto)Não se aplicaData de pagamento "05-01-2019"
tpPgtoNão se aplicaTipo de pagamento. 

1

indResBrNão se aplicaIndicativo se o autônomo reside no Brasil"S"
perRef (detPgtoFl)Não se aplicaPeríodo de referência."01-2019"
ideDmDevNão se aplicaIdentificador do Demonstrativo."014|5663|8292"
indPgtoTt Não se aplicaIndica se o pagamento é total ou parcelado."N"
vrLiqNão se aplicaValor liquidolíquido.11223.11
identRubrNão se aplicaIdentificador da rubrica1
codRubrNão se aplicaCódigo da rubrica."1-604"
vrRubrNão se aplicaValor da rubrica.5000.00
ideTabRubrNão se aplicaIdentificação tab tabela de rubrica."0001000001"
cpfBenef (penAlim)Não se aplicaCPF do beneficiário.0505656987
dtNasctoBenefNão se aplicaData de nascimento do beneficiário.99999
nmBeneficNão se aplicaNome do beneficiárioMaria Santos
vlrPensaoNão se aplicaValor da pensão325.89
identRubrNão se aplicaIdentificador da rubrica1
codRubr (infoPgtoParc)Não se aplicaCódigo da rubrica"1-604"
vrRubrNão se aplicaValor da rubrica5000.00
ideTabRubrNão se aplicaIdentificação tab tabela de rubrica"0001000001"
codCateg (detPgtoAnt)Não se aplicaCódigo da categoria 
tpBcIRRFNão se aplicaTipo base IRRF2
vrBcIRRFNão se aplicaValor base IRRF1234.88
codPais (idePais)Não se aplicaCódigo do País da residência do autônomo"BRA"
indNIFNão se aplicaIndicativo NIF1
nifBenefNão se aplicaNIF do beneficiário"554145551451"
dscLograd (endExt)Não se aplicaDescrição logradouro "Rua bla bla"
nrLogradNão se aplicaNúmero logradouro "556"
complemNão se aplicaComplemento logradouro"lateral da rua xyz"
bairroNão se aplicaBairro "Aphaville"
nmCidNão se aplicaNome da cidade"São Paulo"
codPostalNão se aplicaCódigo postal"55515"

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

Parâmetro 'companyIdcompanyCode' não informado

Verificar se a propriedade json companyId companyCode está preenchida no pacote enviado .

Code Block
themeEclipse
linenumberstrue
collapsetrue
{
   			"message": "Parâmetro 'companyIdcompanyCode' não informado.",
    		"code": "17006",
    		"type": "error"
}
17006

Parâmetro 'branchIdbranchCode' não informado.

Verificar se a propriedade json branchId  branchCode existe e está com valor válido conforme leiaute do eSocial.   
Code Block
themeEclipse
linenumberstrue
collapsetrue
{
   			"message": "Parâmetro 'branchIdbranchCode' não informado.",
    		"code": "17006",
            "type": "error"
}
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 companyCode e branchCode estão preenchido corretamente e se os valores existem na base de dados do RH.
Code Block
themeEclipse
linenumberstrue
collapsetrue
{
   			"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"
}
17006

Parâmetro 'codCateg' da tag 'dmDev' não informado.

Verificar no json do S-1200 se a propriedade 'codCateg' filha da propriedade 'dmDev' está preenchida.
Code Block
themeEclipse
linenumberstrue
collapsetrue
{
   			"message": "Parâmetro 'codCateg' da tag 'dmDev' não informado.",
    		"code": "17006",
            "type": "error"
}



17006

Parâmetro 'eSocialAutonomousCategory' não informado.

Verificar no json do S-1210 se a propriedade 'eSocialAutonomousCategory' está preenchida.
Code Block
themeEclipse
linenumberstrue
collapsetrue
{
   			"message": "Parâmetro 'eSocialAutonomousCategory' não informado.",
    		"code": "17006",
            "type": "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.
Code Block
themeEclipse
linenumberstrue
collapsetrue
{
   			"message": "Não foi encontrado a categoria: 'xyz' na tabela de Categoria do eSocial.",
    		"code": "17006",
            "type": "error"
}
17006Para 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.

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

Code Block
themeEclipse
linenumberstrue
collapsetrue
{
   			"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"
}
17006Parâmetro 'grauExp' é obrigatório quando a categoria for 731, 734 e 738identRubr' não informado ou está com o valor igual a zero.Verificar se a propriedade do json 'grauExpidentRubr' está sendo preenchida quando a categoria for 731, 734 e738preenchido, esse campo é obrigatório.
Code Block
themeEclipse
linenumberstrue
collapsetrue
{
   			"message": "Parâmetro 'grauExpidentRubr' énão obrigatórioinformado quandoou aestá categoriacom foro 731,valor 734igual ea 738zero.",
    		"code": "17006",
            "type": "error"
}
17006Parâmetro 'identRubrqtdDiasAv' não informado ou está com o valor igual a zero.Verificar se a propriedade do json 'identRubrqtdDiasAv' está preenchido, esse campo é obrigatóriosendo preenchido quando a classificação tributária do empregador for igual a "22".
Code Block
themeEclipse
linenumberstrue
collapsetrue
{
   			"message": "Parâmetro 'identRubrqtdDiasAv' não informado ou está com o valor igual a zero.",
    		"code": "17006",
            "type": "error"
}
17006Parâmetro 'qtdDiasAv' não informado ou está com o valor igual a zero.Número da Matrícula INSS já está cadastrada para o Autônomo " 99999Verificar se a propriedade do json 'qtdDiasAvregistrationNumber' está sendo preenchido quando a classificação tributária do empregador for igual a "22".preenchido com o valor correto, pois na base de dados do RH já deve ter outro CPF usando a mesma Matrícula INSS
Code Block
themeEclipse
linenumberstrue
collapsetrue
{
   			"message": "ParâmetroNúmero 'qtdDiasAv'da nãoMatrícula informadoINSS ou está comcadastrada para o valorAutônomo igual" a zero99999.",
    		"code": "17006",
            "type": "error"
}
17006Número da Matrícula INSS já está cadastrada para o Autônomo " 99999Não encontrado o Processo Judicial:  55779911334466550123, informado no parâmetro 'nrProcJud'.Verificar se a propriedade do json 'RegistrationNumbernrProcJud' está  está preenchido com o valor correto, pois na base de dados do RH já deve ter outro CPF usando a mesma Matrícula INSStambém verificar o cadastro FP0030
Code Block
themeEclipse
linenumberstrue
collapsetrue
{
   			"message": "Número da Matrícula INSS já está cadastrada para o Autônomo " 99999.Não encontrado o Código Suspensão:  11 para o processo: 55779911334466550123",
    		"code": "17006",
            "type": "error"
}
56714Remuneração/Pagamento em período incorretoVerificar se a propriedade do json 'perApur' está com a data que se encaixe dentro da data da 3º fase cadastrada no FP0560.
Code Block
themeEclipse
linenumberstrue
collapsetrue
{
   			"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"
}
158Valor Dedução Dependente está diferente da tabela de IRF/INSS Geral do períodoVerificar se a propriedade do json 'vrDedDep' tem o valor correspondente ao cadastrado no FP2500 por dependente. O programa dividi o valor informado no Json pelo valor cadastrado no FP2500 para chegar na quantidade de dependentes de IR.
Code Block
themeEclipse
linenumberstrue
collapsetrue
{
   			"message": Informe um(a) valor dedução dependente válido(a). Está diferente da tabela de IRF/INSS Geral do período",
    		"code": "17006158",
            "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.