Passar para o conteúdo principal

API - Apontamentos

Neste artigo, verá o uso dos endpoints da API da TWO relacionados a Apontamentos.

Escrito por Jorge Luis

Listar Apontamentos

Lista os 1.000 primeiros apontamentos que ainda não foram marcados como sincronizados.

São retornados apenas apontamentos originais, aprovados ou inseridos pelo Gestor/RH.

Endpoint

GET https://api1.tradingworks.net/v1/attendances

Parâmetros

Campo

Tipo

Requerido

Exemplo

Observações

Language

string

Não

pt-BR

Define o idioma dos campos retornados. Valores disponíveis: en-US (padrão) e pt-BR.

FromDate

date

Não

2020-09-01

Data inicial da pesquisa. O período máximo entre FromDate e ToDate é de 120 dias.

ToDate

date

Não

2020-09-30

Data final da pesquisa.

ListAll

boolean

Não

true

Retorna os apontamentos dos últimos 60 dias, independentemente da sincronização, respeitando o limite de 1.000 registros.

ShowMeta

boolean

Não

true

Retorna informações adicionais, como validação facial e geolocalização.

Headers

AUTH-TOKEN = Sua chave privada

Exemplo (Português)

GET https://api1.tradingworks.net/v1/attendances?Language=pt-BR&FromDate=2020-09-01&ToDate=2020-09-30
{
   "AttendanceRegisterID":240341,
   "Matricula":"42345",
   "PIS":"8374823",
   "CPF":"1112223334444",
   "DataBase":"2018-09-03T00:00:00",
   "Data_Hora_Evento":"2018-09-03T13:45:00",
   "Sincronizado":false,
   "SituacaoID":3,
   "Situacao":"Aprovado"
}

Exemplo (Inglês)

GET https://api1.tradingworks.net/v1/attendances?FromDate=2020-09-01&ToDate=2020-09-30
{
   "AttendanceRegisterID":240341,
   "EmployeeNumber":"42345",
   "SocialSecurity":"8374823",
   "PersonalDocument":"1112223334444",
   "BaseDate":"2018-09-03T00:00:00",
   "EventDateTime":"2018-09-03T13:45:00",
   "Synced":false,
   "StatusID":3,
   "Status":"Approved"
}

Valores de StatusID / SituacaoID

Valor

Descrição

0

Inserido - Evento inserido pelo gestor ou por pré-assinalação de alimentação.

1

Automático - Marcação original realizada pelo colaborador.

2

Aguardando - Requisição manual aguardando aprovação.

3

Aprovado - Requisição manual aprovada.

4

Reprovado - Requisição manual reprovada.

5

Uso interno.

6

Descartado - Marcação descartada e não utilizada nos cálculos da folha.

Valores de LocaleStatusID / LocalSituacaoID

Valor

Descrição

0

Não processado - O processamento da localidade ainda não foi realizado.

1

Sem GPS - O equipamento não possui GPS ou o acesso foi bloqueado.

2

Com localidade - O ponto foi registrado dentro de uma localidade conhecida.

3

Sem localidade - O ponto foi registrado fora de uma área cadastrada.

4

Sem precisão - O GPS não possui precisão suficiente para identificar a localidade.

5

Uso de navegador - O ponto foi registrado por navegador, onde a precisão da geolocalização não é exata.

Valores de FaceStatusVerificationID / FaceSituacaoID

Valor

Descrição

0

Não processado - A biometria facial ainda não foi processada.

1

Aprovado automaticamente - A biometria facial foi reconhecida e validada.

2

Aprovado manualmente - A biometria foi aprovada por um gestor/RH.

3

Reprovado automaticamente - A biometria facial não identificou o colaborador.

4

Reprovado manualmente - A biometria foi reprovada por um gestor/RH.

Marcar Apontamento como Sincronizado

Indica que o apontamento foi efetivado nos sistemas internos da empresa e não deverá mais aparecer na listagem.

Limite de até 1.000 apontamentos por requisição.

Endpoint

POST https://api1.tradingworks.net/v1/attendances/setsync

Headers

AUTH-TOKEN = Sua chave privada Content-Type = application/json

Dados

Campo

Tipo

Requerido

Exemplo

Observações

AttendanceRegisterID

integer

Sim

240341

Identificador do apontamento que será marcado como sincronizado.

Exemplo

[
   {
      "AttendanceRegisterID":240341
   },
   {
      "AttendanceRegisterID":240348
   },
   {
      "AttendanceRegisterID":240362
   }
]

Adicionar Apontamento

Permite incluir um registro de ponto proveniente de um equipamento homologado de ponto eletrônico.

Endpoint

POST https://api1.tradingworks.net/v1/attendances/add

Headers

AUTH-TOKEN = Sua chave privada Content-Type = application/json

Dados

Campo

Tipo

Requerido

Exemplo

Observações

NumeroREP

string

Não

98765

Utilizado para auditoria da marcação importada.

NSR

string

Não

1234

Número Sequencial de Registro (NSR), utilizado para auditoria.

CPF

string

Sim

12345678900

CPF do colaborador. Recomenda-se informar apenas números.

DataMarcacao

string

Sim

2023-10-01

Data da marcação no formato AAAA-MM-DD.

HoraMarcacao

string

Sim

22:34

Hora da marcação no formato 24 horas (HH:mm).

Exemplojson formatt

[
   {
      "NumeroREP":"098765",
      "NSR":"1234",
      "CPF":"12345678900",
      "DataMarcacao":"2023-10-01",
      "HoraMarcacao":"14:56"
   },
   {
      "NumeroREP":"098765",
      "NSR":"1235",
      "CPF":"12345678900",
      "DataMarcacao":"2023-10-01",
      "HoraMarcacao":"19:07"
   }
]

Observações importantes

  • A consulta retorna até 1.000 apontamentos por requisição.

  • São retornados apenas apontamentos originais, aprovados ou inseridos pelo Gestor/RH.

  • O período entre FromDate e ToDate não pode ultrapassar 120 dias.

  • Quando ListAll = true, são retornados os apontamentos dos últimos 60 dias, independentemente do status de sincronização.

  • Quando ShowMeta = true, a API retorna informações adicionais, como validação facial, geolocalização e respectivos status.

  • Após utilizar o endpoint Marcar Apontamento como Sincronizado, o registro deixa de ser retornado nas próximas consultas.

  • O endpoint Adicionar Apontamento deve ser utilizado apenas para registros provenientes de equipamentos homologados de ponto eletrônico, permitindo a auditoria por meio do REP e do NSR.

Artigos relacionados
Respondeu à sua pergunta?