Open API: technische referentie

Dit artikel is bedoeld voor de persoon die de PassPass REST API implementeert. Voor een overzicht en dashboardconfiguratie, zie Publieke API en Webhooks.

Interactieve documentatie (Swagger): api.passpass.be/api/public/docs

---

Authenticatie

Elk verzoek bevat uw API-sleutel in de Authorization header:

Authorization: Bearer pk_live_...

De sleutel is gekoppeld aan uw organisatie. Alle geretourneerde gegevens worden automatisch gefilterd op uw organisatie. Het geheim wordt slechts eenmaal getoond bij aanmaak. Als u het verliest, roteer het vanuit het dashboard (het oude geheim werkt onmiddellijk niet meer).

Valideer uw configuratie met GET /v1/me: dit is het enige endpoint dat geen scope vereist.

---

Endpoints

De API is alleen-lezen.

Evenementen (scope events:read)

• GET /v1/events: lijst van uw evenementen

• GET /v1/events/:id: details van een evenement

Bestellingen (scope orders:read)

• GET /v1/orders: lijst van bestellingen

• GET /v1/orders/:id: details van een bestelling

Deelnemers (scope attendees:read)

• GET /v1/events/:eventId/attendees: deelnemers van een evenement

• GET /v1/orders/:orderId/attendees: deelnemers van een bestelling

Analytics (scope events:read): 7 routes die dezelfde gegevens tonen als de Analytics-module in het dashboard (KPI's, verkooptijdlijn, ticketverdeling, verkeersbronnen, geografie, conversietrechter, doelgroepsegmenten). Zie de Swagger voor routedetails en responses.

Introspectie (geen scope vereist)

• GET /v1/me: informatie over uw API-sleutel

---

Machtigingen (scopes)

Scopes bepalen welke velden worden geretourneerd. Een niet-geautoriseerd veld is afwezig, niet null.

• events:read: evenementen en analytics

• orders:read: bestellingen (bedrag, koper, facturatie, regelitems, status)

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

• orders:read:form_answers: antwoorden op het bestelformulier

• attendees:read: deelnemers (minimale gegevens, geen persoonlijke informatie)

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

• attendees:read:financial: ticket_price

• attendees:read:form_answers: antwoorden op het deelnemersformulier

• attendees:read:full: access_token (inclusief contact en financial)

---

Conventies

• Velden in snake_case (uitzondering: buyer en billing in camelCase)

• Bedragen in euro (niet in centen)

• Datums in ISO 8601 UTC

• Meertalige velden: {"fr": "...", "en": "...", "nl": "..."}

• Nieuwe velden kunnen zonder voorafgaande kennisgeving verschijnen

---

Paginering

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

Parameters: ?page= (standaard 1) en ?limit= (standaard 25, max 100).

---

Evenementen

GET /v1/events retourneert al uw evenementen (concepten en privé inbegrepen). Elk evenement bevat zijn tickets met het effectieve BTW-tarief (vat_rate), verkochte aantallen en capaciteiten.

{
  "id": 1535,
  "title": {"nl": "Mijn evenement"},
  "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": {"nl": "Standaard Toegang"},
      "price": 25,
      "vat_rate": 21,
      "max_quantity": 300,
      "sold_count": 128,
      "visibility": "visible"
    }
  ]
}

---

Bestellingen

GET /v1/orders retourneert bestellingen. Standaard worden alleen betaalde bestellingen geretourneerd. Gebruik ?status=all voor het volledige overzicht.

Filters: 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": {"nl": "Standaard Toegang"},
      "quantity": 2,
      "unit_amount": 100,
      "subtotal": 200,
      "vat_rate": 21
    }
  ],
  "form_answers": null,
  "service_fee": 4.6,
  "payout_amount": 195.4
}

buyer: identiteit bij checkout (camelCase). billing: bedrijfsgegevens, null indien niet ingevuld (camelCase). line_items: type ticket (ticket), fee (servicekosten) of discount (korting, negatief bedrag). vat_rate is het effectieve BTW-tarief van het ticket.

---

Deelnemers

GET /v1/events/:eventId/attendees retourneert deelnemers (één per ticket, alleen status active).

{
  "id": "019fdb0d-...",
  "event_id": 1535,
  "order_id": 65817,
  "status": "active",
  "ticket": {
    "id": 4525,
    "type": "ticket",
    "name": {"nl": "Standaard Toegang"}
  },
  "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": {"nl": "Status"},
      "answer": {"nl": "Zelfstandige"}
    }
  ]
}

Velden zijn afhankelijk van scopes: contact (first_name, last_name, email), financial (ticket_price), form_answers, full (access_token).

---

Limieten en fouten

100 verzoeken per minuut per sleutel. Daarboven: HTTP 429.

• 401: sleutel ontbreekt of ongeldig

• 403: onvoldoende scope

• 404: bron niet gevonden

• 400: ongeldige parameter

• 429: limiet overschreden

---

API of Webhooks?

• Realtime (verkoop, scan) → Webhooks

• Boekhoudexport, aanwezigheid → API

• Aangepast analytics dashboard → API analytics

• Herstel na incident → API

• Robuust patroon: webhooks + periodieke API-aanroepen

---