Integrações

Integrando com a solução de Marcação de Ponto 2.0 | HCM

94 views 01/09/2020 14/09/2020 daniel-huebes 1

A solução Marcação de Ponto 2.0 | HCM permite integração com aplicações de terceiros através de suas APIs públicas.

Desta forma é possível alimentar a solução com os dados de entrada necessários e consumir as informações geradas.

SOBRE O TUTORIAL

Neste tutorial vamos exemplificar as chamadas das APIs necessárias para inserir todas as informações necessárias da solução e como consumir as informações geradas.

PRÉ CONDIÇÕES

  • Tenant na plataforma senior X
  • Usuário administrador do tenant
  • Cliente para chamadas de API

Obs: Para realizar as chamadas as APIs é necessário estar autenticado, ou seja, possuir um token de autenticação para realizar as chamadas, este token deve ser enviado em todas as chamadas para APIs protegidas.

PREPARANDO OS DADOS

Para fazer a importação dos dados utilizaremos as APIs blobServiceRequestUploadFile, blobServiceCommitUploadedFile e employeesImportById.

Estes endpoints necessitam de um arquivo contendo as informações dos colaboradores a serem enviados para a solução, o arquivo deve ser salvo com a extensão TMP e conter um objeto JSON com as seguintes informações:

  • Uma lista de colaboradores identificada como employees
  • Objetos dos colaboradores contendo as informações pertinentes
    • PIS
    • E-mail
    • Nome
    • Identificador externo
    • Gestores
      • Nome
      • E-mail
    • Usuários da plataforma
      • Nome de usuário

Para mais informações sobre esses dados consulta a documentação do sistema aqui: https://documentacao.senior.com.br/seniorxplatform/manual-do-usuario/hcm/#marcacao-de-ponto/dados-de-entrada-e-saida.htm

Exemplo:

{
    "employees": [
        {
            "pis": "01234567890",
            "mail": "colaborador@tenant.com.br",
            "name": "Colaborador",
            "company": {
                "cnpj": "01234567890123",
                "name": "Unidade de negócio"
            },
            "managers": [{
                "mail": "gestor@tenant.com.br",
                "platformUsers" :[{
                       "username": "gestor"
                }]            }],
            "externalId": "1-1-1",
            "platformUsers": [
                {
                    "username": "colaborador"
                }
            ]        },
        {
            "pis": "12345678901",
            "mail": "colaborador2@tenant.com.br",
            "name": "colaborador2",
            "company": {
                "cnpj": "01234567890123",
                "name": "Unidade de negócio"
            },
            "managers": [{
                "mail": "gestor1@tenat.com.br",
                "platformUsers" :[{
                       "username": "gestor1"
                },{
                       "username": "gestor11"
                }]            }],
            "externalId": "1-1-2",
            "platformUsers": [
                {
                    "username": "colaborador2"
                },{
                    "username": "colaborador22"
                }
            ]        }      
    ]}

 

IMPORTANDO COLABORADORES

Passo 1:

Para realizar a importação dos colaboradores inicialmente realizamos a chamada a API BlobServiceRequestUploadFile informando o nome do arquivo contendo os colaboradores, chamaremos de employees.tmp.

URI
https://platform.senior.com.br/t/senior.com.br/bridge/1.0/rest/hcm/pontomobile/actions/blobServiceRequestUploadFile
Método
POST
HTTP Headers
Content-Type: application/json
Body
{
"fileName": "employees.tmp"
}

Com o retorno da primitiva, termos o identificador do arquivo, a versão e a URI para qual devemos realizar o upload do arquivo

{
"fileId":"9A99ED188CFE47C381AECB6026D32E74/employees.tmp",
 "version":"version-2653f4b0-3c12-427a-b214-4ea080d38806",
"locationURI": "https://br-com-senior-blob-service-storage.s3.sa-east-1.amazonaws.com/<tenant>/temp/hcm/pontomobile/version-a8dac20f-6753-4a2a-a9b4-75c11d3ea960/employees2.tmp?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20200826T140016Z&X-Amz-SignedHeaders=host&X-Amz-Expires=1440&X-Amz-Credential=AKIA3KDZUIYAVDKFSV7P%2F20200826%2Fsa-east-1%2Fs3%2Faws4_request&X-Amz-Signature=83cb5204c380f3c395b2f3c6de9681ba5f42cb63f8c04d72aec48e118b6eb6f0"
}
 
Passo 2:

Executar uma chamada put para o endereço recebido no endpoint acima na propriedade locationURI, com o conteúdo do arquivo.

 URI
https://br-com-senior-blob-service-storage.s3.sa-east-1.amazonaws.com/<tenant>/temp/hcm/pontomobile/version-a8dac20f-6753-4a2a-a9b4-75c11d3ea960/employees2.tmp?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20200826T140016Z&X-Amz-SignedHeaders=host&X-Amz-Expires=1440&X-Amz-Credential=AKIA3KDZUIYAVDKFSV7P%2F20200826%2Fsa-east-1%2Fs3%2Faws4_request&X-Amz-Signature=83cb5204c380f3c395b2f3c6de9681ba5f42cb63f8c04d72aec48e118b6eb6f0
Método
PUT
Body
Arquivo a ser importado
 
Passo 3:

Após o retorno com HTTP status 201 da chama PUT de upload do arquivo confirmaremos o arquivo na plataforma através do endpoint blobServiceCommitUploadedFile para que o mesmo fique salvo na plataforma e possa ser consumido pela solução e processado.

URI
https://platform.senior.com.br/t/senior.com.br/bridge/1.0/rest/hcm/pontomobile/actions/blobServiceCommitUploadedFile
Método
POST
HTTP Headers
Content-Type: application/json
Body
{
"fileId":"9A99ED188CFE47C381AECB6026D32E74/employees.tmp",     "version":"version-2653f4b0-3c12-427a-b214-4ea080d38806"
}
 
Passo 4:

Por fim chamamos a primitiva employeesImportById para realizar a importação dos dados, passando o id do arquivo enviado para plataforma.

URI
https://platform.senior.com.br/t/senior.com.br/bridge/1.0/rest/hcm/pontomobile/actions/employeesImportByFileId
METHOD
POST
HTTP Headers
Content-Type: application/json
Body
{      
"fileId":"9A99ED188CFE47C381AECB6026D32E74/employees.tmp"
}

Após a importação bem sucedida, os colaboradores estarão disponíveis na solução para serem utilizados para marcação de ponto. Os colaboradores podem ser visualizados na tela de Colaboradores na plataforma seniorX.

Importante

Vale ressaltar que a inclusão dos colaboradores não é incremental, caso ao realizar o processo de importação dos colaboradores já exista colaboradores importados previamente, todos os colaboradores existentes serão inativados e não terão mais acesso as funcionalidades do aplicativo para o celular ou da plataforma para realizar a batida de ponto. Sendo assim o json deve sempre conter uma lista de colaboradores que serão os utilizadores da solução.

 

RECUPERANDO MARCAÇÕES

Para recuperar as marcações de ponto realizadas através da solução iremos utilizar a API ClockingEventExport. Este endpoint irá resgar todas as marcações que não foram lidas em chamadas anteriores, armazenar em um arquivo e sinalizar todas as marcações exportadas desta maneira como lidas. O Arquivo retornado será um TXT com informações referentes as batidas, seguindo um [padrão proprietário] da Senior.

URI
https://platform.senior.com.br/t/senior.com.br/bridge/1.0/rest/hcm/pontomobile/actions/clockingEventExport
Método
POST
Retorno esperado
{
"locationURI": " https://br-com-senior-blob-service-storage.s3.sa-east-1.amazonaws.com/<tenant>/temp/hcm/pontomobile/89ceab09-7eb0-3407-97f5-0b3300693971/MOB_26082020134412.txt"
}

O retorno será uma URI para download do arquivo.

Após a geração do arquivo com as marcações, devido a elas terem sido sinalizadas como lidas, as chamadas subsequentes retornaram apenas novas marcações de ponto que ainda não foram sinalizadas como lidas.

Para recuperar marcações em períodos específicos, caso necessário, utilizamos a API ClockingEventExportByPeriod, onde passamos um período igual ou inferior a 31 dias para recuperar as marcações. Além do período informamos o tipo de arquivo que desejamos receber, se será um TXT ou um CSV e se gostaríamos de receber as informações de geolocalização.

 

URI
https://platform.senior.com.br/t/senior.com.br/bridge/1.0/rest/hcm/pontomobile/actions/clockingEventExportByPeriod
Método
POST
HTTP Headers
Content-Type: application/json
Body:
{
  "period": {
    "initialDate": "2020-08-01",
    "finalDate": "2020-08-28",
    "initialTime": "00:00",
    "finalTime": "23:59"
  },
  "fileType": "CSV",
  "exportGeolocation": "false"
}
Retorno
{
"locationURI": "https://br-com-senior-blob-service-storage.s3.sa-east-1.amazonaws.com/<tenant>/temp/hcm/pontomobile/cd9debcc-2088-3ae6-9691-4d69897070e6/MARCACOES_26082020135641.zip"
}

O retorno será uma URI para download do arquivo.

 

Este artigo foi útil para você?