API - Apontamentos

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

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, geolocalização e dados do relógio de origem da marcação (`EquipmentID`/`DeviceID`, arquitetura e tipo de autenticação).

Headers

AUTH-TOKEN: Sua chave privada

Exemplos de Requisição e Resposta

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

Exemplo com ShowMeta = true
Quando a requisição é feita com ShowMeta=true, cada apontamento passa a trazer também o relógio de origem da marcação e os metadados abaixo:

GET https://api1.tradingworks.net/v1/attendances?ShowMeta=true&FromDate=2026-09-01&ToDate=2026-09-30

{
  "AttendanceRegisterID": 22681,
  "NSR": 1,
  "EmployeeNumber": "304",
  "SocialSecurity": "131142368-54",
  "PersonalDocument": "128.377.188-82",
  "BaseDate": "2026-09-08T00:00:00",
  "EventDateTime": "2026-09-08T10:46:00",
  "Synced": false,
  "StatusID": 1,
  "Status": "Automático",
  "EquipmentID": 2,
  "TWArchitectureID": 1,
  "MainVersion": 1,
  "TWAuthenticationID": 1
}

Campos adicionais retornados com ShowMeta = true

Campo	Tipo	Observações
EquipmentID	integer	Identificador do equipamento (relógio do tipo app/portal) que originou a marcação. Aparece quando a marcação foi feita pelo aplicativo ou pelo portal web. Para mapeamento deste campo, acesse o artigo Clique AQUI para saber mais.
DeviceID	integer	Identificador do dispositivo (coletor REP) que originou a marcação. Para mapeamento deste campo, acesse o artigo Clique AQUI para saber mais.
TWArchitectureID	integer	Identificador da arquitetura de origem da marcação (Web, Mobile, Coletor REP, etc.). Para mapeamento deste campo, acesse o artigo Clique AQUI para saber mais.
MainVersion	integer	Versão do aplicativo utilizado na marcação. Só é retornado em marcações feitas pelo aplicativo.
TWAuthenticationID	integer	Identificador do método de autenticação usado na marcação (Login, Facial, Quiosque). Para mapeamento deste campo, acesse o artigo Clique AQUI para saber mais.

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

Exemplo

[
  {
    "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 sobre a marcação, incluindo o relógio de origem (EquipmentID/DeviceID), a arquitetura (TWArchitectureID), o método de autenticação (TWAuthenticationID), além de validação facial e geolocalização. Para saber o nome/detalhes de cada relógio, arquitetura ou método a partir do ID retornado, consulte os artigos específicos de cada endpoint (linkados na tabela de campos acima).
MainVersion só é retornado em marcações feitas pelo aplicativo.
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.