Waar moet je op letten bij het integreren van een ticketing-API?

Als je bedrijf ticketing moet integreren in je bestaande infrastructuur, is de kwaliteit van de API doorslaggevend. Twijfel je nog tussen aanbieders? Onze gids over hoe je een ticketingplatform kiest behandelt de belangrijkste criteria. Een slecht ontworpen API betekent maanden ontwikkeltijd, voortdurende bugs en beperkingen die je te laat ontdekt. Deze gids helpt je te beoordelen waar je op moet letten voordat je je vastlegt op een platform.

Het goede nieuws is dat bijna niets van wat je moet eisen een kwestie van mening is. Het meeste staat zwart op wit in publieke specificaties: OpenAPI voor het contract, de RFC's van de IETF voor authenticatie, foutafhandeling en het einde van de levensduur van een endpoint, en de documentatie van de betalingsprovider voor de aflevering van events. Hieronder volgt die lijst, met de concrete referentie erbij.

Wat zegt de kwaliteit van de documentatie over een API?

De kwaliteit van de documentatie weerspiegelt de volwassenheid van de API. Let op deze elementen:

• OpenAPI/Swagger-specificatie: maakt het mogelijk om automatisch clients te genereren
• Codevoorbeelden: in de talen die je gebruikt (JS, Python, PHP...)
• Handleidingen voor gebruikscasussen: niet alleen referentiemateriaal, ook tutorials
• Changelog: wijzigingshistorie en versioneringsbeleid
• Statuspagina: inzicht in de beschikbaarheid van de service

De standaard heeft een naam en een datum. De OpenAPI Specification 3.1.0 werd op 15 februari 2021 gepubliceerd en vereist een veld openapi met de versie van de specificatie die het document gebruikt, los van de versie van de API zelf. Ze ondersteunt JSON en YAML, en raadt YAML 1.2 aan zodat de conversie tussen beide geen informatie verliest.

Het praktische verschil is duidelijk. Een geldig OpenAPI-document laad je in een generator, en binnen minuten heb je een getypeerde client in je eigen taal. Een PDF of een pagina met losse voorbeelden lukt dat niet. Vraag om het bestand, niet om een screenshot: als de provider je het openapi.yaml niet op dezelfde dag kan leveren als je het opvraagt, begint de integratie al met een achterstand.

Hoe moet een veilige ticketing-API authenticeren?

De API verwerkt gevoelige gegevens en financiële transacties. Beveiliging staat niet ter discussie.

• OAuth 2.0: moderne standaard voor authenticatie
• API-keys met scopes: granulaire rechten per key
• Rotatie van credentials: mogelijkheid om te roteren zonder downtime
• Rate limiting: bescherming tegen misbruik, met gedocumenteerde limieten
• Toegangslogs: audit van wie waartoe toegang heeft

Het basiskader is RFC 6749, dat het OAuth 2.0 Authorization Framework definieert. Maar wat je naar het technische overleg moet meenemen, is RFC 9700, *Best Current Practice for OAuth 2.0 Security*, gepubliceerd in 2025. Drie van de eisen daaruit controleer je in een middag:

• Autorisatieservers moeten PKCE ondersteunen, en publieke clients moeten het gebruiken. Dit is de bescherming tegen diefstal van de autorisatiecode.
• De validatie van de *redirect URI* moet gebeuren via exacte stringvergelijking, met als enige uitzondering variabele poorten op localhost voor native applicaties. Elke vorm van patroonmatching is een open deur.
• Toegangstokens zouden gebonden moeten zijn aan de uitgever via mTLS of DPoP, zodat een gelekt token in andere handen nutteloos is.

Als de provider alleen een statische, oneindig geldige API-key aanbiedt, is dat niet per se een afknapper, maar het contract moet dan wel dekken wat die keuze inhoudt: echte scopes, rotatie zonder dienstonderbreking en een toegangslogboek dat je kunt exporteren.

Welke essentiële endpoints moet de API bieden?

Controleer of de API alle bewerkingen biedt die je nodig hebt.

• Events: aanmaken, bewerken, weergeven, status beheren
• Tickets: types, prijzen, beschikbaarheid, reserveringen
• Orders: aanmaken, raadplegen, annuleren, terugbetalen
• Validatie: tickets controleren, toegang registreren
• Webhooks: notificaties van events (verkoop, toegang, enz.)

Er is één vraag die zwaarder weegt dan de hele lijst hierboven: wat gebeurt er als hetzelfde verzoek twee keer binnenkomt. Bij ticketing kan een netwerk-retry op het aanmaken van een order een verkoop dupliceren en capaciteit blokkeren die niet bestaat. Het juiste antwoord is een idempotentiekey per schrijfoperatie, zodat de tweede poging het resultaat van de eerste teruggeeft in plaats van een nieuwe order aan te maken. Vraag dit schriftelijk op en laat het gedrag in de sandbox zien.

De tweede vraag gaat over paginering en leeslimieten. Een API die niet documenteert hoeveel orders ze per pagina teruggeeft, of hoe je door de historie navigeert, maakt van elke nachtelijke export naar je metrics-dashboard een eigen technisch probleem.

Waarvoor dienen webhooks in een integratie?

Webhooks zijn essentieel om je systeem gesynchroniseerd te houden zonder constante polling.

• Beschikbare events: welke acties webhooks activeren
• Gedocumenteerde payload: duidelijke structuur per type event
• Retries: wat er gebeurt als je endpoint faalt
• Handtekeningverificatie: om te controleren of de webhook authentiek is
• Logs: geschiedenis van verzonden webhooks en hun status

Hoe controleer je een handtekening

De best gedocumenteerde procedure in de sector is die van Stripe, en die dient als voorbeeld, ook als je provider een andere partij is. De webhookdocumentatie van Stripe beschrijft een header Stripe-Signature met een timestamp met het voorvoegsel t= en een of meer handtekeningen met een schemavoorvoegsel; het enige geldige schema in productie is v1. De handtekening wordt berekend als een HMAC met SHA-256 over de string die bestaat uit de timestamp, een punt en de exacte JSON-body van het verzoek, met het endpoint-secret als sleutel.

Drie details die echte integraties laten mislukken. Eerst: je moet de ruwe body gebruiken; als je framework de JSON opnieuw serialiseert, mislukt de verificatie altijd. Ten tweede: de vergelijking moet in constante tijd gebeuren, om geen informatie te lekken via de responstijd. Ten derde: de officiële libraries passen standaard een tolerantie van 5 minuten toe tussen de timestamp en het huidige tijdstip, en de documentatie zelf waarschuwt om die niet op nul te zetten, omdat dat de versheidscontrole uitschakelt en de deur weer opent voor een replay-aanval.

Retries, duplicaten en volgorde

De concrete getallen zijn relevant als je je wachtrij moet dimensioneren. Stripe documenteert automatische retries gedurende maximaal drie dagen met exponentiële backoff in productiemodus, en drie retries binnen een paar uur in de sandbox. Handmatig opnieuw verzenden werkt tot 15 dagen vanuit het dashboard en tot 30 dagen vanuit de CLI. Er kunnen tot 16 webhook-endpoints worden geregistreerd.

En twee waarschuwingen die je letterlijk in je ontwerp moet overnemen: de afleveringsvolgorde van events is niet gegarandeerd, en een endpoint kan hetzelfde event meer dan één keer ontvangen. De officiële aanbeveling is om de al verwerkte event-ID's te registreren en het aanmaaktijdstip niet te gebruiken om de volgorde af te leiden. Daarnaast moet het endpoint een 2xx teruggeven vóór de zware logica: elke 3xx-respons wordt beschouwd als afleveringsfout, en een *timeout* zet de retry-cyclus in gang.

Hoe moet de API fouten en gebruikslimieten afhandelen?

Met standaardformaten, niet met zelfverzonnen strings. RFC 9457, *Problem Details for HTTP APIs*, gepubliceerd in 2023, definieert een machineleesbare errorbody met vijf velden: type (URI die het soort probleem identificeert), title, status, detail en instance, aangeboden als application/problem+json. Een API die dit toepast, bespaart je het schrijven van een eigen foutvertaler per provider.

Voor gebruikslimieten is de referentie RFC 6585, *Additional HTTP Status Codes*, van april 2012, die de statuscode 429 Too Many Requests introduceerde. De specificatie zelf stelt dat de respons details zou moeten bevatten die de situatie toelichten, en een header Retry-After kan bevatten die aangeeft hoelang je moet wachten. Die header maakt het verschil tussen een doordachte retry en een lus die de overbelasting verergert.

Vraag tijdens de evaluatie welke limieten de API per minuut en per key toepast, of die verschillen voor lezen en schrijven, en wat er gebeurt bij de piekbelasting van een ticketverkoopstart, precies het moment waarop je integratie het hardst wordt belast. Een platform dat zijn limieten niet publiceert, vraagt je om ze te ontdekken op de slechtst mogelijke dag.

Waarom heb ik een testomgeving (sandbox) nodig?

Ontwikkelen tegen productie is een recept voor een ramp. Eis een goede sandbox.

• Afzonderlijke sandboxomgeving: testdata zonder invloed op productie
• Testkaarten: om betalingen te simuleren zonder echte afschrijvingen
• Voorbeeldgegevens: vooraf geladen events en tickets om te testen
• Pariteit met productie: hetzelfde gedrag, dezelfde reacties

Voeg een test toe die bijna niemand doet tijdens de evaluatie: fouten forceren. Een nuttige sandbox laat je een afgewezen betaling simuleren, een gedeeltelijke terugbetaling, een bankauthenticatie die de koper afbreekt, en een webhook die te laat binnenkomt. Als je alleen het ideale scenario kunt testen, heb je niets getest.

De klok speelt ook een rol. Controleer of je in de sandbox de datum van een event kunt vooruitzetten om het sluiten van de verkoop, de controle aan de deur en het genereren van rapportages achteraf te testen, zonder weken te moeten wachten.

Welke juridische verplichtingen brengt de integratie met zich mee?

Twee aandachtsgebieden, en geen van beide is optioneel binnen de Europese Unie.

Het eerste gebied zijn de betalingen. De Gedelegeerde Verordening (EU) 2018/389 eist in artikel 4 dat authenticatie gebaseerd is op twee of meer elementen uit de categorieën kennis, bezit en inherentie, en in artikel 5 de dynamische koppeling: de gegenereerde code moet specifiek zijn voor het bedrag en de begunstigde die de betaler heeft geaccepteerd. Artikel 16 bevat de vrijstelling voor kleine bedragen: transacties tot 30 EUR, met een eerder opgebouwd cumulatief bedrag van niet meer dan 100 EUR of maximaal vijf opeenvolgende transacties op afstand. Je integratie moet de koper na authenticatie correct terugbrengen naar de flow, en dat test je in de sandbox, niet op de avond van de verkoopstart. Verkoop je in Spanje, dan is het de moeite waard dit te combineren met de beschikbare betaalmethoden.

Het tweede gebied zijn de gegevens. De Verordening (EU) 2016/679 verplicht in artikel 32 tot het toepassen van passende technische en organisatorische maatregelen, waaronder versleuteling en de mogelijkheid om vertrouwelijkheid en integriteit te waarborgen, en in artikel 33 tot het melden van beveiligingsinbreuken aan de toezichthoudende autoriteit zonder onredelijke vertraging en, indien mogelijk, binnen uiterlijk 72 uur. De API die je e-mailadressen en telefoonnummers van bezoekers levert, maakt jou verantwoordelijk voor wat je daarmee doet: de verwerkersovereenkomst teken je vóór de eerste aanroep, niet erna. De operationele details vind je in onze AVG-gids voor organisatoren.

Hoe versioneer en deprecieer je een API zonder je integratie te breken?

Met publieke regels. Semantic Versioning 2.0.0 reserveert een verhoging van het hoofdversienummer voor wijzigingen die niet compatibel zijn met eerdere versies, het minor-nummer voor compatibele functionaliteit en het patch-nummer voor correcties. Toegepast op een API betekent dit dat een wijziging die je client breekt, niet zomaar in een stille deployment op een dinsdag mag binnensluipen.

Voor het einde van de levensduur bestaat een standaardheader. RFC 8594, van mei 2019, definieert het HTTP-responsveld Sunset met één tijdstempel die aangeeft wanneer een resource waarschijnlijk niet meer zal reageren, en een linkrelatietype sunset dat verwijst naar het uitfaserings- of migratiebeleid. Vragen of de API deze header afgeeft, is een snelle manier om te weten of de provider heeft nagedacht over de levenscyclus, of alleen over de lancering.

Datzelfde geldt voor de embedded verkoopwidget: als de JavaScript wordt geserveerd vanaf een URL zonder versienummer, bereikt elke wijziging van de provider je website zonder waarschuwing.

Welke technische support moet de provider bieden?

Als er om 2 uur 's nachts voor je event iets misgaat, heb je snelle antwoorden nodig.

• Technisch kanaal: toegang tot developers, niet alleen tot algemene support
• Gedocumenteerde SLA: toegezegde responstijden
• Community: forum of Slack om vragen te beantwoorden
• Technische onboarding: begeleide integratiesessie

Eis dat de SLA drie dingen met concrete cijfers vastlegt: tijd tot eerste reactie per severiteit, gedekte tijdvensters en wat er gebeurt bij overtreding. Een toezegging zonder consequentie is slechts een intentieverklaring. En vraag naar het changewindow: een platform dat op een vrijdag van een verkoopstart naar productie deployt, heeft een procesprobleem, geen technisch probleem.

Hoe kies ik de juiste ticketing-API?

Een goede ticketing-API versnelt je ontwikkeling, vermindert bugs en laat je gepersonaliseerde ervaringen bouwen. Ze vormt ook de basis om een embedded verkoopwidget in je eigen website te integreren of je metrics-dashboard aan te sluiten. Een slechte API houdt je gevangen in beperkingen die je te laat ontdekt. Investeer tijd in evaluatie voordat je je vastlegt: vraag toegang tot de sandbox, test de kritieke endpoints en praat met het technische team. De juiste keuze bespaart je maanden frustratie.

Negen concrete controles voor die evaluatie:

• Vraag om het OpenAPI-bestand, niet om de HTML-documentatie. Bestaat het niet, genereer de client dan zelf en reken dat mee in de projectkosten.
• Eis PKCE en exacte validatie van de redirect URI als er OAuth 2.0 wordt gebruikt, zoals RFC 9700 voorschrijft.
• Test de idempotentie: stuur dezelfde orderaanmaak twee keer en controleer dat er maar één order wordt aangemaakt.
• Verifieer een webhook-handtekening handmatig voordat je op de library vertrouwt, en stel een tijdstolerantie in die niet nul is.
• Laat je endpoint opzettelijk falen en meet hoeveel retries er binnenkomen, hoe lang dat duurt en met welke headers.
• Dupliceer een webhook en controleer dat je systeem niet twee keer hetzelfde ticket verkoopt.
• Vraag naar de gebruikslimieten per key en of de API 429 teruggeeft met Retry-After.
• Controleer het foutformaat: application/problem+json met type, title, status, detail en instance bespaart weken.
• Vraag naar de Sunset-header en naar het versioneringsbeleid vóórdat je tekent, niet wanneer de aankondiging binnenkomt.

Bronnen

• OpenAPI Specification v3.1.0, 15 februari 2021 (OpenAPI Initiative)
• OpenAPI/Swagger Specification (SmartBear, Swagger)
• OAuth 2.0, officiële pagina van de standaard
• RFC 6749: The OAuth 2.0 Authorization Framework (IETF)
• RFC 9700: Best Current Practice for OAuth 2.0 Security (IETF, 2025)
• RFC 9457: Problem Details for HTTP APIs (IETF, 2023)
• RFC 6585: Additional HTTP Status Codes, april 2012 (IETF)
• RFC 8594: The Sunset HTTP Header Field, mei 2019 (IETF)
• Semantic Versioning 2.0.0, specificatie (Spaanse versie)
• Receive Stripe events in your webhook endpoint, officiële documentatie van Stripe
• Gedelegeerde Verordening (EU) 2018/389, technische reguleringsnormen voor sterke cliëntauthenticatie (EUR-Lex)
• Verordening (EU) 2016/679, Algemene Verordening Gegevensbescherming (EUR-Lex)