Customers (Klanten)
===================

.. KlantenCreate_:

Create
------

.. http:post:: /api2/klanten

   Create a new contact of type ``klant`` (customer).

   **Example request**:

   .. sourcecode:: http

      POST /api2/klanten HTTP/1.1
      Host: demo.recras.nl
      Accept: application/json

      {
         "naam": "Voorbeeldgroep", // (name: "Example Group")
         "adres": "Teststraat 1", // (address: "Test Street 1")
         "postcode": "1337 XD", // (postal_code)
         "plaats": "Teststad", // (city: "Test City")
         "provinciecode": "NL-NH", // (province_code)
         "website": "http://www.example.com",
         "bedrijf_id": 1, // (company_id)
         "soort_klant": "Familie", // (customer_type: "Family")
         "afdeling": null, // (department)
         "factuur_adressering": null, // (invoice_addressing)
         "contactpersonen": [ // (contact_persons)
            {
               "id": 15,
               "hoofdcontact": false // (main_contact)
            },
            {
               "voornaam": "Test", // (first_name)
               "achternaam": "Contactpersoon", // (last_name: "Contact Person")
               "geslacht": "man", // (gender: "male")
               "aanhef": null, // (salutation)
               "adres": "Teststraat 1", // (address: "Test Street 1")
               "postcode": "1337 XD", // (postal_code)
               "plaats": "Teststad", // (city: "Test City")
               "telefoon1": "0123456789", // (phone1)
               "email1": "test@example.com",
               "hoofdcontact": true // (main_contact)
            }
         ],
         "extra_fields": [
            {
               "name": "Shoe size",
               "type": "number",
               "value": 42,
            }
         ]
      }

   :json string naam: The name of the customer (`naam` means name)
   :json string adres: The address of the customer (`adres` means address)
   :json string postcode: (`postcode` means postal_code)
   :json string plaats: (`plaats` means city)
   :json string provinciecode: The ISO 3166-2 province code, used for statistics (`provinciecode` means province_code)
   :json string website: The website of the customer
   :json int bedrijf_id: ``id`` number of a Company (`Bedrijf`) in Recras to which this Customer (`Klant`) belongs; the default company is entered if this field is left empty. (`bedrijf_id` means company_id)
   :json string soort_klant: A customer type (`soort_klant`) as specified for the Company (`Bedrijf`)
   :json string afdeling: (`afdeling` means department)
   :json string factuur_adressering: The address to be shown on the invoice, if different from the customer address. (`factuur_adressering` means invoice_addressing)
   :json array contactpersonen: **Required** A list of one or more contact persons (`contactpersonen`); these can already exist in Recras or be new entries.
   :json boolean contactpersonen.hoofdcontact: **Required** for each contact person (`contactpersoon`), it must be indicated whether this contact person is the main contact person (`hoofdcontactpersoon`) of this customer. There can only be 1 main contact person per customer.
   :json array extra_fields: Array of extra fields. ``type`` can be one of the following: ``text``, ``number``, ``date``, ``singlechoice``, ``multiplechoice``. When ``type`` is ``number``, ``value`` is of type ``integer``. When ``type`` is ``date``, ``value`` is an ISO 8601 formatted date. When ``type`` is ``multiplechoice``, ``value`` is an array of string values.

   If an existing contact person is linked:

   :json int contactpersonen.id: ``id`` number of the contact person (`contactpersoon`)

   If a new contact person is entered (see also ``/contactpersonen`` (contact_persons))

   :json string voornaam: First name (`voornaam`) of contact person
   :json string achternaam: (`achternaam` means last_name)
   :json string geslacht: Gender (`geslacht`) of contact person, possibilities are 'man' (male), 'vrouw' (female), 'onbekend' (unknown)
   :json string aanhef: Salutation (`aanhef`) to be used. If left empty, the default salutation is used.
   :json string adres: (`adres` means address)
   :json string postcode: (`postcode` means postal_code)
   :json string plaats: (`plaats` means city)
   :json string telefoon1: (`telefoon1` means phone1)
   :json string telefoon2: (`telefoon2` means phone2)
   :json string email1:
   :json string email2:

   **Example response**:

   .. sourcecode:: http

      HTTP/1.1 201 Created
      Content-Type: application/json

      {
         "id": 83,
         "type": "klant", // (customer)
         "displaynaam": "Voorbeeldgroep", // (display_name: "Example Group")
         "naam": "Voorbeeldgroep", // (name: "Example Group")
         "adres": "Teststraat 1", // (address: "Test Street 1")
         "postcode": "1337 XD", // (postal_code)
         "plaats": "Teststad", // (city: "Test City")
         "provinciecode": "NL-NH", // (province_code)
         "website": "http://www.example.com",
         "bedrijf_id": 1, // (company_id)
         "soort_klant": "Familie", // (customer_type: "Family")
         "afdeling": null, // (department)
         "factuur_adressering": null // (invoice_addressing)
      }

  :statuscode 201: Customer created (`Klant aangemaakt`)
  :statuscode 200: Entered data has been merged with an existing customer (`Ingevoerde gegevens zijn samengevoegd met een bestaande klant`)
  :statuscode 406: Error in the input (`Fout in de invoer`)
  :statuscode 403: User does not have the ``editContact`` permission (`Gebruiker heeft het recht editContact niet`)

Read
----
.. http:get:: /api2/klanten

   List of contacts of type 'klant' (customer) in Recras.

   **Example request**:

   .. sourcecode:: http

      GET /api2/klanten HTTP/1.1
      Host: demo.recras.nl
      Accept: application/json

   **Example response**:

   .. sourcecode:: http

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

      [
         {
            "id": 62,
            "type": "klant", // (customer)
            "displaynaam": "Pascal en Corry en kids", // (display_name: "Pascal and Corry and kids")
            "naam": "Pascal en Corry en kids", // (name: "Pascal and Corry and kids")
            "adres": null, // (address)
            "postcode": null, // (postal_code)
            "plaats": null, // (city)
            "provinciecode": null, // (province_code)
            "website": null,
            "bedrijf_id": 1, // (company_id)
            "soort_klant": null, // (customer_type)
            "afdeling": null, // (department)
            "factuur_adressering": null // (invoice_addressing)
         },
         {
            "id": 17,
            "type": "klant", // (customer)
            "displaynaam": "Gemeente Appingedam", // (display_name: "Municipality Appingedam")
            "naam": "Gemeente Appingedam", // (name: "Municipality Appingedam")
            "adres": "Testraat 23", // (address: "Test Street 23")
            "postcode": "8291KS", // (postal_code)
            "plaats": "Assen", // (city)
            "provinciecode": "NL-DR", // (province_code)
            "website": "",
            "bedrijf_id": 2, // (company_id)
            "soort_klant": "", // (customer_type)
            "afdeling": "", // (department)
            "factuur_adressering": "" // (invoice_addressing)
         }
      ]

   :statuscode 200: OK

   :query integer id>: The smallest ``id``-value to allow in the selection. New in ``v1.1.0``

.. http:get:: /api2/klanten/(int:id)

   A specific customer (`klant`).

   The returned object contains a field ``contactpersonen`` (contact_persons), which contains a list of contact person objects.
   The first of these contact persons is the main contact person (`hoofdcontactpersoon`) of this contact.

   **Example request**:

   .. sourcecode:: http

      GET /api2/contacten/17 HTTP/1.1
      Host: demo.recras.nl
      Accept: application/json

   **Example response**:

   .. sourcecode:: http

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

      {
         "id": 17,
         "type": "klant", // (customer)
         "displaynaam": "Gemeente Appingedam", // (display_name: "Municipality Appingedam")
         "naam": "Gemeente Appingedam", // (name: "Municipality Appingedam")
         "adres": "Testraat 23", // (address: "Test Street 23")
         "postcode": "8291KS", // (postal_code)
         "plaats": "Assen", // (city)
         "provinciecode": "NL-DR", // (province_code)
         "website": "",
         "bedrijf_id": 2, // (company_id)
         "soort_klant": "", // (customer_type)
         "afdeling": "", // (department)
         "factuur_adressering": "", // (invoice_addressing)
         "contactpersonen": [ // (contact_persons)
            {
               "id": 15,
               "voornaam": "Janny", // (first_name)
               "achternaam": "Jansen", // (last_name)
               "geslacht": "man", // (gender: "male")
               "aanhef": null, // (salutation)
               "adres": "Testraat 23", // (address: "Test Street 23")
               "postcode": "8291KS", // (postal_code)
               "plaats": "Assen", // (city)
               "telefoon1": null, // (phone1)
               "telefoon2": null, // (phone2)
               "email1": null,
               "email2": null,
               "hoofdcontact": true // (main_contact)
            }
         ]
      }

  :statuscode 200: OK
  :statuscode 404: No package (`arrangement`) with this ``id``

Update
------
.. http:put:: /api2/klanten/(int:id)

   Update an existing customer (`klant`).

   The usage of this endpoint is almost identical to `KlantenCreate_ <creating new customers>`.
   Note that if the field ``contactpersonen`` (contact_persons) is specified, the list of contact persons must be specified exactly as it should be in Recras.

Changelog
---------

1.1.0:
   Added the ``id>`` parameter to the customers list.

0.1.0:
   Old, basically unversioned API. The documentation may be outdated