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



WAT KAN ER MET EEN API-KOPPELING GEREGELD WORDEN?

De opties zijn:

-    Invoeren en bewerken van producties en voorstellingen

Aan het begin van een nieuw theaterseizoen dienen de producties en voorstellingen in Podiumkunst.info ingevoerd te worden. Zijn er gedurende het seizoen wijzigingen (zaalwisselingen, annuleringen, ect), dan dient dit door de aanbieder aangepast te worden. Afnemers kunnen zelf niets wijzigingen. De aanbieders zijn leidend.

-    Maken van financiële afspraken

Voor elke voorstelling in een zaal, die is aangesloten bij Podiumkunst.info 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 kunt u desgewenst ophalen naar uw boekingssysteem. De meeste theaters actualiseren hun cijfers elke nacht, sommige theaters doen dit elk uur en een enkel theater voert de standen handmatig in en 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 database van Podiumkunst.info, krijgt deze een uniek nummer, het zogenaamde PKI-nummer. Het PKI-nummer heeft het volgende format:

NL-00-000-00000|00000

Dit is opgebouwd uit het productie-ID voor de streep (|) en het voorstellingsnummer binnen die productie na de streep.

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 Podiumkunst.info. Soms maken wij keuzes die niet voor iedereen meteen logisch zijn. Om het juiste ID voor een theater of zaal te kunnen vinden, hebben we een hulppagina aangemaakt. In principe proberen we elk podium in onze database te zetten, ongeacht of de organisatie gebruiker is van onze applicatie.

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

GET {{url}}/rest/theaters.json

Zalen heten hier "theater_locations".


Producenten

Ook producenten worden door ons aangemaakt. Elke producent krijgt een ID-nummer, dat u kunt koppelen aan de producent in uw boekingssysteem.

Het producentnummer wordt opgenomen in het PKI-nummer van elke productie. Het is mogelijk om achteraf de producent te wijzigen. Dit gaat helaas niet via de API. Uw gebruiker zal de producent zowel in het boekingssysteem als in de online applicatie aan moeten passen. Het PKI-nummer van de productie wijzigt echter niet! Het ID van de oude producent blijft onderdeel van het voorstellingsnummer.


De ID's van producenten kunt u ophalen middels deze call:

GET {{url}}/rest/producers.json

De respons bevat echter àlle producenten, terwijl een impresariaat alleen toegang heeft tot de producenten waarvoor wij een relatie hebben gelegd.

Het komt voor dat een producent meer dan eens voorkomt in de respons. Sommige producenten hebben namelijk meerdere accounts in gebruik. In dit geval kunt u in de respons niet vinden welk producenten-ID gekoppeld is aan het impresariaat waarvoor u de koppeling maakt. Vraag het in zo'n geval na bij uw contactpersoon van het impresariaat. Bij het aanmaken van producenten communiceren wij ook altijd het ID-nummer.


PRODUCTIES EN VOORSTELLINGEN

Alle parameters voor het invoeren en wijzigen van producties en voorstellingen worden beschreven in de documentatie bij de betreffende API-calls. Toch behoeft de documentatie hier en daar wat extra toelichting, omdat het gebruik van de parameters bepaalde gevolgen kan hebben, die niet technisch van aard zijn.

De kenmerken voor een voorstelling worden meegegeven aan de performance in de vorm van forms. De toegestane waarden zijn regular, school, location, festival, foreign, education, reading, preview, workshop, registration, fpk_regular, fpk_school_po, fpk_school_vo, fpk_education, fpk_reading en fpk_other.

Alle waarden, die beginnen met fpk_ zijn specifiek bedoeld voor gebruik in de verantwoordingsmodule van Fonds Podiumkunsten. Hiervan mag er maximaal 1 worden toegekend.

De waarden school en preview zorgen er mede voor, dat een afnemer geen verzoek ontvangt om de voorstelling te koppelen. Dit geldt ook voor:

-    status anders dan agreed

-    private = true (voor besloten voorstellingen)

-    type = montage



FINANCIËLE AFSPRAKEN

De procedure voor het maken van financiële afspraken is als volgt:

  1. De aanbieder maakt een concept-afspraak.
  2. De aanbieder stelt de afspraak voor aan de afnemer.
  3. De afnemer ontvangt een e-mail, waarin verteld wordt dat er een voorstel klaar staat.
  4. De afnemer keurt het voorstel goed of af.
  5. De aanbieder ontvangt een e-mail met de reactie van de afnemer.

Wordt de afspraak goedgekeurd, dan is het proces op dit moment voltooid.
Indien het voorstel wordt afgekeurd volgen er een aantal extra stappen:

  • De aanbieder past het afgekeurde voorstel aan.
  • Stap 2 t/m 5 worden herhaald


Mocht er aanleiding zijn om een goedgekeurde afspraak achteraf toch nog te wijzigen, dan bestaat de mogelijkheid om de afspraak open te breken en te herzien.

  1. De aanbieder gebruikt de mogelijkheid om een aangepast voorstel te maken. Er wordt een nieuwe concept-afspraak aangemaakt, terwijl de oude afspraak voorlopig geldig blijft.
  2. De aanbieder stelt de nieuwe afspraak voor aan de afnemer.
  3. De afnemer keurt het voorstel goed. Hiermee wordt de oude afspraak ongeldig en de nieuwe afspraak geldig gemaakt.


Per voorstelling kan er slechts 1 afspraak worden gemaakt, tenzij de goedgekeurde afspraak wordt herzien.
Een afspraak kan alleen uit de applicatie verwijderd worden als deze de status "concept" heeft. Is de afspraak al voorgesteld, dan kan het concept niet meer verwijderd worden. Overigens is het niet mogelijk om een concept te verwijderen via de koppeling. Dit zal de gebruiker altijd in de applicatie zelf moeten doen.

Hoe werkt dit allemaal via de koppeling?
Om een concept aan te maken, gebruik je een van de volgende calls:
POST /rest/impresario/{impresario}/financial-agreements/new-buyout.{_format}
POST /rest/impresario/{impresario}/financial-agreements/new-partage.{_format}
POST /rest/impresario/{impresario}/financial-agreements/new-rent.{_format}
POST /rest/impresario/{impresario}/financial-agreements/new-suppletion.{_format}
POST /rest/impresario/{impresario}/financial-agreements/new-volume.{_format}

Moet het concept nog aangepast worden, dan gebruik je deze call:
PUT /rest/impresario/{impresario}/financial-agreements/{agreement}/edit-buyout.{_format}
of de call voor een van de andere type afspraken.

Is het concept klaar, dan kan de afspraak met de volgende call worden voorgesteld aan de afnemer:
PUT /rest/impresario/{impresario}/financial-agreements/{agreement}/propose.{_format}

Moet een goedgekeurde afspraak herzien worden, gebruik dan deze call:
POST /rest/impresario/{impresario}/financial-agreements/{agreement}/replace-buyout.{_format}
of de call voor een van de andere type afspraken.



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 wordt wel door een enkel theater gebruikt, maar door Podiumkunst.info niet actief gestimuleerd om te gebruiken. In onze webomgeving worden deze kaarten getoond onder "overig".

Bovengenoemde definities gelden voor kaarten, die de bezoeker daadwerkelijk heeft aangeschaft. Daarnaast worden ook reserveringen inzichtelijk gemaakt:
reservations = reserveringen = alle kaarten die niet betaald EN/OF niet geprint zijn, maar wel al zijn toegekend aan een bezoeker. Deze omschrijving is bedoeld als een soort processchema:
- niet betaald = reservering,
-    maar als het vrijkaarten zijn worden die niet betaald, dus dan kan de printstatus doorslaggevend zijn. Is een vrijkaart geprint, dan is dit geen reservering meer. Tot die tijd wel.