Skip to main content
POST
/
registers
/
{registerId}
/
heartbeat
Send a register heartbeat
curl --request POST \
  --url https://api.openfiskal.com/v1/registers/{registerId}/heartbeat \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "timestamp": "2023-11-07T05:31:56Z",
  "sequence": 18291,
  "status": "operational",
  "metrics": {
    "pending_operations": 123,
    "unsynced_operations": 123,
    "battery_level": 0.5,
    "disk_free_bytes": 123
  },
  "software": {
    "pos_vendor": "acme-pos",
    "pos_version": "3.2.1",
    "agent_version": "1.4.0"
  }
}
'
{
  "object": "<string>",
  "received_at": "2023-11-07T05:31:56Z",
  "server_time": "2023-11-07T05:31:56Z"
}

Authorizations

​
Authorization
string
header
required

Platform API key sent as Authorization: Bearer ofk_platform_.... Platform integrators also pass OpenFiskal-Organization: org_xxx to act on behalf of a merchant.

Path Parameters

​
registerId
string
required

Body

application/json
​
timestamp
string<date-time>
required
​
sequence
integer
required

Monotonically increasing counter. Used to detect missed heartbeats.

Example:

18291

​
status
enum<string>
required
Available options:
operational,
degraded
​
metrics
object
​
software
object

Response

Heartbeat acknowledged

Minimal acknowledgment. The register uses server_time to detect local clock drift — compare against the device's own clock and flag significant deviations in the next heartbeat's metrics.

​
object
string
Allowed value: "heartbeat_response"
​
received_at
string<date-time>

Server timestamp when this heartbeat was received

​
server_time
string<date-time>

Current server time. Compare against the register's local clock to detect drift. Drift beyond ~5 seconds is a fiscal risk in jurisdictions that require accurate event timestamps.