Cada vez mais o mercado exige que as operações complexas e manipulação de dados sejam ainda mais ágeis e intuitivas. Neste contexto, surgiu a necessidade da criação de uma interface que possibilite automatizar o envio dos dados das empresas para o governo,de forma rápida, clara e sem que o cliente necessite adquirir um módulo adicional do sistema. Desta forma, o desenvolvimento de um Monitor de Eventos foi necessário para a entrega das obrigações fiscais das empresas para o governo, de modo que as informações que trafegam nele possam ser enviadas em lotes de eventos e depois consultados através de relatórios específicos para cada tipo de serviço.
A utilização do Middleware, como interface de comunicação, possibilitou maior segurança e velocidade de acesso às informações, já que se utilizam de APIs REST na troca de dados. O novo visual do Monitor THF também foi outro passo importante na questão da usabilidade do cliente, que passou a realizar o envio dos eventos fiscais com um número menor de passos e de forma mais intuitiva.
De modo geral, o eSocial do futuro simplifica os processos de seus clientes, em relação ao cumprimento de suas obrigações fiscais, o tornando mais seguro, simples e rápido.
Maiores informações podem ser acessadas em: https://tdn.totvs.com/x/oaT9Hw.
O objetivo desta integração é permitir que o Monitor THF, consiga efetuar a exibição dos registros do card do evento selecionado pelo usuário.
Por intermédio desta integração será disponibilizada a seguinte funcionalidade:
Fora do escopo
Para utilizar a integração será necessário realizar a devida configuração do Webservice Rest no Protheus, com o formato apresentado na seguinte documentação: Exemplo de Configuração de Webservice REST.
Exige que os seguintes pontos sejam revisados:
O grupo TOTVS, representado por suas marcas, irá administrar as demandas de evolução dos leiautes e demais ajustes, acordando junto aos solicitantes o prazo de liberação de release.
Todas as evoluções programadas deverão ser discutidas e aprovadas pelas áreas antes do início do desenvolvimento e somente serão desenvolvidas em caso de concordância das áreas e alinhamento com as diretivas definidas pelo contrato de Integração.
O suporte aos recursos da Integração será de responsabilidade da linha Microsiga Protheus, onde será analisada pela equipe de suporte da TOTVS.
Esta integração traz a funcionalidade exclusivamente da exibição do detalhamento do Card.
Esta integração contempla apenas a consulta do detalhamento do Card.
O Monitor THF, realizará o consumo da API com dados básicos que serão utilizados como parâmetros para efetuar a transmissão do registro s e retornar um conjunto de informações para o requisitante.
Para realizar a integração é necessário passar informações básicas de consulta para retorno das filiais, são elas:
As Entradas e Saídas de dados tipo data (Date) acompanham o formato padrão YYYY-MM-DDThh:mm
Parâmetros
Parâmetro | Valor de Exemplo | Obrigatório | Tipo | Parâmetro | Valor Default | Descrição |
companyCode | T2|L MG 01 | Sim | Array | query | Código da empresa | |
branchCode | L MG 01 | Sim | String | query | Código da Filial | |
id | a272680e-35d2-4cbb-9351-745c44d7cd86 | Não | String | query | Id da requisição | |
eventCode | S-1200 | Sim | String | query | Código do evento | |
period | 2020/03 | Não | String | query | Período | |
status | 1 | Não | String | query | status | |
userId | admin | Não | String | query | userId |
Parâmetros e Chamada do Método:
Parâmetros e Chamada do Método:
Para a realização de testes foi utilizado a ferramenta POSTMAN e após a configuração do server Protheus com o serviço API Rest, a requisição deverá ser semelhante a imagem abaixo:
Estrutura: { protocolo } : // { endereço servidor Rest } : { Porta Rest } / rest / api / rh / { versão } / GPEEsocialDetailTransmission /
Exemplo: http://localhost:8060/rest/api/rh/esocial/v1/GPEEsocialDetailTransmission/
Retorno da API:
{ "finished":true, "percent":100, "header":[ { "property":"status", "label":"Status", "type":"string" }, { "property":"code", "label":"Código", "type":"string" }, { "property":"description", "label":"Descrição", "type":"string" } ], "items":[ { "item":{ "key":"103", "columns":[ { "property":"status", "value":"Pendente de envio" }, { "property":"code", "value":"103" }, { "property":"description", "value":"Salário Bruto" } ], "hasError":true } }, { "item":{ "key":"104", "columns":[ { "property":"status", "value":"Pendente de envio" }, { "property":"code", "value":"104" }, { "property":"description", "value":"Salário Bruto" } ], "hasError":false } } ] } |
Informações das propriedades de retorno da API:
PROPRIEDADES API REST | DESCRIÇÃO |
---|---|
finished | Indica se a transmissão foi concluída |
percent | Percentual de transmissão |
header | Lista com a estrutura do retorno |
property | Nome da propriedade |
label | Descrição |
type | Tipo do conteúdo |
items | Lista com os items |
item | Lista de propriedades |
key | Id de identificação do registro |
hasError | Indica se o registro retornou erro |
columns | Lista com as propriedades do retorno |
property | Nome da propriedade do retorno |
value | Valor da propriedade do retorno |
Nos retornos as informações são obtidas da tabela RJE.
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 Protheus:
Mensagens de Pré-Validação
CÓDIGO DO ERRO | MENSAGEM | SOLUÇÃO | RETORNO DA API | |
400 | O parâmetro 'companyId' é obrigatório e não foi informado. | Realizar o preenchimento do parâmetro companyId. |
| |
400 | O parâmetro 'branches' é obrigatório e não foi informado. | Realizar o preenchimento do parâmetro branches. |
| |
400 | O parâmetro 'eventCode' é obrigatório e não foi informado. | Realizar o preenchimento do parâmetro eventCode. |
| |
500 | Ocorreu uma falha no retorno da informação. Falha ao Inicializar o Ambiente com os dados informados! Saída no final: O arquivo SX2TX0 não existe. | Rever os valores preenchidos no parâmetro companyId. |
|
Itens a serem verificados durante o atendimento: