API-referentie

De API biedt drie endpoints voor scannerapplicaties, aangeboden door elke issuer-instantie. De basis-URL is de iss van de klantimplementatie (bijv. https://tickets.example.com).

Er is ook een publiek discovery-endpoint beschikbaar op {iss}/.well-known/ticket-issuer.json (geen authenticatie vereist). De structuur hiervan wordt beschreven in de protocolspecificatie.

De endpoints check-in en status vereisen een Bearer token. De API key wordt verkregen via de registratie-uitwisseling (hieronder). Het registratie-endpoint zelf vereist geen Bearer; het gebruikt het registratietoken als credential.

Authorization: Bearer sk_live_01HXXX...long-opaque-key

• Elke API key is beperkt tot een evenement (en optioneel een ingang).
• Keys verlopen op het expires_at-tijdstip dat tijdens de registratie wordt teruggegeven.
• Een ongeldige, verlopen of ingetrokken key retourneert 401 UNAUTHORIZED.
• Keys MOETEN worden opgeslagen in de beveiligde opslag van het platform (Keychain, Keystore).

Wisselt een registratietoken (uit een setup-QR-code) in voor een langdurige API key. Het token is eenmalig: een tweede poging met hetzelfde token retourneert INVALID_TOKEN.

curl -X POST https://tickets.example.com/api/v1/scanners/enroll \
  -H "Content-Type: application/json" \
  -d '{
    "token": "st_01HXXX...opaque-enrollment-token",
    "scanner_id": "550e8400-e29b-41d4-a716-446655440000",
    "scanner_name": "iPhone 14 - North Gate",
    "scanner_platform": "ios-18.2"
  }'

Request-parameters

Response · 200 OK

{
  "api_key": "sk_live_01HXXX...long-opaque-key",
  "api_key_id": "sck_01HXXX...ULID",
  "scope": {
    "eid": "evt_01HXXX...ULID",
    "event_name": "Gala Concert",
    "event_date": "2026-06-15T20:00:00Z",
    "gate_id": "north",
    "expires_at": "2026-06-16T02:00:00Z"
  },
  "issuer": {
    "name": "Festival des Arts",
    "iss": "https://tickets.example.com"
  }
}

Registratiefouten

Markeert een ticket als gebruikt. Idempotent: het herhalen van hetzelfde request met dezelfde idempotency_key retourneert hetzelfde resultaat. Een tweede request met dezelfde tid maar een andere idempotency_key wordt behandeld als een dubbele scan en retourneert already_used.

Request

curl -X POST https://tickets.example.com/api/v1/tickets/check-in \
  -H "Authorization: Bearer sk_live_01HXXX..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{
    "tid": "01HXXX...ULID",
    "eid": "evt_01HXXX...ULID",
    "scanned_at": "2026-06-15T19:42:13Z",
    "scanner_id": "gate-north-01",
    "gate_id": "north",
    "idempotency_key": "550e8400-e29b-41d4-a716-446655440000"
  }'

Response · 200 OK

De response is altijd 200 met een status-veld dat het resultaat aangeeft. Dit stelt scanners in staat om verschillende gevallen te onderscheiden zonder HTTP-statuscodes te hoeven parsen.

{
  "status": "valid",
  "ticket": {
    "tid": "01HXXX...ULID",
    "eid": "evt_01HXXX...ULID",
    "holder_name": "J. Smith",
    "ticket_type": "VIP",
    "checked_in_at": "2026-06-15T19:42:13Z"
  }
}

{
  "status": "already_used",
  "ticket": {
    "tid": "01HXXX...ULID",
    "eid": "evt_01HXXX...ULID",
    "holder_name": "J. Smith",
    "ticket_type": "VIP",
    "checked_in_at": "2026-06-15T19:30:00Z"
  }
}

Statuswaarden

Geeft de huidige status van een ticket terug zonder deze te wijzigen. Nuttig voor voorcontroles door scanners, beheertools of afstemming na afloop van een evenement.

curl https://tickets.example.com/api/v1/tickets/01HXXX...ULID/status \
  -H "Authorization: Bearer sk_live_01HXXX..."

{
  "tid": "01HXXX...ULID",
  "eid": "evt_01HXXX...ULID",
  "status": "valid",
  "holder_name": "J. Smith",
  "ticket_type": "VIP",
  "issued_at": "2026-05-01T10:00:00Z",
  "checked_in_at": null
}

Als de tid niet bestaat, retourneert de issuer 404 NOT_FOUND.

Het check-in endpoint gebruikt een idempotency key om herhaalpogingen te dedupliceren. Genereer een unieke UUID v4 per scanpoging en geef deze mee in de body (idempotency_key) of in de HTTP header (Idempotency-Key).

Alle niet-2xx responses gebruiken een standaard fout-envelope:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "API key is missing, expired, or revoked.",
    "details": {}
  }
}

Issuers MOETEN elk endpoint per scannercredential rate-limiten. Wanneer de limiet is bereikt, retourneert de server 429 RATE_LIMITED met een Retry-After header die het aantal seconden wachttijd aangeeft.

• Registratie-endpoint: rate-limited op IP-adres en token om brute-force te voorkomen.
• Check-in endpoint: rate-limited per scannercredential.
• Status-endpoint: rate-limited per scannercredential.

Scanners ZOUDEN exponential backoff moeten implementeren bij 429 responses en de Retry-After-waarde respecteren.