Référence API

L'API expose trois endpoints pour les applications scanner, servis par chaque instance issuer. L'URL de base est l'iss du déploiement client (ex : https://tickets.example.com).

Un endpoint de découverte public est aussi disponible à {iss}/.well-known/ticket-issuer.json (sans authentification). Sa structure est décrite dans la spécification du protocole.

Les endpoints check-in et status nécessitent un Bearer token. La clé API est obtenue via l'échange d'enrollment (ci-dessous). L'endpoint d'enrollment lui-même ne requiert pas de Bearer ; il utilise le token d'enrollment comme credential.

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

• Chaque clé API est scopée à un événement (et optionnellement une porte).
• Les clés expirent au timestamp expires_at retourné lors de l'enrollment.
• Une clé invalide, expirée ou révoquée retourne 401 UNAUTHORIZED.
• Les clés DOIVENT être stockées dans le stockage sécurisé de la plateforme (Keychain, Keystore).

Échange un token d'enrollment (provenant d'un QR de setup) contre une clé API longue durée. Le token est à usage unique : une seconde tentative avec le même token retourne 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 - Entrée Nord",
    "scanner_platform": "ios-18.2"
  }'

Paramètres de requête

Réponse · 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"
  }
}

Erreurs d'enrollment

Marque un billet comme utilisé. Idempotent : rejouer la même requête avec le même idempotency_key retourne le même résultat. Une seconde requête avec le même tid mais un idempotency_key différent est traitée comme double-scan et retourne already_used.

Requête

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"
  }'

Réponse · 200 OK

La réponse est toujours 200 avec un champ status indiquant le résultat. Cela permet aux scanners de distinguer les différents cas sans parser les codes HTTP.

{
  "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"
  }
}

Valeurs de statut

Retourne l'état courant d'un billet sans le modifier. Utile pour les pré-vérifications des scanners, les outils admin ou la réconciliation post-événement.

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
}

Si le tid n'existe pas, l'issuer retourne 404 NOT_FOUND.

L'endpoint de check-in utilise une clé d'idempotence pour dédupliquer les retries. Générez un UUID v4 unique par tentative de scan et passez-le soit dans le body (idempotency_key), soit dans l'en-tête HTTP (Idempotency-Key).

Toutes les réponses non-2xx utilisent une enveloppe d'erreur standard :

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

Les issuers DOIVENT limiter le débit de chaque endpoint par credential scanner. Quand la limite est atteinte, le serveur retourne 429 RATE_LIMITED avec un en-tête Retry-After indiquant le nombre de secondes à attendre.

• Endpoint d'enrollment : rate-limit par IP et par token pour prévenir le brute-force.
• Endpoint de check-in : rate-limit par credential scanner.
• Endpoint de statut : rate-limit par credential scanner.

Les scanners DEVRAIENT implémenter un backoff exponentiel sur les réponses 429 et respecter la valeur de Retry-After.