Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.scanova.io/llms.txt

Use this file to discover all available pages before exploring further.

​
Step 1: Send a test event

Send a single test event with a known event_id so you can trace it: 
curl -X POST "https://track.scanova.io/server-events" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "site_id": "YOUR_SITE_ID",
    "event_name": "test_event",
    "event_id": "00000000-0000-0000-0000-000000000001",
    "scan_session_id": "00000000-0000-0000-0000-000000000002",
    "properties": { "test": true }
  }'
A successful response looks like: 
{
  "event_id": "00000000-0000-0000-0000-000000000001",
  "status": "accepted"
}

​
Step 2: Confirm it appears in the dashboard

  1. Open the Scanova dashboard
  2. Go to Integrations → Conversion Tracking
  3. Open the tracking site
  4. Your test_event should appear within 30–60 seconds

​
Step 3: Test deduplication

Resend the same request with the same event_id: 
# Same request again
curl -X POST "https://track.scanova.io/server-events" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "site_id": "YOUR_SITE_ID",
    "event_name": "test_event",
    "event_id": "00000000-0000-0000-0000-000000000001",
    "scan_session_id": "00000000-0000-0000-0000-000000000002"
  }'
The second request will return 200 but the event will be marked as a duplicate and excluded from conversion counts. Confirm the event count in reports did not increase.

​
Common errors and fixes

​
401 — Missing API key

The X-API-Key header is absent from the request. 
# Wrong — missing header
curl -X POST "https://track.scanova.io/server-events" -d '{...}'

# Correct
curl -X POST "https://track.scanova.io/server-events" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{...}'

​
403 — Invalid key or unauthorized site

Either the API key is invalid, revoked, or the site_id in the payload does not match the site the key belongs to. Verify:
  • The key was copied correctly (no trailing spaces or newline characters)
  • The site_id in the request body matches exactly the site that generated the key
  • The key has not been revoked in the dashboard

​
422 — Validation error

The payload failed schema validation. The response body includes details: 
{
  "detail": [
    {
      "loc": ["body", "scan_session_id"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}
Common causes:
  • Missing required field (site_id, event_name, or scan_session_id)
  • scan_session_id is not a valid UUID format
  • conversion_value.currency is not a 3-letter ISO code
  • properties object exceeds 10 KB
  • Raw email address in properties (use user_identifiers.email_hash instead)

​
429 — Rate limit exceeded

You are sending more than 1,000 events per minute per API key. Back off and retry:
  • Check the Retry-After header in the response
  • Use the batch endpoint (POST /server-events/batch) to consolidate multiple events into fewer requests

​
Event delivered but not appearing in reports

  • Wait 60 seconds — there is a short processing delay
  • Verify the site_id in your payload matches the tracking site you are viewing in the dashboard
  • Check that the scan_session_id is a valid UUID — invalid format is rejected with 422
  • Confirm the scan_session_id you sent is a real scan session from a QR Code scan, not a test UUID — events with unresolvable sessions are not attributed and may not appear in reports