Online Boeking

Huidige versie: 0.2.0

Globaal overzicht

De Online Boeking API werkt nauw samen met de APIs Contactformulieren en Arrangementen.

Om online boeken snel te integreren kun je ook gebruik maken van onze Javascript-library.

Beschikbare Dagen

POST /api2/onlineboeking/beschikbaredagen

Met dit endpoint is het mogelijk voor een bepaalde combinatie van producten te controleren op welke dagen het mogelijk is om te boeken.

Voorbeeld request:

POST /api2/onlineboeking/beschikbaredagen HTTP/1.1
Host: demo.recras.nl
Content-Type: application/json

{
   "arrangement_id": 2,
   "producten": [
      {"arrangementsregel_id": 1, "aantal": 0},
      {"arrangementsregel_id": 2, "aantal": 2},
      {"arrangementsregel_id": 4, "aantal": 0}
   ],
   "begin": "2015-02-01",
   "eind": "2015-04-01"
}
JSON Parameters:

  • arrangement_id (int) – Verplicht Het id-nummer van het te controleren arrangement. Enkel arrangementen met de eigenschappen mag_online_geboekt_worden_direct_betalen of mag_online_geboekt_worden_achteraf_betalen zijn toegestaan.

  • producten (array) – Verplicht Een lijst met te boeken boekingsregels, ieder element is een combinatie van een arrangementsregel_id en een aantal.

  • producten[].arrangementsregel_id (int) – Verplicht Het arrangementsregel_id waaruit een boekingsregel geproduceerd zal worden. Dit arrangementsregel_id moet voorkomen in de regels van het arrangement opgegeven in de arrangement_id parameter.

  • producten[].aantal (int) – Verplicht Het aantal te boeken eenheden

  • begin (date) – Een ISO8601-geformatteerde datum, het begin van het te controleren tijdsbestek. Standaardwaarde: vandaag

  • eind (date) – Een ISO8601-geformatteerde datum, het eind van het te controleren tijdsbestek. Standaardwaarde: vandaag + 90 dagen

Voorbeeld response:

HTTP/1.1 200 OK
Content-Type: application/json

[
   "2015-02-09",
   "2015-02-11",
   "2015-02-12",
   "2015-02-13",
   "2015-02-14",
   "2015-02-15",
   "2015-02-16",
   "2015-02-18",
   "2015-02-19"
]
Status Codes:
Json:

Een lijst van ISO-8601 (specifieker: JJJJ-MM-DD) geformatteerde datums waarop het mogelijk is om deze combinatie van producten te boeken.

Beschikbare Tijden

POST /api2/onlineboeking/beschikbaretijden

Met dit endpoint is het mogelijk voor een bepaalde combinatie van producten te controleren op welke startmomenten op een bepaalde dag het mogelijk is om te boeken.

Voorbeeld request:

POST /api2/onlineboeking/beschikbaretijden HTTP/1.1
Host: demo.recras.nl
Content-Type: application/json

{
   "arrangement_id": 2,
   "producten": [
      {"arrangementsregel_id": 1, "aantal": 0},
      {"arrangementsregel_id": 2, "aantal": 2},
      {"arrangementsregel_id": 4, "aantal": 0}
   ],
   "datum": "2015-02-22"
}
JSON Parameters:

  • arrangement_id (int) – Verplicht Het id-nummer van het te controleren arrangement. Enkel arrangementen met de eigenschappen mag_online_geboekt_worden_direct_betalen of mag_online_geboekt_worden_achteraf_betalen zijn toegestaan.

  • producten (array) – Verplicht Een lijst met te boeken boekingsregels, ieder element is een combinatie van een arrangementsregel_id en een aantal.

  • producten[].arrangementsregel_id (int) – Verplicht Het arrangementsregel_id waaruit een boekingsregel geproduceerd zal worden. Dit arrangementsregel_id moet voorkomen in de regels van het arrangement opgegeven in de arrangement_id parameter.

  • producten[].aantal (int) – Verplicht Het aantal te boeken eenheden

  • datum (date) – Verplicht Een ISO8601-geformatteerde datum waarop de beschikbare startmomenten gevraagd worden.

Voorbeeld response:

HTTP/1.1 200 OK
Content-Type: application/json

[
   "2015-02-22T11:00:00+01:00",
   "2015-02-22T11:30:00+01:00",
   "2015-02-22T12:00:00+01:00",
   "2015-02-22T12:30:00+01:00",
   "2015-02-22T13:00:00+01:00"
]
Status Codes:
Json:

Een lijst van ISO8601-geformatteerde tijden waarop het mogelijk is om te boeken.

Tegoedbonnen controleren

POST /api2/onlineboeking/controleervoucher

Met dit endpoint is het mogelijk om tegoedbonnen te controleren voor een bepaalde online boeking. Een tegoedbon is geldig voor 1 of meerdere producten.

Voorbeeld request:

POST /api2/onlineboeking/controleervoucher HTTP/1.1
Host: demo.recras.nl
Content-Type: application/json

{
   "arrangement_id": 2,
   "producten": [
      {"arrangementsregel_id": 1, "aantal": 2},
      {"arrangementsregel_id": 2, "aantal": 2},
      {"arrangementsregel_id": 4, "aantal": 0}
   ],
   "datum": "2015-02-22",
   "vouchers": ["qwert-asdfg-zxcvb", "ertyu-dfghj-cvbnm", "invalid-code"]
}
JSON Parameters:

  • arrangement_id (int) – Verplicht Het id-nummer van het te controleren arrangement. Enkel arrangementen met de eigenschappen mag_online_geboekt_worden_direct_betalen of mag_online_geboekt_worden_achteraf_betalen zijn toegestaan.

  • producten (array) – Verplicht Een lijst met te boeken boekingsregels, ieder element is een combinatie van een arrangementsregel_id en een aantal.

  • producten[].arrangementsregel_id (int) – Verplicht Het arrangementsregel_id waaruit een boekingsregel geproduceerd zal worden. Dit arrangementsregel_id moet voorkomen in de regels van het arrangement opgegeven in de arrangement_id parameter.

  • producten[].aantal (int) – Verplicht Het aantal te boeken eenheden

  • datum (date) – Verplicht Een ISO8601-geformatteerde datum waarop de beschikbare startmomenten gevraagd worden.

  • vouchers[] (array) – Verplicht een lijst van strings met tegoedbonnen die gecontroleerd moeten worden.

Voorbeeld response:

HTTP/1.1 200 OK
Content-Type: application/json

{
   "qwert-asdfg-zxcvb": {
      "valid": true,
      "processed": [{
         "regel_id": 1,
         "product_id": 4,
         "prijs_per_stuk": 25,
         "aantal": 2,
      }]
   },
   "ertyu-dfghj-cvbnm": {
      "valid": true,
      "processed": [{
         "regel_id": 2,
         "product_id": 3,
         "prijs_per_stuk": 10,
         "aantal": 1,
      }]
   },
   "invalid-code": {
      "valid": false,
      "reason": "ERR_VOUCHER_INVALID"
   }
}
Status Codes:
Json:

Een object van resultaten, met als keys de opgegeven tegoedbonnen en per tegoedbon een resultaat.

Mogelijke reden van afwijzing:

  • ERR_VOUCHER_INVALID - code bestaat niet

  • ERR_VOUCHER_EXPIRED - tegoedbon is vervallen

  • ERR_VOUCHER_INVALID_PRODUCTS - tegoedbon is niet te gebruiken op producten die geboekt worden in dit arrangement

  • ERR_VOUCHER_USED - tegoedbon is al gebruikt

Kortingscode controleren

GET /api2/onlineboeking/controleerkortingscode

Via dit endpoint kunnen kortingscodes gecontroleerd worden op geldigheid

Query Parameters:

  • kortingscode (string) – De code van de kortingscode

  • datum (date) – De ISO8601-datum waarop de kortingscode wel of niet geldig moet zijn

  • arrangement (int) – Het ID van het arrangement waarop de kortingscode wel of niet geldig moet zijn

Voorbeeld van geldige kortingscode

Request:

GET /api2/onlineboeking/controleerkortingscode
GET /api2/onlineboeking/controleerkortingscode?kortingscode=test1234&datum=2019-03-19&arrangement=2 HTTP/1.1
Host: demo.recras.nl
Accept: application/json

Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "naam": "Testcode",
  "percentage": 25
}
JSON Parameters:

  • naam (string) – De naam van de kortingscode

  • percentage (int) – Het kortingspercentage van de kortingscode

Voorbeeld van ongeldige kortingscode

Request:

GET /api2/onlineboeking/controleerkortingscode?kortingscode=test1234&datum=2015-03-19&arrangement=20 HTTP/1.1
Host: demo.recras.nl
Accept: application/json

Response:

HTTP/1.1 200 OK
Content-Type: application/json

false

Boeking reserveren

POST /api2/onlineboeking/reserveer

Met dit endpoint is het mogelijk een boeking in Recras te maken.

Voorbeeld request:

POST /api2/onlineboeking/reserveer HTTP/1.1
Host: demo.recras.nl
Content-Type: application/json

{
   "arrangement_id":2,
   "producten":[
      {"arrangementsregel_id":1,"aantal":0},
      {"arrangementsregel_id":2,"aantal":2},
      {"arrangementsregel_id":4,"aantal":0}
   ],
   "begin":"2015-02-14T14:00:00+01:00",
   "betaalmethode": "factuur",
   "kortingscode": "test1234",
   "vouchers": ["qwert-asdfg-zxcvb", "ertyu-dfghj-cvbnm"],
   "status":"reservering",
   "stuur_bevestiging_email": true,
   "contactformulier": {
      "contact.naam":"Recras",
      "contact.afdeling": "API ontwikkeling",
      "contactpersoon.voornaam": null,
      "contactpersoon.achternaam": null,
      "contactpersoon.geslacht": "onbekend",
      "contactpersoon.email1": "api@recras.nl",
      "contactpersoon.telefoon1": "050-2112212",
      "contactpersoon.adres":"Kadijk 1",
      "contactpersoon.postcode":"9747AT",
      "contactpersoon.plaats":"Groningen",
      "veel_tekst_0":null
   }
}
JSON Parameters:

  • arrangement_id (int) – Verplicht Het id-nummer van het te controleren arrangement. Enkel arrangementen met de eigenschappen mag_online_geboekt_worden_direct_betalen of mag_online_geboekt_worden_achteraf_betalen zijn toegestaan.

  • producten (array) – Verplicht Een lijst met te boeken boekingsregels, ieder element is een combinatie van een arrangementsregel_id en een aantal.

  • producten[].arrangementsregel_id (int) – Verplicht Het arrangementsregel_id waaruit een boekingsregel geproduceerd zal worden. Dit arrangementsregel_id moet voorkomen in de regels van het arrangement opgegeven in de arrangement_id parameter.

  • producten[].aantal (int) – Verplicht Het aantal te boeken eenheden

  • begin (datetime) – Verplicht Een ISO8601-geformatteerde weergave van het startmoment van de boeking

  • betaalmethode (string) – Verplicht De betaalmethode die voor deze boeking gebruikt wordt. Mogelijkheden: factuur (voor betaling achteraf, alleen mogelijk voor arrangementen met de eigenschap mag_online_geboekt_worden_achteraf_betalen) en mollie (voor betaling direct via de payment provider Mollie, alleen mogelijk voor arrangementen met de eigenschap mag_online_geboekt_worden_direct_betalen)

  • status (string) – De status van de boeking na het reserveren. Alleen beschikbaar voor boekingen met betaalmethode factuur. Standaardwaarde wordt overgenomen uit de Recras-instelling online_boeking_achteraf_betalen_status

  • stuur_bevestiging_email (boolean) – Of er een bevestigingsmail verstuurd moet worden na het reserveren. Alleen beschikbaar voor boekingen met betaalmethode factuur. Standaardwaarde is true.

  • kortingscode (string) – Een optionele kortingscode. Een ongeldige kortingscode (niet-bestaand, of niet geldig op de gekozen datum) telt als ongeldige invoer (zie hieronder).

  • vouchers[] (array) – Een optionele lijst van strings met tegoedbonnen die verwerkt moeten worden op deze boeking. Een ongeldige tegoedbon telt als ongeldige invoer. Het is daarom verstandig om een tegoedbon eerst te controleren.

  • contactformulier (object) – Verplicht Ingevuld contactformulier dat hoort bij dit arrangement. Voor meer informatie, zie de documentatie voor _ContactformulierenSubmit<Contactformulieren opslaan> en _arrangementen<Arrangementen>.

  • mollie_params (object) – Extra parameters om aan de Mollie Create Payment API mee te geven. Alleen mogelijk voor betaalmethode mollie. De parameters amount en redirectUrl zijn hier niet toegestaan.

  • redirect_url (URL) – Een URL waar de klant na de betaling naartoe wordt geleid, ongeacht de status van de betaling. Het is dus aan de server waar redirect_url naar verwijst om de status van de boeking te controleren. Alleen mogelijk voor betaalmethode mollie.

Voorbeeld response:

HTTP/1.1 200 OK
Content-Type: application/json

{
   "status":"reservering",
   "message":"Boeking gemaakt",
   "boeking_id":42,
   "klant_id":63
}
Status Codes:

  • 200 OK – Boeking gemaakt

  • 403 Forbidden – Gebruiker heeft onvoldoende rechten

  • 406 Not Acceptable – Fout in de invoer. Dit kan o.a. duiden op een boeking die te ver/te kort van tevoren wordt gemaakt (onlineboeking_maximaal_vooruit en onlineboeking_minimaal_vooruit van een arrangement), een ongeldig startmoment, een ongeldig (fout ingevuld) contactformulier, een ongeldige betaalmethode, of een overboeking op materiaal en/of locatie.

JSON Parameters:

  • status (string) – De status van de gemaakte boeking. Deze kan een Boekingsstatus zijn of betaling benodigd.

  • message (string) – Een bericht dat de status beschrijft.

  • boeking_id (int) – Het id-nummer van de gemaakte boeking. Alleen beschikbaar voor gebruikers met het recht editBoeking.

  • klant_id (int) – Het id-nummer van de gemaakte of gematchte klant. Alleen beschikbaar voor gebruikers met het recht editBoeking.

  • payment_url (uri) – De URL die gevolgd dient te worden om aan de betalingsplicht te voldoen. (Alleen aanwezig indien status gelijk is aan betaling benodigd)

Please note: Bookings with a net price of EUR 0.00

In the special case of a request to /api2/onlineboeking/reserveer with payment method mollie yielding a booking with a net price of EUR 0.00 or lower (this can happen by the application of vouchers and/or the booking having products with a negative sale price), the redirection to the payment service provider will be omitted. The status field of the returned JSON object will then have the booking status definitief (confirmed) and the payment_url field will be absent. This means the customer may be presented with a message confirming the successful creation of the booking. Recras will follow the same procedure as when in the regular case the ‘payment successful’ notification is received, i.e. booking proposal and invoice will be sent to the customer.