Skip to content

Audit and Telemetry

Hyvä POS is on the App Store

The free app is out for iPhone, iPad and Mac: install it from the App Store, connect your Magento store and sell. PRO, the Magento module with a license per terminal, follows shortly. News and pricing are at hyva.io/pos.

Three 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). Sale events record approvals and interventions at the register and link them to the sale's order. 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
POST /V1/pos/sale-events Store a batch of sale events Hyva_Pos::locations
GET /V1/pos/sale-events List stored sale events via searchCriteria Hyva_Pos::locations

The audit log and telemetry GET routes carry the admin-level Hyva_Pos::pos resource, so a terminal-scoped integration token can write but not read them; reading those trails is an admin/reporting concern. GET /V1/pos/sale-events carries Hyva_Pos::locations.

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

The module also writes a row for every held-cart recall (entity_type held_cart), identifying the staff member and the location.

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 kept as the compliance record; pruning the table is a manual database action.

Sale Events

A sale event is an approval or an intervention at the register: a manager approving a discount for a cashier, a staff member removing an item at a self-checkout. Magento stores one row per event_id in hyva_pos_sale_event.

Submit Sale Events

POST /V1/pos/sale-events

{
  "events": [
    {
      "event_id": "0B6E3F8A-2C1D-4E5F-9A7B-3C4D5E6F7A8B",
      "kind": "approval",
      "action": "cart_discount",
      "basket_id": "9F3C2A1B-7D4E-4A61-8C0B-2E5F1A9D3C77",
      "sale_id": "9A9E4AF3-0E4E-4B2A-9D3E-1C2B3D4E5F60",
      "terminal_id": 3,
      "location_id": 1,
      "requested_by": { "staff_id": 12, "name": "John Cashier" },
      "approved_by": { "staff_id": 3, "name": "Jane Manager" },
      "subject": null,
      "amount": "10.00",
      "detail": null,
      "occurred_at": "2026-10-20T09:41:07Z"
    }
  ]
}
Field Type Rule
event_id string Required. A UUID
kind string Required. approval or intervention
action string Required. What was approved or done, at most 64 characters (line_discount, cart_discount, price_override, refund_discrepancy_writeoff, resolve_due_payment, ...)
basket_id string Required. The register's basket, at most 64 characters
sale_id string or null The sale's ID once the basket became a sale, at most 64 characters
terminal_id, location_id int or null
requested_by object Required. staff_id (int or null), name (string or null)
approved_by object or null staff_id, name
subject string or null What the event applies to, such as a line; cut to 255 characters
amount decimal string or null The amount approved
detail string or null Free text; cut to 4000 characters
occurred_at string Required. ISO 8601 with a time zone; stored in UTC

The answer lists each event under accepted (stored by this request), duplicates (stored already) or rejected (with the reason; the rest of the batch is stored). Resend a batch after a lost answer.

Order Linking

An event with a sale_id is linked to the order whose pos_sale_id matches: at once when the order exists, otherwise when the order is saved, after its transaction commits. The event row takes the order's order_id, and the order's history gets a comment that is not visible to the customer, for example Cart discount approved by Jane Manager for John Cashier, 10.00. A failed link is logged and never fails the order save; the event stays stored and is linked by the order's next save or a resend.

List Sale Events

GET /V1/pos/sale-events takes standard searchCriteria and returns the items / search_criteria / total_count envelope.

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": "0.3.0",
    "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 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. There is no validation failure path, so a telemetry problem cannot stop a terminal.

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; anything that must be retained belongs in the audit log or on the order.