Items uit het domein “clients” stellen een klant voor.
Opbouw URL’s:
https://eenvoudigfactureren.be/api/v1/clients: Klantgegevens
https://eenvoudigfactureren.be/api/v1/clients/1001: Klant met ID 1001
https://eenvoudigfactureren.be/api/v1/clients/1001/contacts: Contactgegevens van klant met ID 1001
https://eenvoudigfactureren.be/api/v1/clients/1001/details: Detailgegevens van klant met ID 1001
Domein: clients
| Veldnaam | Type | Omschrijving | Voorbeeld |
|---|---|---|---|
| client_id | int | Unieke ID van de klant. Gegenereerd door het systeem. Steeds verplicht op te geven in URL (behalve bij creatie). | 1001 |
| uri | text | URL naar klant. Gegenereerd door het systeem. Te gebruiken bij aanspreken klant langs de API. | – |
| external_client_id | text | (Unieke) ID van de klant dat kan worden ingesteld door een externe partij. Maximum 50 karakters lang. Uniekheid van de waarde wordt niet afgedwongen. | Client-98437 |
| name | text | Naam van de klant. Verplicht mee te geven bij creatie. Maximum 75 karakters lang. | IT Services BVBA |
| attention | text | T.a.v. (ten aanzien van) van de klant. Niet verplicht. Maximum 100 karakters lang. | dienst administratie |
| number | text | Klantennummer. Niet verplicht, maximum 55 karakters lang. Wordt automatisch gegenereerd indien niet opgegeven bij creatie en indien deze optie geactiveerd werd in de Instellingen. | B12548 |
| street | text | Straat + huisnummer van de klant. Niet verplicht, maximum 150 karakters lang. | Langestraat 189 |
| street2 | text | Tweede adreslijn van de klant. Niet verplicht, maximum 150 karakters lang. | |
| city | text | Stad van de klant. Niet verplicht, maximum 50 karakters lang. | Antwerpen |
| postal_code | text | De postcode van de stad van de klant. Niet verplicht, maximum 10 karakters lang. | 2000 |
| country | text | Land van de klant. Niet verplicht, maximum 25 karakters lang. Bij aanmaken/bewerken enkel te gebruiken indien country_code niet werd opgegeven. Bij opvragen wordt dit veld automatisch bepaald a.d.h.v. country_code. | België |
| country_code | text | Landcode van de klant. Niet verplicht, 2 karakters lang, in hoofdletters. | BE |
| delivery_address | Address | Verzendadres van de klant. Niet verplicht. | – |
| site_address | Address | Werfadres van de klant. Niet verplicht. | – |
| tax_code | text | BTW-nummer van de klant. Niet verplicht, maximum 75 karakters lang. | BE 0123.456.789 |
| tax_code_registration_pending | text | Aanduiding BTW-nummer van de klant is in aanvraag. Kan waarde ‘yes’ of ‘no’ hebben. Indien niet opgegeven of indien tax_code ingevuld is de standaard waarde ‘no’. | no |
| company_id | text | Ondernemingsnummer van de klant. Niet verplicht, maximum 75 karakters lang. | 0123.456.789 |
| email_address | text | Email adres van de klant. Niet verplicht, maximum 125 karakters lang. | [email protected] |
| phone_number | text | Telefoonnummer van de klant. Niet verplicht, maximum 20 karakters lang. | 098/90.20.00 |
| website | text | De URL van de website van de klant. Niet verplicht, maximum 150 karakters lang. | http://www.it-servicesbvba.be |
| state | text | De status van klant. Mogelijke waardes: ‘active’, ‘archived’. Staat standaard op ‘active’. | active |
| private_note | text | Veld met private opmerkingen over de klant. Kan vrij gebruikt worden. Niet verplicht. | Betaald steeds correct. |
| private_note_html | html | Veld met private opmerkingen over de klant in HTML formaat. Kan vrij gebruikt worden. Niet verplicht. | <p>Betaald steeds correct.</p> |
| last_activity | datetime | Tijdstip met de laatste activiteit van de klant. Kan niet worden opgegeven, wordt automatisch bepaald door het systeem. | 2018-05-03 11:33:45 |
| default_days_invoice_due | int | Standaard aantal dagen betalingstermijn nieuwe facturen. Niet verplicht. Indien niet opgegeven wordt de standaard gebruikt zoals ingesteld in de instellingen van de account. | 30 |
| default_days_quote_valid | int | Standaard aantal dagen geldigheidsperiode nieuwe offertes. Niet verplicht. Indien niet opgegeven wordt de standaard gebruikt zoals ingesteld in de instellingen van de account. | 30 |
| default_tax_category | int | Standaard BTW-tarief. Kan de waarde 0, 1, 2 of 3 bevatten waarbij 1 (BTW tarief 1) de standaard waarde is. Niet verplicht. | 0 |
| default_tax_category_special_status | text | De BTW-code bij BTW-vrijstelling. Kan enkel worden ingesteld in combinatie met default_tax_category 0. Maximaal 20 karakters lang. Niet verplicht. Een oplijsting met beschikbaar codes zoals gebruikt in de software kan worden opgehaald door het standaard BTW-tarief via de webinterface in te stellen. | MC |
| default_tax_country_code | text | ISO landcode van het OSS land (One Stop Shop) waar de BTW van toepassing is. Leeg bij gewone BTW berekening. | NL |
| default_discount_percentage | float | Standaard kortingspercentage voor nieuwe facturen van de klant. Bedrag moet tussen 0 en 100 liggen. Getallen tot 2 cijfers na de komma zijn toegestaan. Niet verplicht. Indien niet opgegeven wordt de standaard gebruikt zoals ingesteld in de instellingen van de account. | 5 |
| default_cash_discount_active | text | Aanduiding of financiële korting voor de klant standaard al dan niet geactiveerd is bij aanmaak van nieuwe facturen. Kan waarde ‘yes’ of ‘no’ hebben. Niet verplicht. Indien niet opgegeven wordt de standaard gebruikt zoals ingesteld in de instellingen van de account. | no |
| default_cash_discount_percentage | float | Standaard kortingspercentage financiële korting voor nieuwe facturen van de klant. Bedrag moet tussen 0 en 100 liggen. Getallen tot 2 cijfers na de komma zijn toegestaan. Niet verplicht. Indien niet opgegeven wordt de standaard gebruikt zoals ingesteld in de instellingen van de account. | 1.50 |
| default_cash_discount_days_valid | int | Standaard aantal dagen geldigheid financiële korting voor nieuwe facturen van de klant. Bedrag moet tussen 0 en 100 liggen. Enkel gehele getallen zijn toegestaan. Niet verplicht. Indien niet opgegeven wordt de standaard gebruikt zoals ingesteld in de instellingen van de account. | 8 |
| default_structured_message | text | Standaard gestructureerde mededeling voor nieuwe facturen van de klant. Niet verplicht. Moet een geldige gestructureerde mededeling zijn (12 cijfers met vormcontrole). | 342485986564 |
| default_automatic_reminders | text | Standaard automatische herinneringen uitsturen voor nieuwe facturen van deze klant. Kan de waarde ‘yes’ of ‘no’ hebben. Niet verplicht. Indien niet opgegeven wordt de standaard gebruikt zoals ingesteld in de instellingen van de account. | yes |
| default_language | text | Standaard taal nieuwe facturen. Mogelijke waarden: ‘dutch’, ‘french’, ‘english’, ‘german’. Niet verplicht. Indien niet opgegeven wordt de standaard taal ‘dutch’ gebruikt. | french |
| default_currency | text | Standaard munteenheid nieuwe facturen. Bevat de officiële code van de munteenheid (bvb. ‘EUR’, ‘USD’ of ‘GBP’). Indien niet opgegeven wordt de standaard munteenheid ‘EUR’ gebruikt. | USD |
| default_note | text | Notitie die wordt toegevoegd bij het aanmaken van een factuur, offerte of ander document. Te gebruiken in combinatie met default_note_position. | Klantomschrijving |
| default_note_html | html | Notitie die wordt toegevoegd bij het aanmaken van een factuur, offerte of ander document in HTML formaat. Te gebruiken in combinatie met default_note_position. | <p>Klantomschrijving</p> |
| default_note_position | text | De positie van de notitie ten opzichte van reeds bestaande standaard notitie. Kan de waarde ‘top’ (bovenaan toevoegen; standaard), ‘bottom’ (onderaand toevoegen) of ‘replace’ (vervangen) bevatten. Te gebruiken in combinatie met default_note. | replace |
| default_invoices_layout_id | int | Standaard layout voor nieuwe facturen. Standaard leeg. Indien leeg wordt de standaard layout voor facturen van de account gebruikt. | 8001 |
| default_receipts_layout_id | int | Standaard layout voor nieuwe kasticketten. Standaard leeg. Indien leeg wordt de standaard layout voor kasticketten van de account gebruikt. | 8001 |
| default_quotes_layout_id | int | Standaard layout voor nieuwe offertes. Standaard leeg. Indien leeg wordt de standaard layout voor offertes van de account gebruikt. | 8001 |
| default_orders_layout_id | int | Standaard layout voor nieuwe bestelbonnen. Standaard leeg. Indien leeg wordt de standaard layout voor bestelbonnen van de account gebruikt. | 8001 |
| default_paymentrequest_layout_id | int | Standaard layout voor nieuwe betaalverzoeken. Standaard leeg. Indien leeg wordt de standaard layout voor betaalverzoeken van de account gebruikt. | 8001 |
| default_deliveries_layout_id | int | Standaard layout voor nieuwe leveringsbonnen. Standaard leeg. Indien leeg wordt de standaard layout voor leveringsbonnen van de account gebruikt. | 8001 |
| default_customdocument_layout_id | int | Standaard layout voor nieuwe vrije documenten. Standaard leeg. Indien leeg wordt de standaard layout voor vrije documenten van de account gebruikt. | 8001 |
| sepa_collection | Sepa | Gegevens om SEPA-domiciliëring voor de klant te activeren. | – |
| invoice_count | int | Aantal facturen geregistreerd onder de klant. Wordt door systeem zelf bepaald. | 12 |
| receipt_count | int | Aantal kasticketten geregistreerd onder de klant. Wordt door systeem zelf bepaald. | 2 |
| quote_count | int | Aantal offertes geregistreerd onder de klant. Wordt door systeem zelf bepaald. | 0 |
| order_count | int | Aantal bestelbonnen geregistreerd onder de klant. Wordt door systeem zelf bepaald. | 0 |
| paymentrequest_count | int | Aantal betaalverzoeken geregistreerd onder de klant. Wordt door systeem zelf bepaald. | 3 |
| delivery_count | int | Aantal leveringsbonnen geregistreerd onder de klant. Wordt door systeem zelf bepaald. | 3 |
| customdocument_count | int | Aantal vrije documenten geregistreerd onder de klant. Wordt door systeem zelf bepaald. | 3 |
| subscription_count | int | Aantal abonnementen geregistreerd onder de klant. Wordt door systeem zelf bepaald. | 1 |
| contacts | list | Een lijst met contactpersonen binnen de firma/klant. | – |
| details | list | DEPRECATED. Een generieke lijst met gegevens binnen de firma/klant. Dit gegeven is niet langer beschikbaar bij nieuwe accounts. Alternatief kunt u “custom_values” gebruiken. | – |
| custom_values | list | Lijst met extra velden. De beschikbare velden worden toegevoegd via “Instellingen” > “Geavanceerd”. | – |
Subdomein: contacts ( < clients )
| Veldnaam | Type | Omschrijving | Voorbeeld |
|---|---|---|---|
| contact_id | int | Unieke ID van de contactpersoon. Gegenereerd door het systeem. Verplicht op te geven in URL (behalve bij creatie). | 2002 |
| client_id | int | Unieke ID van de klant. Gegenereerd door het systeem. Verplicht op te geven in URL. | 1001 |
| uri | text | URL naar contactpersoon. Gegenereerd door het systeem. Te gebruiken bij aanspreken contactpersoon langs de API. | – |
| contact_name | text | Naam of omschrijving van de contactpersoon. Verplicht mee te geven bij creatie. Maximum 254 karakters lang. | John Smith |
| email_address | text | Email adres van de contactpersoon. Niet verplicht indien phone_number meegegeven. Maximum 125 karakters lang. | [email protected] |
| phone_number | text | Telefoonnummer van de contactpersoon. Niet verplicht indien email_address meegegeven. Maximum 20 karakters lang. | 098/90.20.20 |
Subdomein : details ( < clients )
Deprecated! Dit gegeven is niet langer beschikbaar bij nieuwe accounts. Alternatief kunt u “custom_values” gebruiken.
| Veldnaam | Type | Omschrijving | Voorbeeld |
|---|---|---|---|
| detail_id | int | Unieke ID van het detailgegeven. Gegenereerd door het systeem. Verplicht op te geven in URL (behalve bij creatie). | 2012 |
| client_id | int | Unieke ID van de klant. Gegenereerd door het systeem. Verplicht op te geven in URL. | 1001 |
| uri | text | URL naar detailgegeven. Gegenereerd door het systeem. Te gebruiken bij aanspreken detailgegeven langs de API. | – |
| name | text | Naam of omschrijving van het detailgegeven. Verplicht mee te geven bij creatie. Maximum 75 karakters lang. | Bank |
| value | text | Waarde van het detailgegeven. Verplicht mee te geven bij creatie. Maximum 100 karakters lang. | 000-00000011-11 |
Subdomein : custom_values ( < clients )
| Veldnaam | Type | Omschrijving | Voorbeeld |
|---|---|---|---|
| name | text | Interne naam van het standaard veld. Wordt bepaald bij aanmaak van het standaard veld en kan worden gebruikt als unieke identificatie van het standaard veld. Verplicht op te geven bij toevoegen of wijzigen van de waarde van dit veld. | myreference |
| description | text | Naam of omschrijving van het standaard veld zoals het wordt weergegeven bij gebruik. Wordt enkel informatief teruggegeven en kan niet worden aangepast via de API. | Onze referentie |
| value | text | Waarde van het standaard veld. Maximum 75 karakters lang. | 123456 |
Type : Address
| Veldnaam | Type | Omschrijving | Voorbeeld |
|---|---|---|---|
| street | text | Straat + huisnummer van het adres. Niet verplicht, maximum 150 karakters lang. | Langestraat 189 |
| street2 | text | Tweede adreslijn van het adres. Niet verplicht, maximum 150 karakters lang. | |
| city | text | Stad van het adres. Niet verplicht, maximum 50 karakters lang. | Antwerpen |
| postal_code | text | De postcode van de stad van het adres. Niet verplicht, maximum 10 karakters lang. | 2000 |
| country | text | Land van de klant. Kan niet worden opgegeven. Wordt automatisch bepaald a.d.h.v. country_code. | België |
| country_code | text | Landcode van de klant. Verplicht, 2 karakters lang, in hoofdletters. | BE |
Type : Sepa
| Veldnaam | Type | Omschrijving | Voorbeeld |
|---|---|---|---|
| name | text | Klantnaam zoals gekend voor het rekeningnummer. Niet verplicht, maximum 100 karakters lang. | John Smith |
| iban | text | IBAN van het rekeningnummer van de klant. Niet verplicht, maximum 50 karakters lang. | BE938493849384349 |
| bic | text | BIC van het rekeningnummer van de klant. Niet verplicht, maximum 50 karakters lang. | BEXXXXXXXX |
| mandate_date | text | Datum ondertekening mandaat. Niet verplicht, formaat YYYY-MM-DD. | 2021-01-01 |
| mandate_reference | text | Referte van het mandaat. Niet verplicht, maximum 100 karakters lang. | SEPA-REF-1 |
Voorbeeld in XML van een klant:
<client>
<client_id>1001</client_id>
<uri>https://eenvoudigfactureren.be/api/v1/clients/1001</uri>
<external_client_id>Client-98437</external_client_id>
<number>B12548</number>
<name>IT Services BVBA</name>
<attention>dienst administratie</attention>
<street>Langestraat 189</street>
<street2></street2>
<city>Antwerpen</city>
<postal_code>2000</postal_code>
<country>België</country>
<country_code>BE</country_code>
<delivery_address>
<street>Gebouw X</street>
<street2>Kortestraat 3</street2>
<postal_code>2000</postal_code>
<city>Antwerpen</city>
<country>België</country>
<country_code>BE</country_code>
</delivery_address>
<site_address>
<street>Olifantstraat 200</street>
<street2></street2>
<postal_code>9000</postal_code>
<city>Gent</city>
<country>België</country>
<country_code>BE</country_code>
</site_address>
<tax_code>BE 0123.456.789</tax_code>
<company_id></company_id>
<email_address>[email protected]</email_address>
<phone_number>098/90.20.00</phone_number>
<website>http://www.it-servicesbvba.be</website>
<state>active</state>
<private_note>Betaald steeds correct.</private_note>
<private_note_html><![CDATA[<p>Betaald steeds correct.</p>]]></private_note_html>
<last_activity>2018-05-03 11:33:45</last_activity>
<default_days_invoice_due>30</default_days_invoice_due>
<default_days_quote_valid>30</default_days_quote_valid>
<default_tax_category>0</default_tax_category>
<default_tax_category_special_status>MC</default_tax_category_special_status>
<default_tax_country_code>NL</default_tax_country_code>
<default_structured_message>342485986564</default_structured_message>
<default_automatic_reminders>yes</default_automatic_reminders>
<default_language>french</default_language>
<default_currency>USD</default_currency>
<default_note>Omschrijving klant</default_note>
<default_note_html><![CDATA[<p>Omschrijving klant</p>]]></default_note_html>
<default_note_position>replace</default_note_position>
<default_invoices_layout_id>8001</default_invoices_layout_id>
<default_receipts_layout_id>8001</default_receipts_layout_id>
<default_quotes_layout_id>8001</default_quotes_layout_id>
<default_orders_layout_id>8001</default_orders_layout_id>
<default_paymentrequests_layout_id>8001</default_paymentrequests_layout_id>
<default_deliveries_layout_id>8001</default_deliveries_layout_id>
<default_customdocuments_layout_id>8001</default_customdocuments_layout_id>
<sepa_collection>
<name>John Smith</name>
<iban>BE938493849384349</iban>
<bic>BEXXXXXXXX</bic>
<mandate_date>2021-01-01</mandate_date>
<mandate_reference>SEPA-REF-1</mandate_reference>
</sepa_collection>
<invoice_count>12</invoice_count>
<receipt_count>7</receipt_count>
<quote_count>7</quote_count>
<order_count>0</order_count>
<paymentrequest_count>0</paymentrequest_count>
<delivery_count>0</delivery_count>
<customdocument_count>0</customdocument_count>
<subscription_count>1</subscription_count>
<contacts>
<contact>
<contact_id>2002</contact_id>
<uri>https://eenvoudigfactureren.be/api/v1/clients/1001/contacts/2002</uri>
<contact_name>John Smith</contact_name>
<email_address>[email protected]</email_address>
<phone_number>098/90.20.20</phone_number>
</contact>
</contacts>
<details>
<detail>
<contact_id>2012</contact_id>
<uri>https://eenvoudigfactureren.be/api/v1/clients/1001/details/2012</uri>
<name>Bankrekeningnummer</name>
<value>000-00000011-11</value>
</detail>
</details>
<custom_values>
<custom_value>
<name>myreference</name>
<description>Onze referentie</description>
<value>123456</value>
</custom_value>
</custom_values>
</client> Meer info over de API? Lees onderstaande nuttige artikels