Recras koppeling met je website via de API.

Recras is een online boekings- en administratiesysteem voor recreatiebedrijven, van Recras BV in Groningen. Het gaat verder dan reserveren alleen: boekingen, planning, personeelsinzet, facturatie en klantcontact zitten in dezelfde software.

De klanten zijn breed: escaperooms, klimparken, trampolineparken, botenverhuur en rondvaart, watersportbedrijven, musea en attracties, evenementenlocaties en verhuurbedrijven. Volgens Recras werken er ruim driehonderdvijftig organisaties mee en lopen er meer dan zevenhonderdvijftigduizend boekingen per jaar doorheen.

Recras biedt ze alle drie aan en ze zijn geen van drieën fout. Ze verschillen alleen in wat je er later mee kunt.

De WordPress-plugin zet het boekproces in je WordPress-site en is met CSS naar je huisstijl te trekken. Elk boekproces en contactformulier heeft daarnaast een eigen openbare pagina bij Recras, die je in een iframe of achter een link kunt zetten. En er is de API, waarmee je alle onderdelen van het reserveringssysteem zelf in je site bouwt.

Wij bouwen op de API, met de JavaScript-bibliotheek van Recras voor het boekproces zelf. Dat is meer werk, maar het is de enige manier waarop je arrangementen echte pagina’s van jouw site worden in plaats van inhoud die er toevallig in hangt.

Meer dan alleen boeken. De documentatie is openbaar en beschrijft onder andere arrangementen en producten, de beschikbaarheid van allebei, boekingen, contacten en klanten, contactformulieren, facturen en betalingen, kortingscodes, tegoedbonnen, diensten en webhooks.

Dat betekent dat een integratie verder kan gaan dan een knop op een pagina. Een aanvraagformulier op je site kan als contact in Recras belanden, een tegoedbon kan online worden verkocht, en met webhooks krijg je bericht zodra er iets verandert in plaats van dat je site blijft vragen of er al nieuws is. Voor buitenactiviteiten combineren we het aanbod soms met het weer; zie KNMI API koppelen.

De sleutel gaat mee als Bearer-token in de header. Een klein deel van de endpoints is openbaar, de rest niet, en dat onderscheid bepaalt wat er in de browser mag draaien en wat aan de serverkant hoort.

De sleutel maak je aan in Recras zelf. Hij gaat mee in een Authorization-header als Bearer-token, volgens RFC 6750. De meeste endpoints werken alleen met die sleutel; de paar die openbaar zijn geven beperkte informatie, en alleen die horen in de browser.

Daarna bepalen we welke arrangementen en producten een eigen pagina krijgen, en halen we die op. Lijsten komen in pagina’s van standaard 100 resultaten. De header X-Total-Count zegt hoeveel het er in totaal zijn, en de Link-header geeft het adres van de volgende pagina. Wie alleen de eerste pagina leest, mist bij een groter aanbod ongemerkt de rest.

Het boekproces zelf zetten we in de pagina met de JavaScript-bibliotheek van Recras, en de beschikbaarheid vragen we op in de stap waar hij telt. Voor de livegang testen we een boeking van begin tot eind, tot hij in Recras staat. Andere systemen voor dagrecreatie en verblijf staan bij elkaar op de pagina over recreatie.

Recras verstuurt webhooks bij twee soorten gebeurtenissen. Er zijn eigen gebeurtenissen, zoals BookingDefinitive en InvoiceDefinitive, en gebeurtenissen per onderdeel: een record dat is aangemaakt, bijgewerkt of verwijderd. Het bericht zit steeds in dezelfde omhulling met version, data en meta.

De documentatie is er duidelijk over: webhooks zijn alfafunctionaliteit, in versie 0.1, en kunnen zonder aankondiging veranderen of breken. Wij gebruiken ze om de site sneller bij te werken, niet als enige bron. Er loopt altijd een periodieke controle naast.

Een fout die vaak voorkomt is de sleutel op de verkeerde plek. De bibliotheek voor het boekproces heeft hem niet nodig, dus hoort hij nergens in de paginabron te staan. Een tweede: beginnen met het iframe en later toch eigen pagina’s willen. Dat is geen aanpassing maar een nieuwe bouw. Wat daarbij komt kijken lees je bij Design & Development.

Hier zit het verschil tussen een site die boekingen aanneemt en een site die boekingen oplevert.

Iemand die een vrijgezellenfeest, een bedrijfsuitje of een dagje uit met de kinderen zoekt, typt dat in met een plaatsnaam erachter. Daar wil je met een pagina staan die over precies dat arrangement gaat: wat het is, voor hoeveel personen, wat het kost, hoe lang het duurt en wat er wel en niet bij zit. Die pagina kun je alleen maken als de arrangementen uit Recras echte pagina’s van jouw site zijn.

Zit het boekproces in een iframe, dan heb je één pagina die "Boeken" heet en verder niets. Het boeken werkt, maar er valt niets te vinden en niets naar te linken. Met de koppeling die wij bouwen krijgt elk arrangement een eigen adres, een eigen titel en een eigen omschrijving, en staat de boekknop daar gewoon op.