.. _onlineboeking: Online Boeking ============== Huidige versie: 0.2.0 Globaal overzicht ----------------- De Online Boeking API werkt nauw samen met de APIs :ref:`Contactformulieren ` en :ref:`Arrangementen `. Om online boeken snel te integreren kun je ook gebruik maken van onze `Javascript-library `_. Beschikbare Dagen ----------------- .. http: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**: .. sourcecode:: http 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 int arrangement_id: **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. :json array producten: **Verplicht** Een lijst met te boeken boekingsregels, ieder element is een combinatie van een ``arrangementsregel_id`` en een aantal. :json int producten[].arrangementsregel_id: **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. :json int producten[].aantal: **Verplicht** Het aantal te boeken eenheden :json date begin: Een ISO8601-geformatteerde datum, het begin van het te controleren tijdsbestek. Standaardwaarde: vandaag :json date eind: Een ISO8601-geformatteerde datum, het eind van het te controleren tijdsbestek. Standaardwaarde: vandaag + 90 dagen **Voorbeeld response**: .. sourcecode:: http 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" ] :statuscode 200: Invoer geaccepteerd :statuscode 406: Fout in de invoer :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 ------------------ .. http: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**: .. sourcecode:: http 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 int arrangement_id: **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. :json array producten: **Verplicht** Een lijst met te boeken boekingsregels, ieder element is een combinatie van een ``arrangementsregel_id`` en een aantal. :json int producten[].arrangementsregel_id: **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. :json int producten[].aantal: **Verplicht** Het aantal te boeken eenheden :json date datum: **Verplicht** Een ISO8601-geformatteerde datum waarop de beschikbare startmomenten gevraagd worden. **Voorbeeld response**: .. sourcecode:: http 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" ] :statuscode 200: Invoer correct :statuscode 406: Fout in de invoer :json: Een lijst van ISO8601-geformatteerde tijden waarop het mogelijk is om te boeken. Tegoedbonnen controleren ------------------------ .. http: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**: .. sourcecode:: http 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 int arrangement_id: **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. :json array producten: **Verplicht** Een lijst met te boeken boekingsregels, ieder element is een combinatie van een ``arrangementsregel_id`` en een aantal. :json int producten[].arrangementsregel_id: **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. :json int producten[].aantal: **Verplicht** Het aantal te boeken eenheden :json date datum: **Verplicht** Een ISO8601-geformatteerde datum waarop de beschikbare startmomenten gevraagd worden. :json array vouchers[]: **Verplicht** een lijst van strings met tegoedbonnen die gecontroleerd moeten worden. **Voorbeeld response**: .. sourcecode:: http 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" } } :statuscode 200: Invoer correct :statuscode 406: Fout in de invoer :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 ------------------------ .. http:get:: /api2/onlineboeking/controleerkortingscode Via dit endpoint kunnen kortingscodes gecontroleerd worden op geldigheid :query string kortingscode: De code van de kortingscode :query date datum: De ISO8601-datum waarop de kortingscode wel of niet geldig moet zijn :query int arrangement: Het ID van het arrangement waarop de kortingscode wel of niet geldig moet zijn Voorbeeld van geldige kortingscode ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ **Request**: .. http:get:: /api2/onlineboeking/controleerkortingscode .. sourcecode:: http GET /api2/onlineboeking/controleerkortingscode?kortingscode=test1234&datum=2019-03-19&arrangement=2 HTTP/1.1 Host: demo.recras.nl Accept: application/json **Response**: .. sourcecode:: http HTTP/1.1 200 OK Content-Type: application/json { "naam": "Testcode", "percentage": 25 } :json string naam: De naam van de kortingscode :json int percentage: Het kortingspercentage van de kortingscode Voorbeeld van ongeldige kortingscode ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ **Request**: .. sourcecode:: http GET /api2/onlineboeking/controleerkortingscode?kortingscode=test1234&datum=2015-03-19&arrangement=20 HTTP/1.1 Host: demo.recras.nl Accept: application/json **Response**: .. sourcecode:: http HTTP/1.1 200 OK Content-Type: application/json false Boeking reserveren ------------------ .. http:post:: /api2/onlineboeking/reserveer Met dit endpoint is het mogelijk een boeking in Recras te maken. **Voorbeeld request**: .. sourcecode:: http 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 int arrangement_id: **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. :json array producten: **Verplicht** Een lijst met te boeken boekingsregels, ieder element is een combinatie van een ``arrangementsregel_id`` en een aantal. :json int producten[].arrangementsregel_id: **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. :json int producten[].aantal: **Verplicht** Het aantal te boeken eenheden :json datetime begin: **Verplicht** Een ISO8601-geformatteerde weergave van het startmoment van de boeking :json string betaalmethode: **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``) :json string status: 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`` :json boolean stuur_bevestiging_email: Of er een bevestigingsmail verstuurd moet worden na het reserveren. Alleen beschikbaar voor boekingen met betaalmethode ``factuur``. Standaardwaarde is ``true``. :json string kortingscode: Een optionele kortingscode. Een ongeldige kortingscode (niet-bestaand, of niet geldig op de gekozen datum) telt als ongeldige invoer (zie hieronder). :json array vouchers[]: 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. :json object contactformulier: **Verplicht** Ingevuld contactformulier dat hoort bij dit arrangement. Voor meer informatie, zie de documentatie voor `_ContactformulierenSubmit` en `_arrangementen`. :json object mollie_params: 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. :json URL redirect_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**: .. sourcecode:: http HTTP/1.1 200 OK Content-Type: application/json { "status":"reservering", "message":"Boeking gemaakt", "boeking_id":42, "klant_id":63 } :statuscode 200: Boeking gemaakt :statuscode 403: Gebruiker heeft onvoldoende rechten :statuscode 406: 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 string status: De status van de gemaakte boeking. Deze kan een Boekingsstatus zijn of ``betaling benodigd``. :json string message: Een bericht dat de status beschrijft. :json int boeking_id: Het ``id``-nummer van de gemaakte boeking. Alleen beschikbaar voor gebruikers met het recht ``editBoeking``. :json int klant_id: Het ``id``-nummer van de gemaakte of gematchte klant. Alleen beschikbaar voor gebruikers met het recht ``editBoeking``. :json uri payment_url: 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 ================================================== .. _net-price-0: 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.