Exibir origem

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.

- 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.

- 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.

- 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.

- 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

- 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>'

- {
  "count": 5,
  "totalHits": 11,
  "took": 12,
  "hits": [
    {
      "mdmGoldenFieldAndValues": {
        "mdmshouldsendwelcomeemail": true,
        "mdmphonenumber": "1232321",
				//....
      }
    },
    {
      "mdmGoldenFieldAndValues": {
        // ...
      }
    },
  ],
  "aggs": {}
}

05.2. Consulta de Marcações

- 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>'

Response similar a da consulta de usuários

05.3. Consulta de Funcionários

- 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>'

Response similar a da consulta de usuários

05.4. Consulta de Dispositivo

- 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>'

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.

- 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" }'

06. EXEMPLO DE USO PARA CONSULTA DE MARCAÇÕES DE PONTO:

Segue abaixo um exemplo prático de como testar e usar uma NAMED QUERY, além de dicas de uso.

06.1. Consultando e testando a NAMED QUERY que pretende usar:

1- Faça Login no seu Ambiente ({organização}.carol.ai/{ambiente});

2- Acesse a opção Explorer no menu da latera esquerda;

3- Dentro do Explorer, acesse a opção Editor.

1- Verifique se está na opção RT em +;

2- Verifique se abriu uma nova aba como RT;

3- No menu lateral esquerdo, também selecione a opção RT;

4- Digite o nome da NamedQuery que pretende utilizar;

5- De duplo clique sobre o nome e ela será aberta para consulta na tela direita;

6, 7 e 8- No caso desta NamedQuery (clockinrecordsListByPeriod), ela permite realizar filtros no Data Model CLOCK IN RECORDS usando os campos de código do dispositivo, período de data da marcação de ponto e a partir de qual número NSR;

9- Você pode testar a NamedQuery pressionando o botão RUN.

TOTVS Clock In > Consultar Dados via Named Queries > image-2024-9-6_11-51-8.png

1- Preencha os filtros desejados e execute a consulta.

TOTVS Clock In > Consultar Dados via Named Queries > image-2024-9-6_12-0-25.png

Assim pode consultar/exportar os dados retornados da consulta:

TOTVS Clock In > Consultar Dados via Named Queries > image-2024-9-6_12-3-12.png

06.2. Exemplo da montagem de uma requisição:

Só passando a NamedQuery, sem usar filtros

Request:

- curl -X 'POST' \
  'https://api.carol.ai/api/v3/queries/named/clockinrecordsListByPeriod?indexType=MASTER&offset=0&pageSize=10&sortBy=mdmGoldenFieldAndValues.mdmeventdate&sortOrder=DESC&scrollable=false' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \    
  -H 'X-Auth-Key: {sua chave aqui}' \
  -H 'X-Auth-ConnectorId: {seu ConnectorId aqui}' \    '

Response:

{
  "count": 10,
  "totalHits": 15646,
  "took": 14,
  "hits": [
    {...}
	...
	]
}

Usando filtro passando um NSR, um único Device e um Período (UTC), não preciso passar todos, poderia por exemplo não passar DEVICE e viria marcações do período de todos DEVICES, ou o NSR e pegar todos registros, mas no caso do NSR eu poderia acabar consumindo registros que ainda não tiveram NSR gerado pela plataforma:

Request:

- curl -X 'POST' \
  'https://api.carol.ai/api/v3/queries/named/clockinrecordsListByPeriod?indexType=MASTER&offset=0&pageSize=10&sortBy=mdmGoldenFieldAndValues.mdmeventdate&sortOrder=DESC&scrollable=false' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'X-Auth-Key: {sua chave aqui}' \
  -H 'X-Auth-ConnectorId: {seu ConnectorId aqui}' \
  -d '{
  "nsrCode": "748",
  "deviceCode": "BE1C11B2-5DEC-4878-88E6-175981481398",
  "initialDate": "2024-08-01T03:00:00.000-03:00",
  "finalDate": "2024-09-01T03:00:00.000-03:00",
}'

Response:

{
  "count": 6,
  "totalHits": 6,
  "took": 4,
  "hits": [
    {
      "mdmDeleted": false,
      "mdmSourceOperation": "SQL_PROCESS",
      "mdmCounterForEntity": 1724761025743000,
      "mdmGoldenFieldAndValues": {
        "clockinmode": "1",
        "smssent": "2024-08-27T03:32:34.990Z",
        "supervisorcode": "[email protected]",
        "isautotimezone": "2",
        "selfclockin": true,
        "lastgpsdatetime": "2024-08-21T12:15:29.000-03:00",
        "nsrprocesseddatetime": "2024-08-21T15:22:25.440Z",
        "devicetimezonechangeindicator": "1",
        "score": "6",
        "supervisorname": "[email protected]",
        "appname": "Clock In",
        "eventdatestr": "2024-08-21T12:15:00.000-03:00",
        "updatedatetimeautomatically": false,
        "lastmomentgpsdatetimeobtained": "2024-08-21T12:15:29.322-03:00",
        "employeegeofencecoordinatesoptional": "no coordinates",
        "receiptimage": "https://totvsclockin.carol.ai/teste/go/728ywobccj",
        "mdmname": "Colaborador Exemplo",
        "devicedescription": "[email protected]",
        "datetimechanged": false,
        "image": "https://totvsclockin.carol.ai/teste/go/raxoohcav9",
        "nsrcode": "753",
        "coordinatesaccuracy": 6,
        "diffgpsdevicetime": "0",
        "collectiveagreement": "99999999999999999",
        "gpslevel": "0",
        "locationcode": "4",
        "licensestatus": "OK",
        "mdmStagingAuditId": "f5ac249636ec0e34",
        "fraudscore": 0.0026708,
        "statusanalysisdate": "2024-08-21T21:09:10.514Z",
        "receiptsentmode": "Nothing",
        "readphonestateenabled": false,
        "gmt": "-03:00",
        "devicecode": "BE1C11B2-5DEC-4878-88E6-175981481398",
        "georeferencestate": "filled",
        "mdmTaskId": "b0a898893037441fbc3cd42d8353f9c2",
        "imagehash": "-0.131479, 0.0294967, 0.0692975, -0.0225383, -0.0269747, -0.0752967, -0.0515807, -0.120229, 0.180412, -0.125723, 0.218578, -0.00439189, -0.253444, -0.118369, 0.002121, 0.117364, -0.0208364, -0.0767907, -0.0751632, -0.0915777, 0.0742972, 0.0451878, 0.0465591, 0.0654342, -0.0633498, -0.339759, -0.0660675, -0.115597, 0.02133, -0.0735729, -0.0318694, 0.0118895, -0.103082, -0.113205, 0.0400811, 0.112948, -0.0746193, -0.0700653, 0.198791, -0.00607182, -0.119064, -0.0749938, 0.0507131, 0.272417, 0.158889, 0.0524132, 0.0531848, -0.0839153, 0.15459, -0.277452, 0.152825, 0.0625031, 0.183316, 0.0599122, 0.20305, -0.146557, 0.0588035, 0.193805, -0.266038, 0.158633, 0.077579, -0.0514593, -0.104153, -0.00862041, 0.249977, 0.166787, -0.132382, -0.0749751, 0.200977, -0.136508, -0.062053, 0.0602444, -0.0952025, -0.207354, -0.218461, 0.0460927, 0.363987, 0.223373, -0.219258, 0.00230355, -0.0482604, 0.00519569, 0.0950405, 0.0393352, -0.0476836, -0.0534268, -0.0686621, -0.0298764, 0.111147, 0.0586453, -0.0532365, 0.272703, 0.0270942, -0.0053324, 0.0387958, 0.0122857, -0.130904, -0.0270901, -0.152075, -0.124179, 0.116132, -0.0682318, 0.0681907, 0.0567057, -0.219154, 0.198706, -0.0320844, 0.0369035, 0.0939216, -0.0129052, -0.104225, 0.0190724, 0.131557, -0.237321, 0.196939, 0.105615, 0.103404, 0.166686, 0.040076, 0.0371103, 0.0908808, -0.0865782, -0.173796, -0.0864644, 0.0326179, -0.0310395, 0.0630728, 0.0668265",
        "isuserinsidegeofenceenum": "1",
        "statusanalysis": "OK",
        "externalservicestatuscode": 0,
        "coordinates": {
          "lon": -48.38827807460761,
          "lat": -22.370139551369817
        },
        "datetimeprovider": "ntp",
        "fakegpslocation": false,
        "devicesynchistorycode": "1724253342422",
        "mdmtaxid": "755",
        "locationdescription": "Joinville",
        "clockinsessionstatus": "logged-in",
        "mdmeventdate": "2024-08-21T15:15:00.000Z",
        "imei": "",
        "gmtfromclockinscoordinates": "-03:00",
        "mdmpersonid": "12345678910"
      },
      "mdmConstraintPending": false,
      "mdmEntityType": "clockinrecordsGolden",
      "mdmStagingRecordIds": [
        "99eb05dd32446c8dd11d0171d995160e"
      ],
      "mdmSourceType": "SQL",
      "mdmMergePending": false,
      "mdmLastUpdated": "2024-08-27T12:17:05Z",
      "mdmTenantId": "1ff0fbe4de2143bbab686413a3c359ca",
      "mdmMasterCount": 1,
      "mdmStagingCounter": "1724729567118246",
      "mdmCreated": "2024-08-27T12:17:05Z",
      "mdmSourceOperationTaskId": "b0a898893037441fbc3cd42d8353f9c2",
      "mdmSourceEntityNames": [
        "bf2ace1f69f34529850e3b983feb8271_clockinrecords"
      ],
      "mdmEntityTemplateId": "7dd4da9d15294d46a6da8e27f179690f",
      "mdmId": "ca04aa98aed7b20e5eb450a397c7ea99"
    },
    {...}, 
    {...}, 
    {...},
    {...},
    {...}
  ],
  "aggs": {}
}

Usando filtro passando um NSR, um único Device e um Período (UTC), não preciso passar todos, poderia por exemplo não passar DEVICE e viria marcações do período de todos DEVICES, ou o NSR e pegar todos registros, mas no caso do NSR eu poderia acabar consumindo registros que ainda não tiveram NSR gerado pela plataforma:

Request:

- curl -X 'POST' \
  'https://api.carol.ai/api/v3/queries/named/clockinrecordsListByPeriod?indexType=MASTER&offset=0&pageSize=10&sortBy=mdmGoldenFieldAndValues.mdmeventdate&sortOrder=DESC&scrollable=false' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'X-Auth-Key: {sua chave aqui}' \
  -H 'X-Auth-ConnectorId: {seu ConnectorId aqui}' \
  -d '{
  "nsrCode": "748",
  "deviceCode": "BE1C11B2-5DEC-4878-88E6-175981481398",
  "initialDate": "2024-08-01T03:00:00.000-03:00",
  "finalDate": "2024-09-01T03:00:00.000-03:00",
}'

Response:

{
  "count": 6,
  "totalHits": 6,
  "took": 9,
  "hits": [
    {
      "mdmGoldenFieldAndValues": {
        "eventdatestr": "2024-08-14T17:40:00.000-03:00",
        "mdmeventdate": "2024-08-14T20:40:00.000Z"
      }
    },
    {
      "mdmGoldenFieldAndValues": {
        "eventdatestr": "2024-08-14T17:42:00.000-03:00",
        "mdmeventdate": "2024-08-14T20:42:00.000Z"
      }
    },
    {
      "mdmGoldenFieldAndValues": {
        "eventdatestr": "2024-08-21T08:49:00.000-03:00",
        "mdmeventdate": "2024-08-21T11:49:00.000Z"
      }
    },
    {
      "mdmGoldenFieldAndValues": {
        "eventdatestr": "2024-08-21T08:55:00.000-03:00",
        "mdmeventdate": "2024-08-21T11:55:00.000Z"
      }
    },
    {
      "mdmGoldenFieldAndValues": {
        "eventdatestr": "2024-08-21T08:57:00.000-03:00",
        "mdmeventdate": "2024-08-21T11:57:00.000Z"
      }
    },
    {
      "mdmGoldenFieldAndValues": {
        "eventdatestr": "2024-08-21T12:15:00.000-03:00",
        "mdmeventdate": "2024-08-21T15:15:00.000Z"
      }
    }
  ],
  "aggs": {}
}

Na documentação acima falamos do offset e pageSize , mas também temos outros query parameters possíveis:
1. sortBy=mdmGoldenFieldAndValues.mdmeventdate - Conforme já mencionado na documentação acima, os campos do Data Model sempre estão dentro do objeto mdmGoldenFieldAndValues. Neste caso eu decidi organizar os registros pelo mdmeventdate (data da marcação de ponto);
2. sortOrder=DESC - Defini que a ordenação será em ordem decrescente, neste caso, da marcação mais atual para mais antiga;
3. fields=mdmGoldenFieldAndValues.eventdatestr%2CmdmGoldenFieldAndValues.mdmeventdate - Aqui no fields você pode definir quais campos retornam da na sua consulta, neste caso escolhi só o eventdatestr e o mdmeventdate.

Request:

- curl -X 'POST' \
  'https://api.carol.ai/api/v4/queries/named/clockinrecordsListByPeriod?indexType=MASTER&offset=0&pageSize=10&sortBy=mdmGoldenFieldAndValues.mdmeventdate&sortOrder=ASC&scrollable=false&fields=mdmGoldenFieldAndValues.eventdatestr%2CmdmGoldenFieldAndValues.mdmeventdate' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'X-Auth-Key: {sua chave aqui}' \
  -H 'X-Auth-ConnectorId: {seu ConnectorId aqui}' \   
  -d '{
  "nsrCode": "748",
  "deviceCode": "BE1C11B2-5DEC-4878-88E6-175981481398",
  "initialDate": "2024-08-01T03:00:00.000-03:00",
  "finalDate": "2024-09-01T03:00:00.000-03:00",
}'

Response:

{
  "count": 6,
  "totalHits": 6,
  "took": 9,
  "hits": [
    {
      "mdmGoldenFieldAndValues": {
        "eventdatestr": "2024-08-14T17:40:00.000-03:00",
        "mdmeventdate": "2024-08-14T20:40:00.000Z"
      }
    },
    {
      "mdmGoldenFieldAndValues": {
        "eventdatestr": "2024-08-14T17:42:00.000-03:00",
        "mdmeventdate": "2024-08-14T20:42:00.000Z"
      }
    },
    {
      "mdmGoldenFieldAndValues": {
        "eventdatestr": "2024-08-21T08:49:00.000-03:00",
        "mdmeventdate": "2024-08-21T11:49:00.000Z"
      }
    },
    {
      "mdmGoldenFieldAndValues": {
        "eventdatestr": "2024-08-21T08:55:00.000-03:00",
        "mdmeventdate": "2024-08-21T11:55:00.000Z"
      }
    },
    {
      "mdmGoldenFieldAndValues": {
        "eventdatestr": "2024-08-21T08:57:00.000-03:00",
        "mdmeventdate": "2024-08-21T11:57:00.000Z"
      }
    },
    {
      "mdmGoldenFieldAndValues": {
        "eventdatestr": "2024-08-21T12:15:00.000-03:00",
        "mdmeventdate": "2024-08-21T15:15:00.000Z"
      }
    }
  ],
  "aggs": {}
}

06.3. Para mais informações

Acesse as documentações técnicas já mencionadas acima:
- Autenticação: aqui.
- Consumindo Dados TOTVS Carol: aqui.
- docs.carol.ai
Consulte o Swagger dentro do seu ambiente: