Histórico da Página

Í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.Image Removed

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

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

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

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.

Image Added

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.

Image Added

1- Preencha os filtros desejados e execute a consulta.

Image Added

Assim pode consultar/exportar os dados retornados da consulta:

Image Added

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

Só passando a NamedQuery, sem usar filtros

Request:

Bloco de código

language	yml
theme	Midnight

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

Bloco de código

language	yml
theme	Midnight

{
  "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:

Bloco de código

language	yml
theme	Midnight

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

Bloco de código

language	yml
theme	Midnight

{
  "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:

Bloco de código

language	yml
theme	Midnight

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

Bloco de código

language	yml
theme	Midnight

{
  "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:

Bloco de código

language	yml
theme	Midnight

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

Bloco de código

language	yml
theme	Midnight

{
  "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:

Image Added
Image Added

Atalhos

Árvore de páginas

Versões comparadas

Versão antiga 9

Nova versão Atual

Chave

01. VISÃO GERAL

02. AUTENTICAÇÃO

03. PAGINAÇÃO

04. FILTROS

05. NAMED QUERIES PARA CONSULTA

05.1. Consulta de Usuários

05.2. Consulta de Marcações

05.3. Consulta de Funcionários

05.4. Consulta de Dispositivo

05.5. Consulta de Filtros

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

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

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

06.3. Para mais informações