.. _contactformulieren: Contactformulieren ================== Om contactformulieren snel te integreren kun je ook gebruik maken van onze `Javascript-library `_. Changelog --------- 1.1.0 (2020-04-03) The contact form fields are now always embedded (``Velden``), and updates to contact form fields are accepted with regular PUT-back semantics. **Deprecated**: The separate API for contact form fields is now deprecated, and should not be used for new integrations. Read ---- .. http:get:: /api2/contactformulieren Lijst van contactformulieren in Recras. Dit endpoint is publiek toegankelijk. **Voorbeeld request**: .. sourcecode:: http GET /api2/contactformulieren HTTP/1.1 Host: demo.recras.nl Accept: application/json **Voorbeeld response**: .. sourcecode:: http HTTP/1.1 200 OK Content-Type: application/json [ { "id": 1, "naam": "Contactformulier", "Velden": [ { "id": 1, "naam": "Bedrijf of Groepsnaam", "soort_invoer": "contact.naam", "verplicht": false, "mogelijke_keuzes": null, "bijzonderheden_boeking": false, "field_identifier": "contact.naam" }, { "id": 2, "naam": "Afdeling", "soort_invoer": "contact.afdeling", "verplicht": false, "mogelijke_keuzes": null, "bijzonderheden_boeking": false, "field_identifier": "contact.afdeling" } ] }, { "id": 2, "naam": "Standaard Onlineboeking Contactformulier", "Velden": [] }, { "id": 3, "naam": "Kitelessen", "Velden": [] } ] :statuscode 200: OK .. http:get:: /api2/contactformulieren/(int:id) Een specifiek contactformulier. Dit endpoint is publiek toegankelijk. **Voorbeeld request**: .. sourcecode:: http GET /api2/contactformulieren/1 HTTP/1.1 Host: demo.recras.nl Accept: application/json **Voorbeeld response**: .. sourcecode:: http HTTP/1.1 200 OK Content-Type: application/json { "id": 1, "naam": "Contactformulier", "Velden": [] } .. http:get:: /api2/contactformulieren/(int:id)/velden **Deprecated**: since version 1.1.0 this API is deprecated. All users are advised to use the ``Velden`` field on the ``/conctactformulieren/(int:id)`` API. Een lijst van velden van een contactformulier. Het is ook mogelijk de velden met de rest van het formulier op te vragen, gebruik hiervoor ``embed=Velden``. Dit endpoint is publiek toegankelijk. **Voorbeeld request**: .. sourcecode:: http GET /api2/contactformulieren/1/velden HTTP/1.1 Host: demo.recras.nl Accept: application/json **Voorbeeld response**: .. sourcecode:: http HTTP/1.1 200 OK Content-Type: application/json [ { "id": 1, "contactformulier_id": 1, "naam": "Bedrijf of Groepsnaam", "soort_invoer": "contact.naam", "verplicht": false, "mogelijke_keuzes": null, "sort_order": 1, "bijzonderheden_boeking": false, "field_identifier": "contact.naam" }, { "id": 2, "contactformulier_id": 1, "naam": "Afdeling", "soort_invoer": "contact.afdeling", "verplicht": false, "mogelijke_keuzes": null, "sort_order": 2, "bijzonderheden_boeking": false, "field_identifier": "contact.afdeling" } ] :statuscode 200: OK :json integer id: Uniek ``id``-nummer van een veld :json integer contactformulier_id: ``id``-nummer van het contactformulier :json string naam: De naam van het veld zoals in Recras ingesteld :json string soort_invoer: Het soort invoerveld. Mogelijkheden: * ``contact.landcode``: Het veld 'land' van de Klant in Recras - een 2-letterige landcode volgens [ISO 3611-1-](https://nl.wikipedia.org/wiki/ISO_3166-1) * ``contact.naam``: Het veld 'naam' van de Klant in Recras - tekst * ``contact.afdeling``: Het veld 'afdeling' van de Klant - tekst * ``contact.soort_klant``: Het veld 'soort klant' van de Klant * ``contact.extra``: Een extra veld van de Klant * ``contact.website``: Het veld 'website' van de Klant * ``contactpersoon.voornaam``: Het veld 'voornaam' van de Contactpersoon in Recras - tekst * ``contactpersoon.achternaam``: Het veld 'achternaam van de Contactpersoon - tekst * ``contactpersoon.geslacht``: Het veld 'geslacht' van de Contactpersoon (suggestie voor presentatie: ``select``-element met mogelijke opties 'man', 'vrouw', 'onbekend') * ``contactpersoon.adres`` * ``contactpersoon.postcode`` * ``contactpersoon.plaats`` * ``contactpersoon.telefoon1`` * ``contactpersoon.telefoon2`` * ``contactpersoon.email1`` * ``contactpersoon.nieuwsbrieven``: Aan welke nieuwsbrief-lijsten het contactpersoon moet worden toegevoegd - een lijst van ``id``-nummers van nieuwsbrieven. Zie de begeleidende velden ``newsletter_options`` (voorkeur) en ``mogelijke_keuzes``. * ``boeking.datum``: De datum waarop een ``informatie``-boeking wordt aangemaakt - een datumstring volgens [ISO8601](https://en.wikipedia.org/wiki/ISO_8601#Dates)-datumnotering, uitgezonderd het 'ordinal date'-formaat. * ``boeking.starttijd``: De starttijd van de ``informatie``-boeking - een tijdstring volgens [ISO8601](https://en.wikipedia.org/wiki/ISO_8601#Times)-tijdnotering. Fracties van seconden worden niet ondersteund. * ``boeking.groepsgrootte``: Het aantal personen - een geheel positief getal. * ``boeking.arrangement``: Het arrangement op basis waarvan een boeking moet worden gemaakt - een getal dat correspondeerd met een ``id``-nummer uit de arrangementen-API. * ``tekst``: Een vrij veld met tekst (suggestie voor presentatie: HTML ``input``-element) * ``veel_tekst``: Een vrij veld met veel tekst (suggestie voor presentatie: HTML ``textarea``-elemen) * ``keuze``: Een keuze-veld waar meerdere keuzes aangevinkt mogen worden (suggestie voor presentatie: HTML ``input[type="checkbox"]``-element) * ``keuze_enkel``: Een keuze-veld waar één keuze aangevinkt mag worden (suggestie voor presentatie: HTML ``input[type="radio"]``-element) :json boolean verplicht: :json array|null mogelijke_keuzes: In het geval dat ``soort_invoer`` gelijk is aan 'keuze' of 'keuze_enkel', is dit een lijst van mogelijke keuzes. Als ``soort_invoer`` gelijk is aan 'contactpersoon.nieuwsbrieven', is dit een lijst met IDs van mogelijke nieuwsbrieven. Zie in dat geval de JSON-map ``newsletter_options`` voor de namen bij de corresponderende ``id``-nummers. :json sort_order: Suggestie van sorteervolgorde (sorteer oplopend voor overeenstemming met presentatie in Recras) :json boolean bijzonderheden_boeking: Indicatie of dit veld in 'bijzonderheden' van de aangemaakte boeking wordt opgenomen :json string extra_field_name: Als ``soort_invoer`` gelijk is aan 'contact.extra', is dit de naam van het extra veld. :json string field_identifier: **Belangrijk voor terugposten** Naam waarbij de invoer opgestuurd dient te worden. .. ContactformulierenSubmit_: Submit ------ .. http:post:: /api2/contactformulieren/(int:id)/opslaan Een ingevuld contactformulier in Recras opslaan. Bij een contactformulier kunnen *alleen* de velden worden opgeslagen die in de bijbehorende velden-lijst opgesomd worden. Dit endpoint is publiek toegankelijk. Wanneer een geldig contactformulier door een personeelslid met het recht ``viewContact`` of ``editContact`` wordt opgeslagen, bevat de response een JSON-object met een integer ``klant_id`` en eventueel een integer ``boeking_id`` zodat een verwijzing naar de klant- of boekingsinformatie gemaakt kan worden. **Voorbeeld request**: .. sourcecode:: http POST /api2/contactformulieren/1/opslaan HTTP/1.1 Host: demo.recras.nl { "contact.naam": "Lipsum BV", "contact.afdeling": null, "contactpersoon.voornaam": "Lorem", "contactpersoon.achternaam": "Ipsum", "contactpersoon.geslacht": "onbekend", "contactpersoon.adres": "Dolor Sit Ametstraat 42", "contactpersoon.postcode": "1337 VB", "contactpersoon.plaats": "Teststad", "contactpersoon.telefoon1": "0123456789", "contactpersoon.email1": "info@recras.nl", "boeking.datum": "2017-01-13", "boeking.starttijd": "09:00", "boeking.groepsgrootte": 120, "boeking.arrangement": 2, "veel_tekst_0": "Het betreft een personeelsfeest,\\nde heer Laoreet is dan 40 jaar in dienst.", "keuze_0": "bedrijfsuitje", "contact.extra[Taart]": "Monchoutaart" } :json field_identifier: De ingevulde contactinformatie. Velden met het kenmerk ``verplicht`` moeten aanwezig zijn, overige velden kunnen worden leeggelaten door de waarde ``null`` in te vullen of het veld niet in het object op te nemen. **Voorbeeld response**: .. sourcecode:: http HTTP/1.1 200 OK :statuscode 200: Contactformulier geaccepteerd :statuscode 201: Contactformulier geaccepteerd :statuscode 406: Fout in de invoer **Voorbeeld response (door ingelogd personeelslid)**: .. sourcecode:: http HTTP/1.1 200 OK Content-Type: application/json { "klant_id": 42, "boeking_id": 130 } :json integer klant_id: Het ``id``-nummer waarmee de klant is opgeslagen. Dit nummer hoeft niet nieuw te zijn; Recras probeert identieke inzendingen aan elkaar te koppelen. :json integer boeking_id: Het ``id``-nummer van de aangemaakte boeking