Como fazer uma integração via API com o software de DP da Sólides?

Confira todos os passos para desenvolvedores integrarem o seu próprio sistema à solução de DP da Sólides.

Neste artigo, você entenderá:

1. Por onde começar?
2. O que é o Swagger?
3. Como iniciar teste?
4. Como integrar os cadastros básicos?
5. Como integrar a API de ajuste de ponto?
6. Como acessar informações da folha de ponto?

1. Por onde começar?

Token de acesso

Primeiro, para utilizar nossas APIs, é preciso obter o token de acesso. Com o token de integração é possível conectar a sua aplicação com a solução de DP da Sólides.

Para isso, será necessário solicitar a liberação do token de integração com o suporte da Sólides, por meio do chat exclusivo para clientes, disponível aqui na Central de Ajuda. Feito isso, siga para os passos:

• Faça login na plataforma web da solução para DP da Sólides.
• No menu lateral, clique em Empregador e escolha a opção Integrações. 

Utilizamos o padrão JWT de autenticação com Basic Authorization, sendo assim, toda requisição precisa ser feita com o header param Authorization: Basic seu_token.

2. O que é o Swagger?

Aqui na Sólides utilizamos o Swagger, que é uma ferramenta para mapear toda a nossa API e te ajudar a construir a estrutura de dados para cada endpoint, bem como executar testes para entender na prática como funciona cada endpoint da nossa API.

Caso tenha mais interesse nesta ferramenta, acesse: Modelando APIs REST com Swagger.

Acesse a nossa API.

3. Como iniciar teste?

Agora que você já possui um token e já deu uma olhada em nosso Swagger, podemos executar um primeiro teste.

Primeiro teste

Será necessário inserir o token de acesso.

• Clique no botão localizado acima da lista de APIs disponíveis, como na imagem abaixo.
  
  

  Feito isso, será aberta uma janela na qual você tem a possibilidade de inserir o token que foi adquirido pelos meios indicados acima. Após confirmação, todas as rotas poderão ser acessadas usando o token como referência.

Iniciando o teste

• Localize a API test-controller no Swagger.

• Clique em [Try it out].

• Execute a requisição e você receberá uma resposta da API com a mensagem "Hello, [seu_nome]."

Depois desses passos, você já estará apto a implementar essa requisição de teste dentro do seu próprio sistema, onde irá ocorrer as integrações.

4. Como integrar os cadastros básicos?

Você pode integrar algumas consultas e cadastros básicos dentro do sistema Sólides, mas, primeiramente, preste atenção nestes quatro conceitos:

1. Todo registro possui o atributo id que é auto-increment e gerenciado pela própria Sólides, então, quando for cadastrar algo novo, não é necessário preencher o atributo "id" no json.
2. Algumas entidades possuem o atributo externalId, que pode ser usado opcionalmente para identificar um registro com seu próprio identificador.
3. Todo endpoint de listagem "find-all" possui o padrão de registros paginados onde você poderá utilizar os Query Params page (página corrente) e size (tamanho da página).
4. Nossos atributos de data/hora são mapeados em milisegundos.

Cargo

Localize a API job-role-controller no Swagger e abra o endpoint POST /job-role/register. Observe que o Body desta requisição é um objeto chamado JobRoleDTO que possui vários atributos. Porém, para cadastrar um novo cargo vamos utilizar apenas dois atributos, sendo opcional o "externalId".

• Clique em [Try it out].
• Cole seu token no campo Authorization.
• Cole o seguinte json no campo (body) jsonRoleDTO:

Execute a requisição e pronto! O seu novo cargo será registrado e estará disponível para ser associado aos colaboradores.

Observe que a resposta da requisição POST retornou o json acrescido do atributo "id", que no momento do cadastro foi autogerado pelo Tangerino.

Você pode utilizar esse id interno da Sólides ou o seu próprio externalId para consultar o registro através do endpoint GET /job-role/find.

Além disso, você também pode  consultar todos os seus cargos cadastrados por meio do endpoint GET /job-role/find-all que contem uma lista paginada dos registros.

Local de trabalho/setor

Localize a API workplace-controller no Swagger e abra o endpoint POST /workplace/register.

• Clique em [Try it out].
• Cole seu token no campo Authorization.
• Cole o seguinte json no campo (body) jsonRoleDTO:

Agora, execute a requisição e pronto! O seu novo Local de trabalho será  registrado e estará disponível para ser associado aos colaboradores.

Observe que a resposta da requisição POST retornou o json acrescido do atributo "id", que no momento do cadastro foi autogerado pelo Tangerino.

Você pode utilizar esse id interno da Sólides ou o seu próprio externalId para consultar o registro através do endpoint GET /workplace/find.

Além disso, você pode também consultar todos os seus cargos cadastrados através do endpoint GET /workplace/find-all que contem uma lista paginada dos registros.

Escala de trabalho

As escalas de trabalho devem ser cadastradas pela plataforma web. Porém, você precisará sincronizá-las em seu sistema para posteriormente associá-las em seus respectivos colaboradores.

Localize a API work-schedule-controller e abra o endpoint GET /work-schedule.

Este endpoint também serve para consultar todos os registros paginadamente, porém, se trata de um objeto um pouco mais complexo, então vamos observar este exemplo:

• O atributo standard serve para verificar se esta é a escala padrão da sua conta.

• A lista "workScheduleTimetableList" representa os horários desta escala onde o atributo "day" define o dia da semana sendo 1 = Domingo, 2 Segunda, [...] e 7 = Sábado.

• Em uma jornada de trabalho podemos ter dois turnos (dividida pela pausa pro almoço/jantar) por isso temos os atributos (data/hora) startShift1, endShift1, startShift2 e endShift2 que vão definir efetivamente os horários dessa escala em seus respectivos dias.

Colaborador

Agora você poderá finalmente cadastrar um novo colaborador!

Localize o employee-controller e vamos ao POST /employee/register.

Agora, vamos cadastrar  um colaborador inserindo o json no body employeeDTO.

Observe que você precisa informar o id de algum local de trabalho (workplace) e a escala (workSchedule) que cadastramos anteriormente.

Ótimo! Execute a requisição e o novo colaborador será cadastrado na Sólides.

Um detalhe importante: é no retorno desse endpoint, onde temos o json do colaborador cadastrado detalhadamente, incluindo o atributo "pin" já possibilita o registro de ponto do novo colaborador.

Fuso horário/time zone

Usamos o exemplo de cadastro de um colaborador  no fuso horário de São Paulo.

Entretanto, diversos fusos horários podem ser cadastrados na Sólides. Confira abaixo a lista de horários suportada:

Gestor

Na solução de DP da Sólides, um determinado colaborador pode ser cadastrado como gestor de outros colaboradores.

Para isto, localize a API manager-controller no Swagger e abra o endpoint POST /manager/register.

Agora, definiremos o colaborador como gestor inserindo o json no body managerDTO.

Também é possível usar a lógica dos ids externos passando o json dessa forma:

• O atributo recordsPunch serve para definir se o gestor será isento ou não de bater ponto.

• O atributo allowChangePunch serve para definir se o  gestor poderá editar pontos.

• O atributo allowExcludePunch serve para definir se esse gestor poderá excluir pontos.

5. Como integrar a API de ajuste de ponto?

A Sólides permite fazer ajustes nos pontos. Nossa API de ajuste de ponto serve para lançar folgas, atestados, férias e outros tipos de ajustes.

Localize a API adjustment-reason-controller, abra e execute o endpoint GET /adjustment-reason/find-all.

Executando esse endpoint teremos um retorno com a lista de motivos de ajuste de ponto, para que você possa lançar futuramente as férias de um colaborador, por exemplo.

Lançamento de férias

Observe que no endpoint GET /adjustment-reason/find-all foi retornado um "motivo de ajuste" FÉRIAS. Usaremos esse  objeto para lançar férias ao colaborador cadastrado anteriormente.

Localize a API adjustment-reason-record-controller e abra o endpoint POST /adjustment/register.

No body desta requisição usaremos o seguinte json:

Repare que colocamos o objeto FÉRIAS no atributo "adjustmentReasonDTO", porém, só é necessário informar o atributo "id". A, description serve somente para facilitar o  entendimento.

O mesmo acontece com o objeto "employeeDTO" onde se pode passar tanto "id" (tangerinoID) quanto "externalId" que seria seu próprio identificador para o colaborador.

"startDate" e "endDate" definem o período que o  colaborador estará em férias.

"status" pode ser integrado com as seguintes opções: APROVADO, PENDENTE, REPROVADO.

Lançamento de ajustes

Exatamente da mesma forma que vimos no lançamento de férias, podemos lançar qualquer motivo de ajuste conforme a lista de opções obtidas em GET /adjustment-reason/find-all.

Lançamento de pontos em atraso

Eventualmente será preciso lançar pontos com data passada, principalmente, por esquecimento do próprio colaborador. Nesse caso, disponibilizamos uma API onde é possível lançar um ponto em atraso, porém, daremos sequência em outro módulo da API de integração .

Antes de lançar um ponto em atraso você precisará escolher uma justificativa, então entenda como listar as opções.

Localize a API manual-editing-justification-controller e execute o endpoint GET /manual-editing-justification-punch.

Você receberá uma lista de possíveis justificativas, como esse exemplo:

Agora, você poderá lançar um ponto em atraso com sua respectiva justificativa.

Localize a API punch-controller e execute o endpoint POST /register/late/1.1.

No body desta requisição usaremos o seguinte json:

• Como nos demais serviços, o atributo employeeId pode ser substituído por externalId.

• O atributo date não terá o padrão de milisegundos, pois precisamos saber em qual timezone será registrado esse ponto, sendo assim, siga o padrão 'yyyy-MM-dd'T'HH:mm:ss.SSSZ'. Repare também que não há divisão para data de entrada e saída, pois, quando se trata de uma marcação de ponto, esta se refere a um momento único e o próprio Tangerino internamente organizará as marcações para identificar 'entradas' e 'saídas'.

6. Como acessar informações da folha de ponto?

Após passar por todos os cadastros, deixando os colaboradores aptos a bater ponto pela Sólides, você precisará consultar as informações de ponto dos colaboradores. Conheça algumas APIs para consulta de pontos e até mesmo para gerar uma folha de ponto.

Consulta de pontos

Dando sequência, na API punch-controller, localize o endpoint GET /.

Este é o endpoint onde se pode consultar todos os pontos da sua empresa paginadamente, e com possibilidade de alguns filtros, como você poderá ver pelo Swagger.

Caso queira manter todos os pontos em sua própria base de dados, basta usar o query paramlastUpdate na requisição desse endpoint, onde poderá agendar uma rotina de busca dos pontos, passando sempre a data da última vez em que foi feita a requisição para retornar apenas os novos pontos registrados, desde então.

Outra forma de usar essa consulta é passando um intervalo de datas startDate e endDate podendo ainda filtrar por colaborador através do parâmetro employeeId.

Histórico de observações

Cada ponto possui um histórico de observações e, no sistemo Sólides Ponto, podemos buscá-los separadamente.

Localize o endpoint GET /observation-historical e veja como é simples usá-lo. Você pode usar um intervalo de datas startDate e endDate (em milisegundos) para listar todo o histórico desse período e, opcionalmente, pode-se passar o query param punchId para trazer o histórico de observações específico de um ponto.

Emissão da folha de ponto

Finalmente poderemos emitir uma folha de ponto através do endpoint GET /time-sheet. Acesse o novo módulo.

Temos praticamente os mesmos filtros na tela de Relatório de folha de ponto da plataforma Web da soluçaõ de DP da Sólides. Veja:

O retorno desta API terá o seguinte formato:

No atributo base64FileContent virá uma string com o conteúdo do arquivo em Base64.

Pronto! Você aprendeu todos os passos e poderá usar todas as vantagens das integrações com o Sólides Ponto.

Qualquer dúvida, entre em contato com o e-mail ti@tangerino.com.br