Informatie voor boekingssystemen

Gewijzigd op Sun, 21 May 2023 om 07:29 PM

Elk theaterseizoen kent nieuwe producties en voorstellingen, maar ook reprises. Aanbieders voeren al deze producties in hun boekingssysteem in. De koppeling tussen een boekingssysteem en DIP is erop gericht alle relevante gegevens van een productie en de bijbehorende voorstellingen vanuit het boekingssysteem over te zetten naar de DIP-database. Zodat afnemers deze voorstellingen van actuele verkoopcijfers kunnen voorzien. Daarnaast kunnen beide partijen financiële afspraken vastleggen via de applicatie, met het boekingssysteem als bron.

WAT KAN ER MET EEN API-KOPPELING GEREGELD WORDEN?

Invoeren en bewerken van producties en voorstellingen
Aan het begin van een nieuw theaterseizoen moeten de producties en voorstellingen ingevoerd worden in DIP. Zijn er gedurende het seizoen wijzigingen (zaalwisselingen, annuleringen, et cetera)? Dan moet de aanbieder dit aanpassen. Afnemers kunnen zelf niets wijzigingen. De aanbieder is leidend.
Maken van financiële afspraken
Voor elke voorstelling in een bij DIP aangesloten zaal kunnen financiële afspraken worden gemaakt. De actuele gebruikerslijst is altijd opvraagbaar via onze website. Ook hier heeft de aanbieder het initiatief.
Ophalen van kaartstanden
Aangesloten theaters geven per voorstelling verkochte kaarten en reserveringen door. Deze kun je desgewenst doorsturen naar jouw boekingssysteem. De meeste theaters actualiseren hun cijfers elke nacht. Sommige theaters doen dit elk uur en een enkel theater voert de standen handmatig. Het streven is dan om ze wekelijks door te geven.

Bekijk hier de workflow met de benodigde API-calls.

Id-NUMMERS

Voorstellingen

Zodra een voorstelling wordt opgeslagen in de DIP-database, krijgt deze een uniek nummer: het zogenaamde DIP-id. Het DIP-id heeft het volgende format: NL-00-000-0000000|000000

Met voor de streep (|) het productie-id en na de streep het voorstellingsnummer binnen die productie..

Deze nummercombinatie wordt in principe overal toegepast om voorstellingen te identificeren. Op basis hiervan wordt bijvoorbeeld een financiële afspraak aan een voorstelling gekoppeld. Ook de afnemers maken gebruik van dit nummer. Aan hun kant dient het als basis om de actuele kaartstanden door te kunnen geven.

In de API-calls wordt het nummer altijd gesplitst toegepast, dus als id van 'production' en 'number van performances'.

Theaters

Theaters en hun bijbehorende zalen worden aangemaakt door DIP. Soms maken wij keuzes die niet voor iedereen meteen logisch zijn. Ben je op zoek naar het juiste id voor een theater of zaal? Kijk op de hulppagina. In principe proberen we elk podium in onze database te zetten, ongeacht of de organisatie een DIP-gebruiker is.

De id's van alle theaters en bijbehorende zalen kunnen worden opgehaald via de call:

GET {{url}}/theaters

Zalen heten hier 'theater_locations'.

Producenten

Ook producenten worden door ons aangemaakt. Als producent krijg je een id-nummer, dat je kunt koppelen aan de producent in jouw boekingssysteem.

Het producentnummer wordt opgenomen in het DIP-id van elke productie. Het is mogelijk om achteraf de producent te wijzigen. Dit gaat helaas niet via de API. Jouw gebruiker zal de producent zowel in het boekingssysteem als in de online applicatie aan moeten passen. Let op: Het DIP-id van de productie verandert niet! Het id van de oude producent blijft onderdeel van het productienummer.

De id's van producenten kun je ophalen middels deze call:

GET {{url}}/producers

De respons bevat álle producenten, terwijl een impresariaat alleen toegang heeft tot de producenten met wie wij een relatie hebben gelegd.

Om een concept aan te maken, gebruik je een call van de vorm:
POST /contracts/{type}/create

waarbij type één van rent, partage, volume, suppletion of buyout is.

Moet het concept nog aangepast worden? Dan gebruik je deze call:
PUT /contracts/{contractId}/{type}/update

Is het concept klaar? Dan kan de afspraak met de volgende call worden voorgesteld aan de afnemer:
PUT /contracts/{contractId}/propose

Moet een goedgekeurde afspraak herzien worden? Gebruik dan deze call:
POST /contracts/{contractId}/{type}/revise

DE DEFINITIES VOOR KAARTSTANDEN

De kaartsoorten die we binnen krijgen zijn:

normal
discount
free
other
complimentary

Hierbij gaan wij uit van de volgende definities:

Normal = normaal = het reguliere tarief voor bezoekers zonder enige bijzonderheden.
Discount = korting = het tarief voor bezoekers die een afwijkend tarief betalen op basis van bepaalde kenmerken (bijvoorbeeld CJP-houders, last-minute-kaarten, etc.).
Free = vrijkaarten = alle gratis kaarten die worden weggegeven (tenzij er een logische reden is om gratis kaarten anders te registreren: dan kunnen gratis kaarten ook als type 'normaal' of 'korting' worden verwerkt).
Other = overig = alle kaarten die niet aan bovenstaande omschrijvingen voldoen.
Complimentary = extra = een term die door enkele theaters wordt gebruikt, maar heeft niet onze voorkeur. In de DIP-omgeving vind je deze kaarten onder 'overig'.

Deze definities gelden voor kaarten die de bezoeker daadwerkelijk heeft aangeschaft.

Daarnaast zijn er ook nog reserveringen:

reservations = reserveringen = alle kaarten die niet betaald EN/OF niet geprint zijn, maar wel al zijn toegekend aan een bezoeker. Een schema:
- Niet betaald = reservering,
- Zijn het vrijkaarten (dus niet betaalde kaarten)? Dan is de printstatus doorslaggevend. Een geprinte vrijkaart is geen reservering meer. Is er nog niet geprint? Dan is de kaart nog wél een reservering.