Point Markers¶

What is it?¶

One point marking is the entry or exit record of an employee at a given time. It is the central data of the frequency control system — everything in Pontotel revolves around ensuring that the markings are accurate and complete.

Why It Matters In Integration¶

In integrations with point devices (clocks, totens, apps), the logs arrive via API
In sync with sheet systems, historical markings can be imported
O time zone correct is mandatory — offset UTC markings generate inconsistencies in calculations

Business Rules¶

Each appointment has a type: entrada or saida
O data_hora must include the time zone offset (ISO 8601)
Inactive employees cannot register new markings
Incorrect markings should not be deleted — should be adjusted with justification for audit
The chronological order (entry → output → input → output) must be respected

Time zone is mandatory

Always send data_hora with explicit offset.
"2025-01-31T08:05:00-03:00"
"2025-01-31T08:05:00" (no offset — ambiguous)

Available Operations¶

Method	Endpoint	Description
GET	`/marcacoes/`	List Markers
POST	`/marcacoes/`	Registration
GET	`/marcacoes/{id}/`	Get Marking
PATCH	`/marcacoes/{id}/`	Adjust (requires justification)

Fields¶

Field	Type	Required	Description
`id`	integer	—	Internal ID
`empregado_id`	integer		Employee ID
`data_hora`	datetime		Date and time with offset (ISO 8601)
`tipo`	string		`entrada` or `saida`
`origem`	string	—	`app` \
`justificativa`	string	—	Reason for adjustment (for PATCH)

Example: Register Marking¶

Request¶

HTTP
POST /pontotel/api/v4/marcacoes/
Authorization: Bearer {token}
Content-Type: application/json

{
  "empregado_id": 500,
  "data_hora": "2025-01-31T08:05:00-03:00",
  "tipo": "entrada",
  "origem": "api"
}

Response (201 Created)¶

JSON
{
  "id": 9999,
  "empregado_id": 500,
  "data_hora": "2025-01-31T08:05:00-03:00",
  "tipo": "entrada",
  "origem": "api",
  "justificativa": null
}

Example: List Period Markers¶

HTTP
1 2	`GET /pontotel/api/v4/marcacoes/?empregado_id=500&data_inicio=2025-01-01T00:00:00-03:00&data_fim=2025-01-31T23:59:59-03:00 Authorization: Bearer {token}`

Example: Adjust Wrong Marking¶

HTTP
PATCH /pontotel/api/v4/marcacoes/9999/
Authorization: Bearer {token}
Content-Type: application/json

{
  "data_hora": "2025-01-31T08:00:00-03:00",
  "justificativa": "Correção de horário registrado com atraso por falha no dispositivo"
}

Common Errors¶

Error	Cause	Solution
Timestamp without offset	`data_hora` no time zone	Always include offset: `2025-01-31T08:00:00-03:00`
Inactive employee	Try to register for employee fired	Check `is_active` before sending
Reverse order	Logged out before entry	Ensure correct chronological order