API publique : référence technique

Cet article est destiné à la personne qui consomme l'API REST PassPass. Pour une vue d'ensemble et la configuration depuis le dashboard, consultez API publique et Webhooks.

Documentation interactive (Swagger) : api.passpass.be/api/public/docs

---

Authentification

Chaque requête porte votre clé API dans le header Authorization :

Authorization: Bearer pk_live_...

La clé est liée à votre organisation. Toutes les données renvoyées sont filtrées automatiquement sur votre organisation. Le secret n'est affiché qu'une seule fois à la création. Si vous le perdez, effectuez une rotation depuis le dashboard (l'ancien secret cesse de fonctionner immédiatement).

Validez votre configuration avec GET /v1/me : c'est le seul endpoint qui ne requiert aucun scope.

---

Endpoints

L'API est en lecture seule.

Événements (scope events:read)

• GET /v1/events : liste de vos événements

• GET /v1/events/:id : détail d'un événement

Commandes (scope orders:read)

• GET /v1/orders : liste des commandes

• GET /v1/orders/:id : détail d'une commande

Participants (scope attendees:read)

• GET /v1/events/:eventId/attendees : participants d'un événement

• GET /v1/orders/:orderId/attendees : participants d'une commande

Analytics (scope events:read) : 7 routes exposant les mêmes données que le module Analytics du dashboard (KPIs, évolution des ventes, répartition par ticket, sources de trafic, géographie, funnel de conversion, segments d'audience). Consultez le Swagger pour le détail des routes et des réponses.

Introspection (aucun scope requis)

• GET /v1/me : informations de votre clé API

---

Permissions (scopes)

Les scopes contrôlent les champs renvoyés. Un champ non autorisé est absent, pas null.

• events:read : événements et analytics

• orders:read : commandes (montant, acheteur, billing, line items, statut)

• orders:read:financial : service_fee, payout_amount, refundable_amount

• orders:read:form_answers : réponses au formulaire de commande

• attendees:read : participants (données minimales, aucune donnée personnelle)

• attendees:read:contact : first_name, last_name, email

• attendees:read:financial : ticket_price

• attendees:read:form_answers : réponses au formulaire participant

• attendees:read:full : access_token (inclut automatiquement contact et financial)

---

Conventions

• Champs en snake_case (exception : buyer et billing en camelCase)

• Montants en euros (pas en centimes)

• Dates en ISO 8601 UTC

• Champs multilingues : {"fr": "...", "en": "...", "nl": "..."}

• Nouveaux champs possibles sans préavis

---

Pagination

{
  "data": [],
  "total": 137,
  "page": 1,
  "limit": 25,
  "total_pages": 6
}

Paramètres : ?page= (défaut 1) et ?limit= (défaut 25, max 100).

---

Événements

GET /v1/events renvoie tous vos événements (brouillons et privés inclus). Chaque événement inclut ses tickets avec le taux de TVA effectif (vat_rate), les quantités vendues et les jauges.

{
  "id": 1535,
  "title": {"fr": "Mon événement"},
  "status": "published",
  "visibility": "public",
  "sold_count": 128,
  "max_capacity": 500,
  "start_at": "2026-06-01T18:00:00.000Z",
  "end_at": "2026-06-01T23:00:00.000Z",
  "timezone": "Europe/Brussels",
  "currency": "EUR",
  "tickets": [
    {
      "id": 4525,
      "type": "ticket",
      "name": {"fr": "Entrée Standard"},
      "price": 25,
      "vat_rate": 21,
      "max_quantity": 300,
      "sold_count": 128,
      "visibility": "visible"
    }
  ]
}

---

Commandes

GET /v1/orders renvoie les commandes. Par défaut, seules les commandes payées sont renvoyées. Passez ?status=all pour le portrait complet.

Filtres : status (paid/pending/cancelled/all), created_after, created_before (ISO-8601).

{
  "id": 65817,
  "event_id": 1535,
  "status": "paid",
  "amount_total": 200,
  "buyer": {
    "firstName": "Marie",
    "lastName": "Dupont",
    "email": "marie@example.com"
  },
  "billing": {
    "identifierType": "vat",
    "companyName": "Demo Corp SRL",
    "vat": "BE0123456789",
    "vatCountry": "BE",
    "addressStreet": "Rue de la Loi 1",
    "addressCity": "Bruxelles",
    "addressZip": "1000",
    "addressCountry": "BE"
  },
  "line_items": [
    {
      "type": "ticket",
      "ticket_id": 4525,
      "name": {"fr": "Entrée Standard"},
      "quantity": 2,
      "unit_amount": 100,
      "subtotal": 200,
      "vat_rate": 21
    }
  ],
  "form_answers": null,
  "service_fee": 4.6,
  "payout_amount": 195.4
}

buyer : identité au checkout (camelCase). billing : données société, null si non renseigné (camelCase). line_items : type ticket (billet), fee (frais) ou discount (remise, montant négatif). Le vat_rate est le taux de TVA effectif du ticket.

---

Participants

GET /v1/events/:eventId/attendees renvoie les participants (un par billet, statut active uniquement).

{
  "id": "019fdb0d-...",
  "event_id": 1535,
  "order_id": 65817,
  "status": "active",
  "ticket": {
    "id": 4525,
    "type": "ticket",
    "name": {"fr": "Entrée Standard"}
  },
  "first_name": "Marie",
  "last_name": "Dupont",
  "email": "marie@example.com",
  "ticket_price": 100,
  "access_token": "019fdb0d-...",
  "form_answers": [
    {
      "type": "selection",
      "field_id": "abc123...",
      "question_title": {"fr": "Statut"},
      "answer": {"fr": "Indépendant"}
    }
  ]
}

Les champs dépendent des scopes : contact (first_name, last_name, email), financial (ticket_price), form_answers, full (access_token).

---

Limites et erreurs

100 requêtes par minute par clé. Au-delà : HTTP 429.

• 401 : clé absente ou invalide

• 403 : scope insuffisant

• 404 : ressource inexistante

• 400 : paramètre invalide

• 429 : quota dépassé

---

API ou Webhooks ?

• Temps réel (vente, scan) → Webhooks

• Export comptable, émargement → API

• Dashboard analytics → API analytics

• Rattrapage après incident → API

• Schéma robuste : webhooks + API périodique

---