← HomeSwagger

ss-tipdata API documentation

This service ingests Genius/Heartland reporting data and returns tip allocations per staff/per job type, with reconciliation against tipsPayouts.

Authentication

All third‑party API endpoints require a shared API key header:

x-ss-tipdata-key: <shared_key>

The server also uses a static integrator key for upstream Genius/Heartland calls (configured server‑side via GENIUS_INTEGRATOR_KEY).

If the Swagger “Servers” dropdown shows localhost in your deployment, set SS_TIPDATA_PUBLIC_BASE_URL to your public URL (for example https://ss-api.example.com).

Workflow (recommended)

  1. Register location (one time): store the Heartland X-Api-Key for a location.
  2. Setup mapping: fetch job types and configure payroll job codes and the tax-on-tips flag.
  3. Export (on demand): call export for a business-date range.

Endpoints

POST /api/location/register

Stores the location key and upserts location identity from /v2/setup/settings.

curl -X POST \
  -H "content-type: application/json" \
  -H "x-ss-tipdata-key: <shared_key>" \
  -d '{"xApiKey":"<location_key>"}' \
  http://localhost:3000/api/location/register

GET /api/setup

Returns job types merged with current mapping values. By default it refreshes job types from Heartland.

curl -H "x-ss-tipdata-key: <shared_key>" \
  "http://localhost:3000/api/setup?locationAccountNumber=<id>&refresh=true"

POST /api/sync-dims and POST /api/ingest-range

These endpoints support two modes:

  • MVP/debug: include xApiKey in the JSON body (no shared auth header required).
  • Automation: omit xApiKey and pass x-ss-tipdata-key; the server will use the stored location key.

PATCH /api/setup

Bulk update mappings in one call.

curl -X PATCH \
  -H "content-type: application/json" \
  -H "x-ss-tipdata-key: <shared_key>" \
  -d '{"locationAccountNumber":"<id>","mappings":[{"jobTypeId":"...","payrollJobCode":"110","taxOnTips":true}]}' \
  http://localhost:3000/api/setup

POST /api/export

Fresh-pull export for a business-date range. This is the recommended “on demand” endpoint for automation. Optional flags default to excluding salaried staff and Online Order User (-1). Set debug=true to include provenance log + raw payloads.

curl -X POST \
  -H "content-type: application/json" \
  -H "x-ss-tipdata-key: <shared_key>" \
  -d '{"locationAccountNumber":"<id>","startDate":"2025-12-01","endDate":"2025-12-14","debug":false}' \
  http://localhost:3000/api/export

POST /api/process-range-os

“Do it for me” endpoint: sync dims → ingest fresh → process → return results (optional debug). Unlike /api/export, this also persists a ProcessRun and raw fetch snapshots to the DB for audit/debug.

About /api/export vs /api/process-range-os

  • /api/export: best for stateless automation. Fresh pull and return results (optional debug payload).
  • /api/process-range-os: best when you want the run persisted for later inspection. Fresh pull + persists RawFetch and ProcessRun.

Debugging & troubleshooting

  • Provenance log: set debug=true to include event-level attribution decisions and reconciliation steps.
  • Ticket-owner fallback: if a payment is run by a cashier, we use /v2/reports/tickets/info to fall back to the ticket owner for attribution.
  • Online Order User (-1): staff id c3RhZmY6LTE= is treated as a system pseudo-staff and logged as online_order_unallocated.
  • Re-polling: ingestion overwrites cached raw data for the same location/date scope so upstream edits (punch changes, staff changes) are reflected on rerun.