TOTVS Clock In

Atalhos

Árvore de páginas

Versões comparadas

Versão antiga 2

changes.mady.by.user Patricia Theilacker

Gravado em

comparado com

Nova versão 12

changes.mady.by.user Brunno Matera Barbosa_

Gravado em

Chave

  • Esta linha foi adicionada.
  • Esta linha foi removida.
  • A formatação mudou.

Índice

01. VISÃO GERAL 

Este documento tem objetivo apresentar como é possível obter dados de usuários, marcações, funcionários e dispositivos do Clock in utilizando Named Queries.

02. AUTENTICAÇÃO

A Plataforma Carol disponibiliza duas formas de autenticação para uso de rotas privadas para Named Queries: OAuth2 e API Key. Mais detalhes acesse aqui.

03. PAGINAÇÃO

A Plataforma Carol disponibiliza a opção do page size / offset.

Para obter os 5 primeiros registros da primeira pagina utilizando o offset=0 e pageSize=5.


Bloco de código
- curl -X POST 
   'https://api.carol.ai/api/v3/queries/named/<NOME_DA_NAMED_QUERY>
      ?offset=0
      &pageSize=5'
   -H 'X-Auth-Key: <KEY>'
   -H 'X-Auth-ConnectorId: <CON_ID>'


Para obter os 5 registros da segunda página, utilizando o offset=5 e pageSize=5.


Bloco de código
- curl -X POST 
   'https://api.carol.ai/api/v3/queries/named/<NOME_DA_NAMED_QUERY>
      ?offset=5
      &pageSize=5'
   -H 'X-Auth-Key: <KEY>'
   -H 'X-Auth-ConnectorId: <CON_ID>'



Caso houvessem mais registros, seria possível utilizar o offset=10 e pageSize=5.

Também é possível retornar todos os dados em uma única request. Isto não é recomendado pois a resposta pode ser lenta e podem haver limitação de quantidade de registros. Para tanto basta remover o campo offset e setar o campo pageSize=-1.

Bloco de código
- curl -X POST 
   'https://api.carol.ai/api/v3/queries/named/<NOME_DA_NAMED_QUERY>
      ?pageSize=-1'
   -H 'X-Auth-Key: <KEY>'
   -H 'X-Auth-ConnectorId: <CON_ID>'


04. FILTROS

Por padrão, Named Queries retornam todos os dados dos Data Models (local onde os dados estão), mas é possível utilizar filtros para obter apenas os dados necessários. No caso abaixo os campos mdmpersonid e mdmname foram utilizados como filtro. Sempre lembrando que os campos do Data Model sempre estão dentro do objeto mdmGoldenFieldAndValues. A Plataforma Carol retorna outros campos que fazem parte da estrutura interna dela mas que não parecem fazer sentido para este caso.


Bloco de código
- curl -X POST 
   'https://api.carol.ai/api/v3/queries/named/<NOME_DA_NAMED_QUERY>
      ?offset=0
      &pageSize=5
      &fields=mdmGoldenFieldAndValues.mdmpersonid,mdmGoldenFieldAndValues.mdmname'
   -H 'X-Auth-Key: <KEY>'
   -H 'X-Auth-ConnectorId: <CON_ID>'



05. NAMED QUERIES PARA CONSULTA

Para obter a lista completa de Named Queries disponíveis no ambiente, basta entrar em Explore e depois em Named Queries. A lista será apresentada. Nesta área é possível editar, excluir e incluir novas Named Queries. Sempre lembrando que elas vão retornar os registros dos Data Models.  Para saber mais sobre Named Queries acesse aqui. 


05.1. Consulta de Usuários 

Bloco de código
- curl -X POST 
   'https://api.carol.ai/api/v3/queries/named/userList
      ?offset=0
      &pageSize=5
      &fields=mdmGoldenFieldAndValues'
   -H 'X-Auth-Key: <KEY>'
   -H 'X-Auth-ConnectorId: <CON_ID>'
Bloco de código
- {
  "count": 5,
  "totalHits": 11,
  "took": 12,
  "hits": [
    {
      "mdmGoldenFieldAndValues": {
        "mdmshouldsendwelcomeemail": true,
        "mdmphonenumber": "1232321",
				//....
      }
    },
    {
      "mdmGoldenFieldAndValues": {
        // ...
      }
    },
  ],
  "aggs": {}
}

05.2. Consulta de Marcações

Bloco de código
- curl -X POST 
   'https://api.carol.ai/api/v3/queries/named/clockinrecordsListByPeriod
      ?offset=0
      &pageSize=5
      &fields=mdmGoldenFieldAndValues'
   -H 'X-Auth-Key: <KEY>'
   -H 'X-Auth-ConnectorId: <CON_ID>'
Bloco de código
Response similar a da consulta de usuários


05.3. Consulta de Funcionários 

Bloco de código
- curl -X POST 
   'https://api.carol.ai/api/v3/queries/named/employeeList
      ?offset=0
      &pageSize=5
      &fields=mdmGoldenFieldAndValues'
   -H 'X-Auth-Key: <KEY>'
   -H 'X-Auth-ConnectorId: <CON_ID>'
Bloco de código
Response similar a da consulta de usuários

05.4. Consulta de Dispositivo



Bloco de código
- curl -X POST 
   'https://api.carol.ai/api/v3/queries/named/deviceList
      ?offset=0
      &pageSize=5
      &fields=mdmGoldenFieldAndValues'
   -H 'X-Auth-Key: <KEY>'
   -H 'X-Auth-ConnectorId: <CON_ID>'
Bloco de código
Response similar a da consulta de usuários


05.5. Consulta de Filtros


Para verificar quais são os filtros das Named Queries, basta entrar na área citada anteriormente e executar uma Named Query para testes. Ao executar, a Carol apresentará quais são os filtros. Também é possível adicionar novos filtros. Segue abaixo exemplo de como enviar valores para os filtros via requisições HTTP POST.


Bloco de código
- curl -X POST 
   'https://api.carol.ai/api/v3/queries/named/<NOME_DA_NAMED_QUERY>
      ?offset=0
      &pageSize=5
      &fields=mdmGoldenFieldAndValues'
   -H 'X-Auth-Key: <KEY>'
   -H 'X-Auth-ConnectorId: <CON_ID>'
   -d '{ "key1": "value1", "key2": "value2" }'

Como realizar a autenticação para consumo de apis na Carol:

https://tdn.totvs.com/pages/releaseview.action?pageId=552107176#id-2.Autentica%C3%A7%C3%A3o-ConnectorToken(APIKey)

Como realizar o consumo de apis na Carol:
Consumindo Dados TOTVS Carol

...