SAAVISAAVI InsightsRead-only data API

Operations

Onboarding runbook

The sequence used to bring each SAAVI customer onto the Insights API. Nothing is published to a dashboard until the parity step passes.

  1. 1 · Register the organisation

    Each SAAVI customer becomes its own organisation with its own MSSQL target record. Table structure is shared, so only the connection details and reporting rules differ.

  2. 2 · Agree the reporting rules

    GST basis, week start day, cancelled-order treatment, pallet derivation basis and timezone are confirmed in writing before any figure is published. They are stored per organisation and returned by /organization.

  3. 3 · Install the bridge

    A small runner inside the customer's network reads SAAVI tables using a modified-since watermark and pushes batches outbound over HTTPS. No inbound port, no VPN, and no write path back into SAAVI.

  4. 4 · Backfill and roll up

    Historical orders are mirrored, then day, week and month rollups are computed. The rollup engine is deterministic and replayable, so any published figure can be recomputed from the mirror on demand.

  5. 5 · Parity sign-off

    A parity harness compares rollups against the mirrored source rows for sampled windows. Discrepancies must be zero before keys are issued; the run output is the evidence attached to go-live.

  6. 6 · Issue keys and schedule

    Issue one key per consumer with the narrowest scopes needed, subscribe any webhooks, and enable the hourly sync. Keys are hashed at rest and revocable instantly.

Key issuance defaults

  • Dashboard key — metrics:read, orders:read
  • Spreadsheet or ETL key — exports:read
  • Bridge runner key — bridge:write, issued only to the on-prem runner
  • Default limit 120/min per key

Full scope list: metrics:read, orders:read, exports:read, webhooks:manage, bridge:write

Operating guarantees

  • Reads never touch the customer's live SAAVI database.
  • No endpoint can create, change or cancel an order.
  • One organisation per key; cross-organisation reads are impossible.
  • Every request is audited with a correlation id, key, route and status.
  • Every response states how old the data is.

Health check

Point uptime monitoring at the health endpoint with a low-scope key. It reports liveness and the age of the most recent successful sync, so a stalled bridge is caught before anyone questions a dashboard figure.

curl -s https://insights.saavi.com.au/api/public/v1/health -H "X-Api-Key: saavi_live_..."