Boekingen ========= Huidige versie: 1.1.0 Create ------ .. http:post:: /api2/boekingen Maak een nieuwe boeking aan **Voorbeeld request**: .. sourcecode:: http POST /api2/boekingen HTTP/1.1 Host: demo.recras.nl Accept: application/json { "klant_id": 47, "begin": "2014-01-01T15:00:00+01:00", "personen": 15, "arrangement_id": 2, "arrangement": "Klimmen en barbecue" } :json integer klant_id: **Verplicht** Het ``id`` van een klant :json datetime begin: **Verplicht** Beginmoment van de boeking :json integer personen: **Verplicht** De groepsgrootte :json string status: Default: *informatie* De status van de boeking (voor mogelijke statussen zie :ref:`boekingsstatus`) :json string arrangement: De naam van het arrangement zoals die naar de klant wordt weergegeven :json integer boeking_id: Het ``id`` van de boeking waar deze boeking op gebaseerd is. Deze kan niet in combinatie met de volgende velden gestuurd worden: ``arrangement_id``, ``book_process_id``, ``product_id`` :json integer arrangement_id: Het ``id`` van het arrangement waar deze boeking op gebaseerd is :json integer book_process_id: Het ``id`` van het boekproces waar deze boeking op gebaseerd is :json integer product_id: Het ``id`` van het product waar deze boeking op gebaseerd is :json date status_vervaldatum: De datum waarop de optie/reservering zal vervallen :json string bijzonderheden: Bijzonderheden van deze boeking die voor personeel en leveranciers van belang zijn **Voorbeeld response**: .. sourcecode:: http HTTP/1.1 201 Created Content-Type: application/json { "id": 34, "klant_id": 47, "datum": "2014-01-01", "status": "informatie", "arrangement": "Klimmen en barbecue", "personen": 15, "status_updated_at": "2014-10-29T10:53:15+01:00", "arrangement_id": 2, "online_boeking": false, "status_vervaldatum": null, "bijzonderheden": "", "conceptfactuur_na_dagen": null, "referentie": "47-2", "boekingsregels": [ { "id": 132, "locatie_id": 2, "aantal": 15, "begin": "2014-01-01T18:00:00+01:00", "eind": "2014-01-01T20:00:00+01:00", "minimum_aantal": 0, "beschrijving": "Genieten van onze heerlijke BBQ", "opmerking": null, "betaald_bedrag": null, "betaal_datum": null, "betaal_opmerking": null, "herinnering_leverancier": null, "product_id": 5 }, { "id": 133, "locatie_id": 1, "aantal": 15, "begin": "2014-01-01T15:30:00+01:00", "eind": "2014-01-01T18:00:00+01:00", "minimum_aantal": 8, "beschrijving": "Met de hele groep, onder begeleiding, heerlijk klimmen.", "opmerking": null, "betaald_bedrag": null, "betaal_datum": null, "betaal_opmerking": null, "herinnering_leverancier": null, "product_id": 6 }, { "id": 134, "locatie_id": 2, "aantal": 15, "begin": "2014-01-01T15:00:00+01:00", "eind": "2014-01-01T15:30:00+01:00", "minimum_aantal": 0, "beschrijving": "Ontvangst met koffie,thee op het Klimbos terras", "opmerking": null, "betaald_bedrag": null, "betaal_datum": null, "betaal_opmerking": null, "herinnering_leverancier": null, "product_id": 3 } ], "kosten": { "klant_id": 47, "opmerking": null, "betaaltermijn": 14, "referentie_klant": null, "calculated_totaalbedrag_inclusief_btw": 643.95, "bedrijf_id": 1, "boeking_id": 34, "regels": [ { "id": 285, "naam": "Klimmen en barbecue", "type": "groep", "kortingspercentage": 0, "kortingomschrijving": null, "children_visible": false, "regels": [ { "id": 288, "naam": "Ontvangst koffie / thee", "type": "item", "kortingspercentage": 0, "kortingomschrijving": null, "aantal": 15, "bedrag": 2.5, "btw_percentage": 6, "product_id": 3, "boekingsregel_id": 134 }, { "id": 287, "naam": "Groepen klimmen", "type": "item", "kortingspercentage": 0, "kortingomschrijving": null, "aantal": 15, "bedrag": 15, "btw_percentage": 6, "product_id": 6, "boekingsregel_id": 133 }, { "id": 286, "naam": "Basis BBQ", "type": "item", "kortingspercentage": 0, "kortingomschrijving": null, "aantal": 15, "bedrag": 23, "btw_percentage": 6, "product_id": 5, "boekingsregel_id": 132 } ] } ] } } :resheader Location: De locatie van de nieuwe boeking :statuscode 201: Boeking gemaakt :statuscode 406: Fout in de invoer :statuscode 403: Gebruiker heeft het recht ``createBoeking`` niet Read ---- .. _BoekingenEmbedParameter: .. http:get:: /api2/boekingen Verkrijg een lijst van boekingen :query integer page: Default: *1*, minimum: *1* De pagina weer te geven :query integer page_size: Default: *100* Het aantal boekingen per pagina :query integer locatie: Kommagescheiden lijst locatie-ids, vraag boekingen op die een activiteit op één van deze locaties hebben :query periode periode: ISO 8601 time interval. Bv: *P1D* of *2021-11-01T00:00:00+01:00/2021-11-05T00:00:00+01:00* :query string referentiedatum: Default: *boekingsregel* Filter bookings by containing a booking line in the given period (``boekingsregel``, default); by start date of the booking (``startdatum``); or by booking creation date (``created_at``) :query boekingsstatus_ status: Kommagescheiden lijst van statussen :query boolean los_op_planning: Geef alleen boekingen die een product bevatten dat de instelling *los op planning* heeft :query objectnaam embed: Kommagescheiden lijst van objecten om in de resultatenlijst op te nemen. Mogelijke objectnamen zijn ``Klant``, ``boekingsregels``, ``kosten``, ``Klant.Hoofdcontact`` (impliceert ``Klant``), ``Creator``, ``Diensten``, ``Facturen``, ``Facturen._betaald_bedrag`` :query integer klant_id: Geef alleen boekingen van deze klant terug :query string Klant.soort_klant: Kommagescheiden lijst van klantsoorten. Geef alleen boekingen weer waarvan de klant van dit soort is. (impliceert ``embed=Klant``) (Sinds versie 0.1.1) :query integer bedrijf_id: Kommagescheiden lijst van bedrijfsids. Geef alleen boekingen weer waarvan de boeking bij dit bedrijf hoort. (impliceert ``embed=Klant``) (Sinds versie 0.1.1) :query bevat_product_id: Comma separated list of product ids the booking must contain :statuscode 200: OK :statuscode 406: Fout in de parameters **Voorbeeld request**: .. sourcecode:: http GET /api2/boekingen HTTP/1.1 Host: demo.recras.nl Accept: application/json **Voorbeeld response**: .. sourcecode:: http HTTP/1.1 200 OK Content-Type: application/json [ { "id": 75, "klant_id": 49, "referentie": "49-2", "datum": "2015-01-01", "status": "informatie", "arrangement": "Boogschieten met buffet", "personen": 15, "status_updated_at": "2014-06-03T15:11:34+02:00", "arrangement_id": 4, "online_boeking": false, "status_vervaldatum": null, "bijzonderheden": null, }, { "id": 1, "klant_id": 9, "referentie": "9-1", "datum": "2014-05-01", "status": "informatie", "arrangement": "Gezinsmaaltijd", "personen": 10, "status_updated_at": "2013-06-19T10:46:47+02:00", "arrangement_id": 2, "online_boeking": false, "status_vervaldatum": null, "bijzonderheden": "", "conceptfactuur_na_dagen": null } ] .. http:get:: /api2/boekingen/(int:id) Een specifieke boeking :query objectnaam embed: Kommagescheiden lijst van objecten om in de resultatenlijst op te nemen. Zie ook BoekingenEmbedParameter_ :statuscode 200: OK :statuscode 406: Fout in de parameters :statuscode 404: Boeking niet gevonden **Voorbeeld request (embed Klant)**: .. sourcecode:: http GET /api2/boekingen/75?embed=Klant,Klant.Hoofdcontact,boekingsregels,kosten,gefactureerd_bedrag HTTP/1.1 Host: demo.recras.nl Accept: application/json **Voorbeeld response**: .. sourcecode:: http HTTP/1.1 200 OK Content-Type: application/json { "id": 25, "klant_id": 46, "datum": "2014-11-15", "status": "optie", "arrangement": "Klimmen en bbq", "personen": 23, "status_updated_at": "2014-10-14T12:04:05+02:00", "arrangement_id": 2, "online_boeking": false, "status_vervaldatum": "2014-10-13", "bijzonderheden": "", "conceptfactuur_na_dagen": null, "gefactureerd_bedrag": 0, "referentie": "46-1", "boekingsregels": [ { "id": 112, "locatie_id": 2, "aantal": 23, "begin": "2014-11-15T12:00:00+01:00", "eind": "2014-11-15T14:00:00+01:00", "minimum_aantal": 0, "beschrijving": "Genieten van onze heerlijke BBQ", "opmerking": "", "betaald_bedrag": null, "betaal_datum": null, "betaal_opmerking": null, "herinnering_leverancier": null, "product_id": 5 }, { "id": 113, "locatie_id": 1, "aantal": 20, "begin": "2014-11-15T09:30:00+01:00", "eind": "2014-11-15T12:00:00+01:00", "minimum_aantal": 8, "beschrijving": "Met de hele groep, onder begeleiding, heerlijk klimmen.", "opmerking": "", "betaald_bedrag": null, "betaal_datum": null, "betaal_opmerking": null, "herinnering_leverancier": null, "product_id": 6 }, { "id": 114, "locatie_id": 2, "aantal": 23, "begin": "2014-11-15T09:00:00+01:00", "eind": "2014-11-15T09:30:00+01:00", "minimum_aantal": 0, "beschrijving": "Ontvangst met koffie,thee op het Klimbos terras", "opmerking": "", "betaald_bedrag": null, "betaal_datum": null, "betaal_opmerking": null, "herinnering_leverancier": null, "product_id": 3 } ], "Klant": { "id": 46, "displaynaam": "Restaurant de Dinkel", "naam": "Restaurant de Dinkel", "adres": "", "postcode": "", "plaats": "Dinxperloo", "provinciecode": null, "website": "", "bedrijf_id": 1, "soort_klant": null, "afdeling": null, "factuur_adressering": null, "Hoofdcontact": { "id": 41, "voornaam": "Fiona", "achternaam": "Teggartz", "geslacht": "onbekend", "aanhef": "", "adres": "", "postcode": "", "plaats": "", "telefoon1": "", "telefoon2": "", "email1": "", "email2": "", "hoofdcontact": true } }, "kosten": { "klant_id": 46, "opmerking": "", "betaaltermijn": 14, "referentie_klant": "", "calculated_totaalbedrag_inclusief_btw": 886.5, "bedrijf_id": 1, "boeking_id": 25, "regels": [ { "id": 236, "naam": "Klimmen en bbq", "type": "groep", "kortingspercentage": 0, "kortingomschrijving": "", "children_visible": false, "regels": [ { "id": 239, "naam": "Ontvangst koffie / thee", "type": "item", "kortingspercentage": 0, "kortingomschrijving": "", "aantal": 23, "bedrag": 2.5, "btw_percentage": 6, "product_id": 3, "boekingsregel_id": 114 }, { "id": 238, "naam": "Groepen klimmen", "type": "item", "kortingspercentage": 0, "kortingomschrijving": "", "aantal": 20, "bedrag": 15, "btw_percentage": 6, "product_id": 6, "boekingsregel_id": 113 }, { "id": 237, "naam": "Basis BBQ", "type": "item", "kortingspercentage": 0, "kortingomschrijving": "", "aantal": 23, "bedrag": 23, "btw_percentage": 6, "product_id": 5, "boekingsregel_id": 112 } ] } ] } } Update ------ .. http:put:: /api2/boekingen/(int:id) Update een bestaande boeking. :json int id: Het ``id``-nummer, kan niet aangepast worden :json string klant_id: Het ``id``-nummer van de klant, kan niet aangepast worden :json date datum: *Deprecated* De datum van de boeking, kan niet aangepast worden :json string status: De status van de boeking (voor mogelijke statussen zie :ref:`boekingsstatus`) :json string arrangement: De naam van het arrangement zoals gepresenteerd aan de klant :json int personen: Het aantal personen van de boeking :json datetime status_updated_at: Het moment dat de status van deze boeking voor het laatst gewijzigd is. Kan niet aangepast worden :json int arrangement_id: Het ``id``-nummer van het arrangement op basis waarvan deze boeking is gemaakt, kan niet aangepast worden :json boolean online_boeking: Of deze boeking door de Online Boeking module is aangemaakt. Kan niet aangepast worden :json date status_vervaldatum: Vervaldatum van status. Alleen geldig voor boekingen met status *informatie*, *interesse*, *optie* en *reservering* :json string bijzonderheden: Opmerkingen voor intern gebruik :json int conceptfactuur_na_dagen: Hoeveel dagen na de boeking een conceptfactuur gemaakt moet worden. Een negatief getal zorgt er voor dat er voor de boekingsdatum een conceptfactuur wordt gemaakt. *null* betekent dat er geen conceptfactuur gemaakt zal worden. :json string referentie: De referentie van de boeking. Kan niet aangepast worden :json array boekingsregels: De lijst van boekingsregels van deze boeking. Boekingsregels kunnen toegevoegd, verwijderd of aangepast worden. Moet tegelijk met het veld ``kosten`` aangepast worden. Als er een nieuwe regel wordt toegevoegd, hoeft geen kostenregel toegevoegd te worden, dit gebeurt automatisch. :json kosten: De kosten-structuur van deze boeking. Kostenregels kunnen toegevoegd, verwijderd of aangepast worden. Moet tegelijk met het veld ``boekingsregels`` aangepast worden. Een kostenstructuur moet voor iedere boekingsregel een corresponderende *item*-regel bevatten **Boekingsregels** :json int boekingsregel.id: ``id``-nummer van de aan te passen boekingsregel. Kan niet aangepast worden. :json string boekingsregel.ref: Zelfgekozen referentie om naar te verwijzen vanuit nieuwe kostenregels. :json int boekingsregel.locatie_id: ``id``-nummer van de locatie waar deze activiteit plaatsvindt. Kan alleen ingesteld worden op locaties waar het opgegeven product kan plaatsvinden. :json int boekingsregel.aantal: *Verplicht voor nieuwe boekingsregels* :json datetime boekingsregel.begin: Begin van de activiteit. Moet kleiner of gelijk zijn dan de corresponderende eind-tijd :json datetime boekingsregel.eind: Moet groter of gelijk zijn dan de corresponderende begin-tijd :json int boekingsregel.minimum_aantal: Kan niet aangepast worden :json string boekingsregel.beschrijving: Beschrijving van de boekingsregel om te tonen aan de klant :json string boekingsregel.opmerking: Opmerking bij de boekingsregel voor personeel en/of leverancier :json float boekingsregel.betaald_bedrag: Bedrag dat voor deze boekingsregel is betaald aan de leverancier :json date boekingsregel.betaal_datum: Datum waarop voor deze boekingsregel is betaald aan de leverancier :json string boekingsregel.betaal_opmerking: Opmerking bij de betaling aan de leverancier :json datetime boekingsregel.herinnering_leverancier: Moment dat voor het laatst een automatische herinnering aan de leverancier is verstuurd. Kan niet aangepast worden :json int boekingsregel.product_id: ``id``-nummer van het product. Dit veld aanpassen past ook ``boekingsregel.minimum_aantal`` aan **Kosten-structuur** :json int kosten.klant_id: *Deprecated* ``id``-nummer van de klant. Kan niet aangepast worden :json string kosten.opmerking: Opmerking voor op de factuur :json int kosten.betaaltermijn: De betaaltermijn in dagen :json string kosten.referentie_klant: Een extra referentie voor de klant :json float kosten.calculated_totaalbedrag_inclusief_btw: Het totaalbedrag wat de klant zou moeten betalen als de boeking gefactureerd wordt. Kan niet aangepast worden :json int kosten.bedrijf_id: ``id``-nummer van het bedrijf waar gemaakte facturen namens verstuurd worden :json int kosten.boeking_id: *Deprecated* ``id``-nummer van de boeking. Kan niet aangepast worden :json array kosten.regels: Lijst van ``kostenregel``-objecten. **Kostenregel** :json int kostenregel.id: ``id``-nummer van de kostenregel. Kan niet aangepast worden :json string kostenregel.boekingsregel_ref: Referentie van nieuwe boekingsregel. Kan niet tegelijk met ``id`` of ``boekingsregel_id`` aangepast worden :json string kostenregel.naam: :json string kostenregel.type: *Verplicht* Type van de kostenregel, mogelijke waarden zijn *groep*, *item* :json float kostenregel.kortingspercentage: Kortingspercentage te berekenen voor dit *item* of deze *groep* :json string kostenregel.kortingomschrijving: Omschrijving van de berekende korting :json boolean kostenregel.children_visible: *Alleen voor groep-regels* Of de onderliggende regels weergegeven moeten worden op de factuur :json array kostenregel.regels: *Alleen voor groep-regels* Lijst van kostenregels :json int kostenregel.product_id: *Alleen voor item-regels* ``id``-nummer van het product. Kan alleen aangepast worden wanneer ``boekingsregel_id`` = *null*. Wordt automatisch aangepast wanneer de corresponderende boekingsregel aangepast wordt. :json int kostenregel.aantal: *Alleen voor item-regels* Aantal eenheden. Kan alleen aangepast worden wanneer ``boekingsregel_id`` = *null*. Wordt automatisch aangepast wanneer de corresponderende boekingsregel aangepast wordt. :json float kostenregel.bedrag: *Alleen voor item-regels* Stuksprijs Wordt automatisch aangepast wanneer de corresponderende boekingsregel aangepast wordt. :json float kostenregel.btw_percentage: *Alleen voor item-regels* BTW-percentage te berekenen Wordt automatisch aangepast wanneer ``kostenregel.product_id`` aangepast wordt. :json int kostenregel.boekingsregel_id: *Alleen voor item-regels* ``id``-nummer van de corresponderende boekingsregel Delete ------ .. http:delete:: /api2/boekingen/(int:id) Delete an existing booking. Not all bookings can be deleted. To check if a booking can be deleted, make a GET request to /api2/boekingen/:id/deletable **Example request**: .. sourcecode:: http DELETE /api2/boekingen/5 HTTP/1.1 Host: demo.recras.nl **Example response**: .. sourcecode:: http HTTP/1.1 200 OK :statuscode 200: Booking deleted .. _boekingsstatus: Statussen van boekingen ----------------------- Iedere boeking in Recras heeft een status. Alle statussen zijn beschreven op `de algemene support-pagina over boekingsstatussen `_. De mogelijke statussen zijn: * *informatie* * *interesse* * *optie* * *pending_online* * *reservering* * *definitief* * *gaande* * *voltooid* * *geannuleerd* HATEOAS Links ------------- Each booking resource should have a ``_links`` map. The followine relations may be present: ``recras:diensten_bij_boeking`` If this link is present, you may follow it to find a list of shifts associated with this booking. ``recras:send_boekingsvoorstel`` If this link is present, you may follow it to send a booking proposal. ``recras:invoices`` If this link is present, you may follow it to find a list if invoices associated with this booking. ``recras:booking:set_status:ongoing`` .. _link-ongoing: If this link is present, you may follow it to set the status of the booking to *ongoing* (``gaande``). In the special case of the booking-status begin set from *finished* to *ongoing*, the link may return 403 response if the authenticated user doesn't have the ``saveOverbooking`` permission, otherwise, it should return a 204 status code. The Recras Point-of-Sale uses this link to set bookings to *ongoing*. New in API version 0.2.1 ``recras:booking:set_status:finished`` .. _link-finished: If this link is present, you may follow it to set the status of the booking to *finished* (``voltooid``). The Recras Point-of-Sale uses this link to set bookings to *finished*. New in API version 0.2.1 ``recras:booking:set_status:confirmed`` .. _link-confirmed: If this link is present, you may follow it to set the status of the booking to *confirmed* (``definitief``). The Recras Point-of-Sale uses this link to set bookings to *confirmed*. New in API version 0.2.1 ``recras:booking:qr`` If this link is present, you may follow it to get the contents of a QR-code that can be used to put the booking to "ongoing" in the POS