Open API: technische referentie

Dit artikel is bedoeld voor de persoon die de PassPass REST API gebruikt. Voor een overzicht en de configuratie vanaf het dashboard, raadpleeg Openbare API en Webhooks.

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

---

Authenticatie

Elke aanvraag bevat uw API-sleutel in de header Authorization :

GET /api/v1/events HTTP/1.1
Host: api.passpass.be
Authorization: Bearer pk_live_9f2c4a1b...

De sleutel is gekoppeld aan uw organisatie. Alle geretourneerde gegevens worden automatisch gefilterd op uw organisatie.

Het geheim van de sleutel wordt slechts één keer weergegeven bij het aanmaken. Als u het verliest, voer dan een rotatie uit vanaf het dashboard (het oude geheim werkt onmiddellijk niet meer).

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

---

Beschikbare endpoints

De API is alleen-lezen. 7 GET endpoints:

• GET /v1/me : introspectie van uw API-sleutel (scopes, organisatie, laatste gebruik). Geen scope vereist

• GET /v1/events : lijst van uw evenementen (alle statussen, inclusief concepten en privé). Scope: events:read

• GET /v1/events/:id : detail van een evenement. Scope: events:read

• GET /v1/orders : lijst van bestellingen. Scope: orders:read

• GET /v1/orders/:id : detail van een bestelling. Scope: orders:read

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

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

---

Permissies (scopes)

De scopes controleren de geretourneerde velden, niet alleen de toegang tot de endpoints. Een niet-geautoriseerd veld is afwezig, niet null.

• events:read : toegang tot evenementendpoints

• orders:read : toegang tot bestellingsendpoints (bedrag, koper, facturatie, line items, status)

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

• orders:read:form_answers : antwoorden op het bestelformulier

• attendees:read : toegang tot deelnemerendpoints (minimale gegevens, geen persoonlijke gegevens)

• 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 automatisch contact en financieel)

---

Paginering

Alle lijsten zijn gepagineerd:

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

Parameters: ?page= (standaard 1) en ?limit= (standaard 25, maximum 100). Pagineer altijd tot total_pages en herlees de limit die wordt geretourneerd.

---

Conventies

• Velden in snake_case (uitzondering: koper en facturatie in camelCase)

• Bedragen in euro's (niet in centen). 25 = 25,00€

• Datums in ISO 8601 UTC

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

• Niet-geautoriseerd veld door de scopes: afwezig, niet null

• Nieuwe velden mogelijk zonder voorafgaande kennisgeving, verwerp geen onbekend veld

---

Evenementen

GET /v1/events retourneert al uw evenementen (inclusief concepten en privé, alleen verwijderde zijn uitgesloten). Geen filter op status of datum aan de API-kant: filter aan de klantzijde op status / start_at.

Gebruikscases: dashboard van capaciteit, ticketvoorraadbeheer, lijst van evenementen in een backoffice.

{
  "id": 1535,
  "title": {"fr": "Mon événement"},
  "short_description": {"fr": "Description courte"},
  "address_label": {"fr": "Bruxelles"},
  "address_full": {"fr": "Rue de la Loi 1, 1000 Bruxelles"},
  "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"},
      "description": null,
      "price": 25,
      "vat_rate": 21,
      "max_quantity": 300,
      "sold_count": 128,
      "visibility": "visible",
      "sell_start_at": null,
      "sell_end_at": null
    }
  ],
  "created_at": "2026-01-12T14:22:00.000Z",
  "updated_at": "2026-04-17T09:00:00.000Z"
}

---

Bestellingen

GET /v1/orders retourneert de bestellingen van uw organisatie.

Beschikbare filters

• status : paid (standaard), pending, cancelled, of all

• created_after : ISO-8601 datum, bestellingen aangemaakt vanaf dit moment (inclusief)

• created_before : ISO-8601 datum, bestellingen aangemaakt tot dit moment (inclusief)

Statussen

• paid : betaald en niet geannuleerd

• cancelled : geannuleerd (of het nu betaald is of niet). Verlopen bestellingen (verlaten winkelwagentje) vallen hier ook onder

• pending : noch betaald noch geannuleerd (lopende winkelwagen, wachtende overschrijving)

Gebruikscases: boekhoudkundige export, financiële afstemming, CRM-synchronisatie.

{
  "id": 65817,
  "event_id": 1535,
  "status": "paid",
  "origin": "online",
  "currency": "EUR",
  "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
    }
  ],
  "form_answers": null,
  "paid_at": "2026-04-17T10:00:00.000Z",
  "cancelled_at": null,
  "created_at": "2026-04-17T10:00:00.000Z",
  "updated_at": "2026-04-17T10:00:00.000Z",
  "service_fee": 4.6,
  "payout_amount": 195.4,
  "refundable_amount": 4.6,
  "historical_service_fee": 4.6
}

De velden begrijpen

buyer : identiteit ingevoerd bij de checkout (voornaam, achternaam, email). In camelCase.

billing : bedrijfsfacturatiegegevens. Alleen aanwezig als de koper "ik bestel namens een bedrijf" heeft aangevinkt bij de checkout. Anders null. In camelCase. Bevat: identifierType (vat of enterprise), companyName, vat, vatCountry, addressStreet, addressCity, addressZip, addressCountry.

line_items : detail van de bestelling. Elke regel heeft een type:

• ticket : gekocht ticket, unit_amount = eenheidsprijs

• fee : servicekosten (één enkele samengevoegde regel)

• discount : kortingscode / korting, negatieve unit_amount

Financieel blok (scope orders:read:financial) :

• service_fee : huidige servicekosten

• historical_service_fee : kosten vastgelegd op het moment van verkoop

• payout_amount : netto bedrag dat aan de organisator moet worden overgemaakt

• refundable_amount : deel van de kosten dat nog kan worden terugbetaald

form_answers (scope orders:read:form_answers) : antwoorden op het gepersonaliseerde bestelformulier.

---

Deelnemers

GET /v1/events/:eventId/attendees of GET /v1/orders/:orderId/attendees retourneert de deelnemers. Een deelnemer = een ticket.

Gebruikscases: presentielijst, offline toegangscontrole, nominatieve export.

{
  "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-...",
  "created_at": "2026-04-17T10:00:00.000Z",
  "updated_at": "2026-04-17T10:00:00.000Z",
  "form_answers": [
    {
      "type": "selection",
      "field_id": "abc123...",
      "question_title": {"fr": "Quel est votre statut actuel ?"},
      "answer": {"fr": "Indépendant"}
    },
    {
      "type": "unique-choice",
      "field_id": "def456...",
      "question_title": {"fr": "Régime alimentaire"},
      "answer": {"fr": "Végétarien"}
    },
    {
      "type": "short-text",
      "field_id": "ghi789...",
      "question_title": {"fr": "Nom entreprise"},
      "answer": "Demo Corp"
    },
    {
      "type": "formatted-field",
      "field_id": "jkl012...",
      "question_title": {"fr": "Téléphone"},
      "answer": "+32400000000"
    },
    {
      "type": "formatted-field",
      "field_id": "mno345...",
      "question_title": {"fr": "Code postal"},
      "answer": "1000"
    }
  ]
}

De velden begrijpen

De velden zijn afhankelijk van de scopes. Afwezig als de scope niet is toegekend:

• first_name, last_name, email (scope attendees:read:contact)

• ticket_price (scope attendees:read:financial) : bedrag in euro's

• form_answers (scope attendees:read:form_answers) : antwoorden op het deelnemersformulier. Mogelijke types: selection, unique-choice, short-text, formatted-field. De types selection en unique-choice hebben meertalige antwoorden, de andere string-antwoorden

• access_token (scope attendees:read:full) : de geheime identificatie achter de QR-code van het ticket, gelezen door de PassPass Organizer mobiele applicatie tijdens de toegangscontrole. Deze token kan bijvoorbeeld worden herverdeeld op een badge om een QR-code te repliceren die leesbaar is door de PassPass ticketcontrole. Het doorgeven van deze token komt neer op het geven van toegang tot het ticket

---

Introspectie

GET /v1/me retourneert de informatie van uw sleutel. Geen scope vereist.

{
  "api_key_id": "019d-...",
  "api_key_prefix": "pk_live_9f2c4a1b",
  "api_key_name": "Production server",
  "organization_id": "019d-...",
  "scopes": ["events:read", "orders:read", "attendees:read"],
  "last_used_at": "2026-04-17T09:58:00.000Z",
  "created_at": "2026-01-12T14:22:00.000Z"
}

---

Limieten

100 verzoeken per minuut per API-sleutel. Daarbuiten: HTTP 429. Als uw behoefte realtime is, gebruik dan de webhooks in plaats van polling.

---

Foutcodes

• 401 : sleutel afwezig, ongeldig of gedeactiveerd

• 403 : geldige sleutel maar onvoldoende scope

• 404 : niet-bestaande bron of buiten uw organisatie

• 400 : ongeldige parameter (status, datumformaat...)

• 429 : quotum overschreden (100 req/min)

---

API of Webhooks?

• Reageren op een verkoop in realtime → Webhooks order.paid

• Een CRM synchroniseren in de loop van de tijd → Webhooks + API als inhaalslag

• Boekhoudkundige export, afstemming → API /v1/orders?status=all&created_after=...

• Presentielijst, toegangscontrole → API /v1/events/:id/attendees

• Dashboard capaciteit / voorraad → API /v1/events (sold_count, max_quantity)

• Een verleden geschiedenis opnieuw afspelen → API (de webhooks spelen het verleden niet opnieuw af)

Het robuuste schema: webhooks voor realtime + periodieke API-oproep om in te halen wat een netwerkincident zou hebben gemist.

---