AllowanceControl - INTEGRAÇÃO PONA350API - Controle de Abonos

Sistemas Envolvidos

Protheus (módulo de Ponto Eletrônico): Módulo responsável pela gestão da assiduidade e marcações/apontamentos de horários de trabalho do funcionário, dentre outros cadastros pertinentes aos colaboradores.
Quírons - NG

Integração

O objetivo desta integração é permitir que o RH ou área responsável pelo Gestão de Pessoal do Protheus, receba os dados do Controle de Abono de marcações de ponto dos funcionários de outros sistemas especializados, reduzindo assim o trabalho de inclusão/alteração/exclusão manual dessas informações dentro do sistema;

Benefícios
- Não terá um investimento alto de tempo para o cadastramento, pois os dados já serão enviados, editados ou excluídos através da integração a cada requisição do sistema especialista através da API de Abono.
- A informação será atualizada de forma automática, facilitando que conferência e confiabilidade dos dados recebidos.

Arquitetura (Tecnologia)

Toda integração entre o Protheus e o Sistema é feita por intermédio de comunicação direta com os Web Services(que são fixos) REST(Representation State Transfer) utilizando o formato JSON(JavaScript Object Notation) de serialização de dados, onde através da ativação do serviço do REST do Protheus esteja disponível para utilizar o serviço.

Escopo

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

Manutenção de Lançamentos de Pré-Abono do funcionário no módulo SIGAPON;

Fora do escopo

Automatização de consultas de Abono,
Importação de base cadastral - dados do Funcionário,
Informações do Abono que não se enquadram dentro da tabela de Abono

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

Versões mínimas do Protheus: 12.1.23
Possuir acesso à Internet, caso o sistema que venha a utilizar a integração com a aplicação Protheus.
Estrutura de rede estável, para que haja tráfego de dados sem interrupção.
Protheus devidamente configurado e serviço Rest habilitado em seu server.

Instalação/Atualização

Este tópico tem por objetivo orientar a instalação da integração, visando o seu funcionamento completo.

Instalação de produtos ou ferramentas necessárias podem referenciar outros documentos existentes, desde que estejam disponíveis no repositório de documentação da TOTVS ou sejam enviados junto com o documento da integração em si.

As informações mínimas necessárias para este tópico são:

Ativação/Desativação da integração

Por padrão esta integração estará em repositório, porém demanda realizar a devida configuração conforme abaixo:

Configuração de Webservice Rest no Protheus no formato apresentado na seguinte documentação (Exemplo de Configuração de Webservice REST)

Controle de Ambiente

Exige que os seguintes pontos sejam revisados:

Protheus com sua arquitetura devidamente estruturada.
Módulo de Ponto Eletrônico (SIGAPON) com suas entidades base, devidamente populadas por dados que no momento da integração serão utilizados na criação do registro de abono. (Para melhor compreensão, analise o cadastro disponível dentro do sistema e verifique os campos que possuem consultas em outras tabelas se as mesmas estão com os seus dados devidamente cadastrados).

Controle de Versão

O grupo TOTVS, representado por suas marcas, irá administrar as demandas de evolução dos layouts 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 marcas antes do início do desenvolvimento e somente serão desenvolvidas em caso de concordância das marcas e alinhamento com as diretivas definidas pelo Comitê de Integração TOTVS.

Suporte

O suporte aos recursos da Integração será de responsabilidade da linha Protheus, onde será analisada pela equipe de suporte da Totvs.

Fluxo das Informações

Esta integração traz a funcionalidade exclusivamente à área de Ponto Eletrônico, no processo de cadastramento (inclusão/alteração/exclusão) de abonos de marcações de horário de ponto.

Cadastro

Esta integração contempla apenas o cadastramento(inclusão/alteração/exclusão) do Abono dentro do módulo SIGAPON.

Processos

O Sistema requisitante enviará as informações via json para a interface de integração, desta forma serão atualizados os dados de abono de marcações dentro do cadastro de pré abono no Protheus, caso tenha êxito na geração do registro, será retornada a mesma estrutura json recebida, acompanhada de uma nova tag chamada id, que será uma chave única composta de informações da entidade dentro do sistema. Desta forma será confirmada sua gravação, caso contrário enviará as informações de inconsistências que serão 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á o registro individual de cada registro de Abono.

Como realizar a chamada da API REST

Para realizar a integração com o parceiro TOTVS são necessárias as informações básicas de consulta para retorno do funcionário desejado.

Preenchimento do EndPoint da API PONA350API;
Utilizar a chamada do método Post, Put e Delete e do Serviço AllowanceControl;
Preenchimento dos parâmetros obrigatórios da API.

Totvs custom tabs box

tabs	POST,PUT,DELETE
ids	POST,PUT,DELETE

Totvs custom tabs box items

default	no
referencia	POST

Parâmetros de Entrada POST:

Parâmetro

Valor de Exemplo

Obrigatório

Tipo

Valor Default

Descrição

authorization

usuario:senha

Sim

header

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

content

{
"companyId":"T1",
"branchId": "D MG 01 ",
"employeeId":"T1|D MG 01 |160001",
"code": "T1|D MG |114",
"startDate": "2020-06-02T10:10:10",
"endDate": "2020-06-10T10:10:10",
"startTime": "10:10",
"endTime": "19:10"
}

sim

body

Estrutura json com informações do abono de marcações do funcionário:

Dados de preparação de ambiente:

companyId: Grupo de empresa
branchId: Empresa+Unidade de negócio+Filial

Dados de Abono:

employeeId: Informação pertinente ao funcionário.
startDate: Data do Início do abono.
endDate: Data do Final do abono.
startTime: Hora do Início do abono.
endTime: Hora do Final do abono.
code: Tipo de Abono registrado.

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 a API Rest, a requisição deverá ser semelhante a imagem abaixo:

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

Dados utilizados da API

Por ser uma estrutura única para todas as linhas, cada linha utilizará os campos pertinentes aos seus ambientes.

Propriedade API REST	CAMPO PROTHEUS	DESCRIÇÃO	Formato
companyId		Informações de acesso ao sistema, campo contém informação do grupo de empresa	"T1"
branchId	RF0_FILIAL	Informações de acesso ao sistema, campo compõe Empresa+Unidade de Negócio+ Filial	"D MG 01 "
employeeId	RF0_MAT	chave do Funcionário	"T1\|D MG 01 \|000001""
startDate	RF0_DTPREI	Data inicial do abono	"2020-01-01T18:25:43"
endDate	RF0_DTPREF	Data final do abono	"2020-01-01T18:25:43"
startTime	RF0_HORINI	hora inicial do abono	"10:00"
endTime	RF0_HORFIM	hora final do abono	"15:00"
code	P6_CODIGO	chave do tipo de abono	"T1\| D MG \| 107"

Situações Tratadas

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.

Mensagens Validação

Erro

Mensagem

Solução

API RESPONSE

201

Created.

Registro incluído com sucesso.

Bloco de código

theme	Eclipse
linenumbers	true
collapse	true

"companyId":"T1",
"branchId": "D MG 01 ",
"employeeId":"T1|D MG 01 |160001",
"code": "T1|D MG |114",
"startDate": "2020-06-02T10:10:10",
"endDate": "2020-06-10T10:10:10",
"startTime": "10:10",
"endTime": "19:10",
"id": "T1;D MG 01 ;T1|D MG 01 |160001;2020-06-03T13:00:00.000Z;10:10;T1|D MG|107"

400

Erro no momento da listagem do registro.

Verificar se as propriedade json startDate está preenchida e com dados válidos no pacote enviado .

Bloco de código

theme	Eclipse
linenumbers	true
collapse	true

{
    "code": 400,
    "detailedMessage": "Verifique o conteúdo da TAG (startDate) pois a data não está no formato correto: 'YYYY-MM-DDTHH:MM:SS'\r\n",
    "helpUrl": "https://tdn.totvs.com/x/ZYNvI",
    "message": "Erro na validação do recebimento da mensagem."
}

500

Erro no acesso ao Endpoint.

É necessário avaliar se o servidor está funcionando corretamente.

Bloco de código

theme	Eclipse
linenumbers	true
collapse	true

{
    "code": 500,
    "detailedMessage": "Ocorreu uma falha no retorno da informação.",
    "helpUrl": "https://tdn.totvs.com/x/ZYNvI",
    "message": Descrição do erro.
}

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, vale lembrar que são apenas exemplos de mensagens de erros e podendo variar o nome da propriedade enviada.

Totvs custom tabs box items

default	no
referencia	PUT

Parâmetros de Entrada PUT:

Parâmetro	Valor de Exemplo	Obrigatório	Tipo	Valor Default	Descrição
authorization	usuario:senha	Sim	header		autenticação é importante para o funcionamento correto da API em casos de ambientes com autenticação Http Basic.
allowanceId	T1;D MG 01 ;T1\|D MG 01 \|160001;2020-06-03T13:00:00.000Z;10:10;T1\|D MG\|107	Sim	request		Composição da string a ser enviada, deve ser ser composta por "GRUPO DE EMPRESA;FILIAL;CHAVEFUNCIONARIO;DATADEINÍCIO;HORADEINICIO;CHAVE TIPODEABONO".
content	layout json	sim	body		Estrutura json com informações do abono de marcação de ponto: *Dados de preparação de ambiente:* companyId: Grupo de empresa branchId: Empresa+Unidade de negócio+Filial *Dados de solicitação de abono:* employeeId: Informação pertinente ao funcionário. startDate: Data inicial do abono. endDate: Data final do abono. startTime: Horário do Início do abono. endTime: Horário do final do abono. code: Tipo de abono registrado.

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 a API Rest, a requisição deverá ser semelhante a imagem abaixo:

{protocolo}://{host}/{api}/rh/v1/allowanceControl{allowanceId}

Dados utilizados da API

Por ser uma estrutura única para todas as linhas, cada linha utilizará os campos pertinentes aos seus ambientes.

Propriedade API REST	CAMPO PROTHEUS	DESCRIÇÃO	Formato
companyId		Informações de acesso ao sistema, campo contém informação do grupo de empresa	"T1"
branchId		Informações de acesso ao sistema, campo compõe Empresa+Unidade de Negócio+ Filial	" D MG 01 "
employeeId	RF0_MAT	chave do Funcionário.	"T1\|D MG 01 \|000001"
startDate	RF0_DTPREI	Data de Início do abono	"2020-01-01T18:25:43"
endDate	RF0_DTPREF	Data do Final do abono	"2020-01-01T18:25:43"
startTime	RF0_HORINI	Hora inicial do abono	"10:00"
endTime	RF0_HORFIM	Hora final do abono	"15:00"
code	P6_CODIGO	chave do tipo de abono	"T1\|D MG \|107"

Situações Tratadas

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.

Mensagens Validação

Erro

Mensagem

Solução

API RESPONSE

200

Atualizado com sucesso.

Registro alterado com sucesso.

Bloco de código

theme	Eclipse
linenumbers	true
collapse	true

"companyId":"T1",
"branchId": "D MG 01 ",
"employeeId":"T1|D MG 01 |160001",
"code": "T1|D MG |114",
"startDate": "2020-06-02T10:10:10",
"endDate": "2020-06-10T10:10:10",
"startTime": "10:10",
"endTime": "19:10",
"id": "T1;D MG 01 ;T1|D MG 01 |160001;2020-06-03T13:00:00.000Z;10:10;T1|D MG|107"

400

Erro no momento da listagem do registro.

Verificar se as propriedade json allowanceId está preenchida e com dados válidos no pacote enviado .

Bloco de código

theme	Eclipse
linenumbers	true
collapse	true

{
    "code": 400,
    "detailedMessage": "Informação allowanceId ausente ou inválida.",
    "helpUrl": "https://tdn.totvs.com/x/ZYNvI",
    "message": "Erro na validação do recebimento da mensagem."
}

500

Erro no acesso ao Endpoint.

É necessário avaliar se o servidor está funcionando corretamente.

Bloco de código

theme	Eclipse
linenumbers	true
collapse	true

{
    "code": 500,
    "detailedMessage": "Ocorreu uma falha no retorno da informação.",
    "helpUrl": "https://tdn.totvs.com/x/ZYNvI",
    "message": Descrição do erro.
}

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, vale lembrar que são apenas exemplos de mensagens de erros e podendo variar o nome da propriedade enviada.

Totvs custom tabs box items

default	no
referencia	DELETE

Parâmetros de Entrada DELETE:

Parâmetro	Valor de Exemplo	Obrigatório	Tipo	Valor Default	Descrição
authorization	usuario:senha	Sim	header		autenticação é importante para o funcionamento correto da API em casos de ambientes com autenticação Http Basic.
allowanceId	"T1;D MG 01 ;T1\|D MG 01 \|160001;2020-06-03T13:00:00.000Z;10:10;T1\|D MG\|107"	Sim	query		Composição da string a ser enviada, deve ser ser composta por "GRUPO DE EMPRESA;FILIAL;CHAVEFUNCIONARIO;DATADEINÍCIO;HORADEINICIO;CHAVE TIPODEABONO".

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 a API Rest, a requisição deverá ser semelhante a imagem abaixo:

{protocolo}://{host}/{api}/rh/v1/allowanceControl{allowanceId}

Situações Tratadas

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.

Mensagens Validação

Erro

Mensagem

Solução

API RESPONSE

204

Atualizado com sucesso.

Registro foi deletado com sucesso.

Bloco de código

theme	Eclipse
linenumbers	true
collapse	true

{
        "code":  "204200",
        "description":  "ATUALIZADOOpera��o realizada COMcom SUCESSO.sucesso!"
}

400

Erro no momento da listagem do registro.

Verificar se a propriedade json allowanceId está preenchida e com dados válidos no pacote enviado .

Bloco de código

theme	Eclipse
linenumbers	true
collapse	true

{
    "code": 400,
    "detailedMessage": "Informação allowanceId ausente ou inválida.",
    "helpUrl": "https://tdn.totvs.com/x/ZYNvI",
    "message": "Erro na validação do recebimento da mensagem."
}

500

Erro no acesso ao Endpoint.

É necessário avaliar se o servidor está funcionando corretamente.

Bloco de código

theme	Eclipse
linenumbers	true
collapse	true

{
    "code": 500,
    "detailedMessage": "Ocorreu uma falha no retorno da informação.",
    "helpUrl": "https://tdn.totvs.com/x/ZYNvI",
    "message": Descrição do erro.
}

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

Páginas filhas

Versões comparadas

Versão antiga 21

Nova versão 22

Chave

AllowanceControl - INTEGRAÇÃO PONA350API - Controle de Abonos

Sistemas Envolvidos

Integração

Escopo

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

Instalação/Atualização

Ativação/Desativação da integração

Controle de Ambiente

Controle de Versão

Suporte

Fluxo das Informações

Limitações / Restrições Gerais

Como realizar a chamada da API REST

Parâmetros de Entrada POST:

Situações Tratadas

Parâmetros de Entrada PUT:

Situações Tratadas

Parâmetros de Entrada DELETE:

Situações Tratadas

Checklist de suporte da aplicação

Anexos

Páginas filhas

Histórico da Página

Versões comparadas

Versão antiga 21

Nova versão 22

Chave

AllowanceControl - INTEGRAÇÃO PONA350API - Controle de Abonos

Sistemas Envolvidos

Integração

Escopo

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

Instalação/Atualização

Ativação/Desativação da integração

Controle de Ambiente

Controle de Versão

Suporte

Fluxo das Informações

Limitações / Restrições Gerais

Como realizar a chamada da API REST

Parâmetros de Entrada POST:

Situações Tratadas

Parâmetros de Entrada PUT:

Situações Tratadas

Parâmetros de Entrada DELETE:

Situações Tratadas

Checklist de suporte da aplicação

Anexos