Conventies

Afspraken die voor alle endpoints onder /api/v2 gelden. Eén keer lezen, en de rest van de documentatie leest een stuk sneller.

Authenticatie

Elke aanroep gaat naar het webadres van je eigen ticketshop en draagt je token. Dat token bepaalt om welk account het gaat, dus je stuurt nergens een klantnummer mee. Twee manieren, allebei goed:

Als header, aanbevolen

Access-Token: JOUW_TOKEN

Als parameter, handig om even iets te proberen

?access_token=JOUW_TOKEN

Zonder geldig token, of met een token dat is ingetrokken, krijg je een 401. Een record dat bij een ander account hoort, geeft een 404: je kunt niet zien of het bestaat.

Wat een token mag

Bij het aanmaken kies je wat een token mag. Drie mogelijkheden, los van elkaar aan te vinken:

analytics	Verkoopcijfers opvragen, en de MCP-koppeling gebruiken.
read	Evenementen, voorstellingen, producten en locaties inzien.
write	Diezelfde dingen aanmaken, wijzigen en verwijderen.

Mist je token het benodigde recht, dan krijg je een 403 met de naam van wat er ontbreekt. Geef een token niet meer rechten dan het nodig heeft: een koppeling die alleen rapporteert, heeft genoeg aan analytics.

Foutmeldingen

Elke fout heeft dezelfde vorm:

Antwoord bij een fout

{
  "message": "Validation failed",
  "errors": [
    { "field": "name", "message": "can't be blank" }
  ]
}

message is altijd één regel tekst, nooit een lijst. errors staat er alleen bij als er veldfouten zijn, en is dan altijd een lijst met field en message.

Code	Wanneer
400	Ongeldige invoer, een ontbrekende parameter, of iets dat niet opgeslagen kan worden
401	Ontbrekend, ongeldig of ingetrokken token
404	Het record bestaat niet, of hoort bij een ander account
405	De actie kan niet voor dit account

We geven liever een duidelijke fout dan een getal waar je niets aan hebt. Vraag je bijvoorbeeld om een uitsplitsing die niet bestaat, dan krijg je een 400 met de naam van het veld erin, en geen lege lijst.

Lijsten

Elk lijst-endpoint geeft een envelop terug, geen kaal array:

Antwoord van een lijst

{
  "meta": { "total": 1265, "count": 50, "limit": 50, "offset": 0, "has_more": true },
  "data": [ ... ]
}

total	Alle records die aan je filter voldoen
count	Aantal records in dit antwoord
limit	Gebruikte paginagrootte, standaard 50 en maximaal 200
offset	Vanaf welk record dit antwoord begint
has_more	Of er na deze pagina nog records zijn

Pagineren doe je door offset op te hogen met limit. Vraag je een hogere limit dan het maximum, dan krijg je stil het maximum. De analytics-endpoints gebruiken dezelfde data-sleutel, met een meta-blok dat over de berekening gaat.

Datums, tijden en bedragen

Datums	`jjjj-mm-dd`. Een periode is inclusief: `from` en `to` tellen allebei mee.
Tijdzone	Alles loopt in Nederlandse tijd, zomertijd inbegrepen. Het antwoord zegt dat er zelf bij.
Bedragen	Euro's met twee decimalen. Nooit centen. Ook dat staat in het antwoord, in `amounts_in`.

Lees het meta-blok

Elk antwoord begint met meta, waarin staat wat je precies hebt gekregen: op welke datum er gerekend is, in welke tijdzone, in welke eenheid, en wat er buiten beschouwing is gelaten. Dat is er niet voor de netheid. Het voorkomt dat je cijfers verkeerd uitlegt.