Skip to content

Audit and Telemetry

Hyvä POS is in closed beta

Hyvä POS is currently in a closed beta (pilot phase) with a small group of merchants. It is not yet generally available: the App Store release follows the pilot, and features and configuration may still change - possibly in backwards-incompatible ways - before the general release. Want to take part? Sign up at hyva.io/pos.

Two independent trails. The audit log records who changed what - one row per field change, written when a cashier edits data from the device (and by admin-side saves of POS entities). Telemetry records operational events for diagnostics and usage reporting.

Method Route Purpose ACL
POST /V1/pos/audit-log Submit field-change entries from a terminal Hyva_Pos::locations
GET /V1/pos/audit-log List audit entries via searchCriteria Hyva_Pos::pos
POST /V1/pos/telemetry Submit an event batch from a terminal Hyva_Pos::locations
GET /V1/pos/telemetry/report Export an aggregated report Hyva_Pos::pos

The two GET routes carry the admin-level Hyva_Pos::pos resource, so a terminal-scoped integration token can write but not read - reading the trails is an admin/reporting concern.

Submit Audit Entries

POST /V1/pos/audit-log

Called by the app after on-device edits - a stock correction, a product price change, a customer edit. The body is a batch of entries; each entry is one field change:

{
  "entries": [
    {
      "entity_type": "stock",
      "entity_id": 2043,
      "entity_name": "Classic Shirt (WSH12)",
      "field_name": "qty",
      "old_value": "14",
      "new_value": "12",
      "change_source": "pos_terminal",
      "staff_id": 7,
      "staff_name": "Anna",
      "terminal_id": 3,
      "terminal_name": "Front Desk 01",
      "location_id": 1,
      "location_name": "Amsterdam Store"
    }
  ]
}

Returns true. Field notes:

  • entity_type, entity_id, and field_name are required; an empty entity_type or field_name is stored as "unknown" rather than rejected.
  • change_source defaults to pos_terminal when omitted. The column also carries admin and api for rows written server-side.
  • The *_name fields are denormalized on purpose: they capture the display names at the time of the change, so the trail stays readable after a staff member, terminal, or location is renamed or deleted.
  • old_value / new_value are free-form strings; the app sends whatever representation the edited field had.

List Audit Entries

GET /V1/pos/audit-log?searchCriteria[filter_groups][0][filters][0][field]=entity_type&searchCriteria[filter_groups][0][filters][0][value]=stock

Standard Magento searchCriteria listing over the hyva_pos_audit_log table, returning the usual items / search_criteria / total_count envelope. Each item carries the submitted fields plus the server-assigned log_id and created_at timestamp. Useful filter fields: entity_type, entity_id, change_source, staff_id, terminal_id, location_id, created_at.

This is the same data behind the admin grid; admin-side saves of POS entities (for example location edits) land in the same table with change_source set to admin and the admin user's name recorded.

Retention

Audit rows are never purged automatically - there is no cleanup cron for hyva_pos_audit_log. The audit trail is the compliance record; if a merchant needs pruning, that is a deliberate DBA action, not module behavior.

Submit Telemetry

POST /V1/pos/telemetry

Batch upload of operational events. The payload is a free-shape object with device context at the top level and an events array:

{
  "payload": {
    "location_id": 1,
    "terminal_id": 3,
    "device_id": "8F1C2D3E-4A5B-6C7D-8E9F-0A1B2C3D4E5F",
    "app_version": "1.4.2",
    "events": [
      {
        "event_type": "counter",
        "event_name": "checkout_completed",
        "event_data": {"payment_method": "cash"},
        "value": 1,
        "period": "2026-08-12",
        "recorded_at": "2026-08-12 14:03:22"
      }
    ]
  }
}

event_type and event_name are required per event; event_data (arbitrary JSON), value (numeric), period, and recorded_at are optional. The endpoint is deliberately lenient: a non-array payload or an empty events array returns false instead of an error, and individual malformed events are skipped while the rest of the batch is stored. Telemetry must never break a terminal, so there is no validation failure path.

Telemetry Report

GET /V1/pos/telemetry/report?locationId=1&from=2026-08-01&to=2026-08-12

Admin-side export of aggregated telemetry for the optional location and date range. All three query parameters are optional.

Retention

A daily cron (hyva_pos_telemetry_cleanup, 04:00 server time) aggregates raw events into daily summaries and then purges: raw events and summaries older than hyva_pos_advanced/telemetry/retention_days (default 90) are deleted. Telemetry is a rolling diagnostic window, not a permanent record - anything that must survive belongs in the audit log or on the order.