Items uit het domein “customdocuments” stellen een vrij document voor.
Opbouw URL’s:
https://eenvoudigfactureren.be/api/v1/customdocuments: Vrije documentgegevens
https://eenvoudigfactureren.be/api/v1/customdocuments/3003: Vrije document met ID 3003
https://eenvoudigfactureren.be/api/v1/customdocuments/3003/items: Items van vrij document met ID 3003
https://eenvoudigfactureren.be/api/v1/customdocuments/3003/items/4005: Item met ID 4005 van vrij document met ID 3003
https://eenvoudigfactureren.be/api/v1/customdocuments/3003/remarks: Opmerkingen van vrij document met ID 3003
https://eenvoudigfactureren.be/api/v1/customdocuments/3003/remarks/5010: Opmerking met ID 5010 van vrij document met ID 3003
https://eenvoudigfactureren.be/api/v1/customdocuments/3003/events: Gebeurtenissen van vrij document met ID 3003
https://eenvoudigfactureren.be/api/v1/customdocuments/3003/events/5030: Gebeurtenis met ID 5030 van vrij document met ID 3003
https://eenvoudigfactureren.be/api/v1/uploads: Bestand-uploads/Attachments
Domein : customdocuments
Veldnaam | Type | Omschrijving | Voorbeeld |
---|---|---|---|
customdocument_id | int | Unieke ID van het vrij document. Gegenereerd door het systeem. Verplicht op te geven in URL (behalve bij creatie). | 3003 |
uri | text | URL naar vrij document. Gegenereerd door het systeem. Te gebruiken bij aanspreken vrij document langs de API. | – |
external_customdocument_id | text | (Unieke) ID van het vrij document dat kan worden ingesteld door een externe partij. Maximum 50 karakters lang. Uniekheid van de waarde wordt niet afgedwongen. | PR0983984 |
client_id | int | Unieke ID van de klant. Verplicht op te geven bij creatie. | 1001 |
client_uri | text | URL naar de klant. Gegenereerd door het systeem. Te gebruiken bij aanspreken klant langs de API. | – |
client_name | text | Naam van de klant. Wordt automatisch overgenomen uit de klantgegevens indien niet opgegeven. | IT Services BVBA |
client_attention | text | T.a.v. van de klant. Wordt automatisch overgenomen uit de klantgegevens indien niet opgegeven. | Dienst administratie |
type | text | Type van het document. Is steeds 'customdocument'. Wordt bepaald door het systeem en kan niet zelf worden doorgegeven. | customdocument |
number | text | Uniek nummer van het vrij document zoals getoond op het vrij document. Wordt gegenereerd indien niet meegegeven. Maximum 255 karakters lang. | 2012-001 |
layout_id | int | Unieke ID van de layout. Indien niet opgegeven wordt de standaard layout automatisch bepaald. Kan leeg zijn indien er geen layout voor de account werd ingesteld. | 8001 |
reference | text | Zelf opgegeven referentie van het vrij document. Niet verplicht. Maximum 250 karakters lang. | ID123456789 |
date | date | Datum creatie van het vrij document. Wordt gegenereerd indien niet meegegeven. Formaat YYYY-MM-DD. | 2012-02-15 |
status | text | Status van het vrij document. Mogelijke waarden: ‘open’, ´completed´. | open |
billing_address | Address | Facturatieadres van de klant. Wordt automatisch overgenomen uit de klantgegevens indien niet opgegeven. | – |
delivery_address | Address | Verzendadres van de klant. Wordt automatisch overgenomen uit de klantgegevens indien niet opgegeven. | – |
site_address | Address | Werfadres van de klant. Wordt automatisch overgenomen uit de klantgegevens indien niet opgegeven. | – |
discount_percentage | float | Kortingspercentage die geldt voor het hele vrij document. Bedrag moet tussen 0 en 100 liggen. Getallen tot 2 cijfers na de komma zijn toegestaan. Indien niet opgegeven is deze waarde 0. | 5 |
currency | text | De munteenheid waarin het vrij document wordt opgemaakt. Deze waarde moet deel uitmaken van een limitatieve lijst van de ondersteunde munteenheden. De waarde is 3 tekens lang en steeds in hoofdletters. Indien niet opgegeven wordt EUR gebruikt. | EUR |
exchange_rate | number | De omwisselingskoers om de bedragen op het vrij document om te zetten naar EUR. | 1 |
show_tax_for_exchange_rate | text | Toon de BTW omgerekend naar EURO op het vrij document indien er een andere munt wordt gebruikt (zoals wettelijk verplicht). Kan waarde ‘yes’ of ‘no’ hebben. Indien leeg is de standaard waarde ‘yes’. | yes |
language | text | De taal waarin het vrij document wordt opgemaakt. Deze waarde kan ‘dutch’, ‘french’, ‘english’ of ‘german’ bevatten maar kan ook leeg zijn. Indien leeg (= standaard waarde) wordt de standaard taal (dutch) gebruikt. | dutch |
tax_calculation | text | De berekeningswijze BTW van het vrij document. Mogelijke waardes: ‘total’, ‘item’. Standaard wordt ‘total’ gebruikt. Bij berekeningswijze ‘total’ wordt de BTW berekend op het totaalbedrag van het vrij document, bij berekeningswijze ‘item’ wordt de BTW berekend per lijn. Wisselen tussen de berekeningswijze kan afrondingsverschillen geven. Indien ‘tax_included’=’yes’ is enkel ‘item’ een geldige waarde. | total |
tax_included | text | Duidt aan of de bedragen van het vrij document al dan niet inclusief BTW werden opgegeven en dus inclusief BTW worden afgedrukt. Kan waarde ‘yes’ of ‘no’ hebben. Indien leeg wordt de standaard waarde bepaald zoals ingesteld voor de account (standaard ‘no’). | no |
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 |
items | list | Lijst met items. | – |
discount_total_without_tax | float | Totaal bedrag van de toegekende korting op het totaal zonder rekening te houden met BTW. Wordt automatisch berekend en kan niet zelf worden opgegeven. | 10.00 |
total_refundable_deposit | float | Totaal bedrag van lijnen met terugbetaalbare verpakking (tax_rate_special_status = DR). Wordt automatisch berekend en kan niet zelf worden opgegeven. | 5.00 |
total_without_tax | float | Totaal bedrag over alle items heen zonder rekening te houden met BTW. Eventuele kortingen (discount_total_without_tax) en terugbetaalbare verpakking (total_refundable_deposit) zijn reeds opgenomen in dit totaal. Wordt automatisch berekend en kan niet zelf worden opgegeven. | 200.00 |
tax_rate_1 | float | 1e BTW-percentage die kan gebruikt worden op het vrij document. Wordt tijdens creatie overgenomen uit de instellingen en kan niet zelf worden opgegeven. | 21 |
total_tax_1 | float | Totaal bedrag BTW volgens 1e BTW-percentage over alle items heen. Wordt automatisch berekend en kan niet zelf worden opgegeven. | 42.00 |
tax_rate_2 | float | 2e BTW-percentage die kan gebruikt worden op het vrij document. Wordt tijdens creatie overgenomen uit de instellingen en kan niet zelf worden opgegeven. | 12 |
total_tax_2 | float | Totaal bedrag BTW volgens 2e BTW-percentage over alle items heen. Wordt automatisch berekend en kan niet zelf worden opgegeven. | 0.00 |
tax_rate_3 | float | 3e BTW-percentage die kan gebruikt worden op het vrij document. Wordt tijdens creatie overgenomen uit de instellingen en kan niet zelf worden opgegeven. | 6 |
total_tax_3 | float | Totaal bedrag BTW volgens 3e BTW-percentage over alle items heen. Wordt automatisch berekend en kan niet zelf worden opgegeven. | 0.00 |
cash_discount_total | float | Totaal bedrag van de toegekende financiële korting op het totaal. Wordt automatisch berekend en kan niet zelf worden opgegeven. | 1.20 |
discount_total_with_tax | float | Totaal bedrag van de toegekende korting op het totaal inclusief BTW. Wordt automatisch berekend en kan niet zelf worden opgegeven. | 12.10 |
total_with_tax | float | Totaal bedrag over alle items heen inclusief BTW. Wordt automatisch berekend en kan niet zelf worden opgegeven. | 242.00 |
note | text | Nota die onderaan het vrij document wordt getoond. Optioneel mee te geven. Maximum 2000 karakters lang. | 25 € kosten bij laattijdige betalingen. |
note_html | html | Nota die onderaan het vrij document wordt getoond in HTML formaat. Optioneel mee te geven. Maximum 2000 karakters lang. | <p>25 € kosten bij laattijdige betalingen.</p> |
last_activity | datetime | Tijdstip met de laatste activiteit van het vrij document. Kan niet worden opgegeven, wordt automatisch bepaald door het systeem. | 2018-05-03 11:33:45 |
tags | list | Lijst met tags die aanduiden welke acties reeds werden uitgevoerd voor het vrij document. | – |
custom_values | list | Lijst met extra velden die kunnen worden toegevoegd aan het vrij document. De beschikbare extra velden kunnen worden ingesteld via “Instellingen” > “Geavanceerd”. | – |
remarks | list | Lijst met persoonlijke opmerkingen op het vrij document | – |
events | list | Lijst met gebeurtenissen van het vrij document. | – |
Subdomein : items ( < customdocuments )
Veldnaam | Type | Omschrijving | Voorbeeld |
---|---|---|---|
item_id | int | Unieke ID van het item. Gegenereerd door het systeem. Verplicht op te geven in URL (behalve bij creatie). | 4004 |
customdocument_id | int | Unieke ID van het vrij document. Gegenereerd door het systeem. Verplicht op te geven in URL. | 3003 |
uri | text | URL naar item. Gegenereerd door het systeem. Te gebruiken bij aanspreken item langs de API. | – |
type | text | Type van het item. Standaard is 'item'. Kan ook 'text' (=informatieve lijn), 'header' (subtotaal bovenaan) of 'footer' (subtotaal onderaan) bevatten. | item |
amount | float | Bedrag per eenheid (1 quantity) van het item exclusief BTW. Verplicht te gebruiken indien veld tax_included=’no’. Kan tot op 4 decimalen nauwkeurig opgegeven worden. Het maximumbedrag is 9.999.999,9999. Wordt automatisch berekend indien bedrag werd opgegeven via ‘amount_with_tax’. | 100.00 |
amount_with_tax | float | Bedrag per eenheid (1 quantity) van het item inclusief BTW. Verplicht te gebruiken indien veld tax_included=’yes’. Kan tot op 4 decimalen nauwkeurig opgegeven worden. Het maximumbedrag is 9.999.999,9999. Wordt automatisch berekend indien bedrag werd opgegeven via ‘amount’. | 121.00 |
quantity | float | Aantal eenheden van het item. Kan tot op 2 decimalen nauwkeurig opgegeven worden. Indien niet opgegeven wordt standaard ‘1’ gebruikt. Het maximumbedrag is 999.999,99. | 2 |
unit | text | Eenheid van het item. Niet verplicht. Maximum 10 karakters lang en moet beginnen met een letter. Mag geen spaties bevatten. | stuk |
stockitem_code | text | Artikelcode gekoppeld aan het item. Niet verplicht. Maximum 20 karakters lang. Toevoegen van een artikelcode heeft geen invloed op het aantal items in voorraad op de artikelenlijst. | A0000001 |
stockitem_id | int | Unieke ID van het artikel. Niet verplicht. Kan enkel gebruikt worden tijdens aanmaken of bewerken. Door deze ID door te geven worden niet opgegeven velden zoals “description”, “amount”, “stockitem_code”, “tax_rate”, “tax_rate_special_status” en “general_ledger_account” automatisch aangevuld. | 2002 |
quantity_with_unit | text | Aantal en eenheid van het item gescheiden door een spatie. Kan enkel gebruikt worden tijdens aanmaken of bewerken. Kan niet gebruikt worden in combinatie met veld ‘quantity’ of ‘unit’. Dezelfde beperkingen als velden ‘quantity’ en ‘unit’ zijn van toepassing. | 2 stuk |
description | text | Omschrijving van het item. Verplicht op te geven bij creatie. | product omschrijving |
description_html | html | Omschrijving van het item in HTML formaat. Verplicht op te geven bij creatie. | <p>product omschrijving</p> |
total_without_tax | float | Totaal bedrag van het item zonder BTW. Wordt berekend a.d.h.v. veld ‘amount’ en ‘quantity’. | 200.00 |
tax_rate | float | BTW-percentage van het item. Moet overeenkomen met één van de BTW-percentages van het vrij document of moet ‘0’ zijn. Indien niet opgegeven wordt ‘0’ verondersteld. | 21 |
tax_rate_special_status | text | Code afwijkend BTW-tarief van het gebruikte BTW-percentage (tax_rate) van het item. Kan enkel gebruikt worden indien het BTW-percentage 0 is. Het veld is optioneel en kan maximum 20 karakters lang zijn. | MC |
total_with_tax | float | Totaal bedrag van het item inclusief BTW. Wordt berekend a.d.h.v. veld ‘amount’, ‘quantity’ en ‘tax_rate’. | 242.00 |
general_ledger_account | text | Code van de grootboekrekening gekoppeld aan het item. Niet verplicht. Tussen 6 en 8 karakters lang, uitsluitend cijfers zijn toegelaten. | 700000 |
custom_values | list | Lijst met extra velden. De beschikbare velden worden toegevoegd via “Instellingen” > “Geavanceerd”. | – |
Subdomein : custom_values ( < customdocuments + items < customdocuments )
Veldnaam | Type | Omschrijving | Voorbeeld |
---|---|---|---|
name | text | Interne naam van het extra veld. Wordt bepaald bij aanmaak van het extra veld en kan worden gebruikt als unieke identificatie van het extra veld. Verplicht op te geven bij toevoegen of wijzigen van de waarde van dit veld. | myreference |
description | text | Naam of omschrijving van het extra 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 extra veld. Maximum 75 karakters lang. | 123456 |
Subdomein : tags ( < customdocuments )
Veldnaam | Type | Omschrijving | Voorbeeld |
---|---|---|---|
tag_id | number | Unieke ID van de tag | 3 |
name | text | Naam of code van de tag. Mogelijke waardes: ‘printed’ (tag_id=3), ‘sent’ (tag_id=6). | printed |
Opmerking: Het subdomein ‘tags’ is geen volwaardige subdomein en kan niet los van domein ‘customdocuments’ worden aangesproken. Het is niet mogelijk om waardes in tags aan te passen langs de API. Deze gegevens worden automatisch toegevoegd op basis van uitgevoerde acties.
Subdomein : remarks ( < customdocuments )
Veldnaam | Type | Omschrijving | Voorbeeld |
---|---|---|---|
remark_id | int | Unieke ID van de opmerking. Gegenereerd door het systeem. Verplicht op te geven in URL (behalve bij creatie). | 5020 |
customdocument_id | int | Unieke ID van het vrij document. Gegenereerd door het systeem. Verplicht op te geven in URL. | 3003 |
uri | text | URL naar opmerking. Gegenereerd door het systeem. Te gebruiken bij aanspreken opmerking langs de API. | – |
date | date | Datum waarop de opmerking werd toegevoegd. Indien niet opgegeven wordt de huidige datum gebruikt. Formaat is YYYY-MM-DD. | 2012-02-15 |
description | text | Omschrijving van de opmerking. Verplicht op te geven bij creatie of wijziging indien description_html niet opgegeven. | Klant heeft goederen reeds ontvangen |
description_html | html | Omschrijving van de opmerking in HTML formaat. Verplicht op te geven bij creatie of wijziging indien description niet opgegeven. | <p>Klant heeft goederen reeds ontvangen</p> |
Subdomein : events ( < customdocuments )
Veldnaam | Type | Omschrijving | Voorbeeld |
---|---|---|---|
event_id | int | Unieke ID van de gebeurtenis. Gegenereerd door het systeem. Verplicht op te geven in URL. | 5030 |
customdocument_id | int | Unieke ID van het vrij document. Gegenereerd door het systeem. Verplicht op te geven in URL. | 3003 |
uri | text | URL naar gebeurtenis. Gegenereerd door het systeem. Te gebruiken bij aanspreken gebeurtenis langs de API. | – |
date | date | Datum waarop de gebeurtenis heeft plaatsgevonden. Formaat YYYY-MM-DD. | 2012-02-15 |
type | text | Type van de gebeurtenis. Momenteel enkel ’email sent’ mogelijk. | email sent |
content | text | Inhoud of omschrijving van de gebeurtenis. Bij type ’email sent’ komt hierin de inhoud van de email terecht. | In bijlage uw vrij document |
recipients | list | Lijst met ontvangers van de gebeurtenis. | – |
Opmerking: Een element van het subdomein ‘events’ kan niet worden gewijzigd of zelf worden aangemaakt. Enkel het systeem kan een ‘event’ aanmaken.
Subdomein : recipients ( < events < customdocuments )
Veldnaam | Type | Omschrijving | Voorbeeld |
---|---|---|---|
name | text | Naam (voornaam + familienaam) van de ontvanger. | Bart Decouster |
email_address | text | Email adres van de ontvanger. | [email protected] |
external_event_recipient_id | text | Externe unieke referentie naar dit record. | 17ad5dfc-b03e-4fd3-b66b-05b264cfa0c6 |
status | text | Status die teruggeeft of de event reeds toegekomen is bij ontvanger. Mogelijke statussen zijn: sending, sent, open, failed. | sending |
information | text | Bijkomende informatie rond de status. Hier komt een foutmelding terecht indien status in ‘failed’ staat. | – |
Opmerking: Het subdomein ‘recipients’ is geen volwaardige subdomein en kan niet los van ‘events’ worden aangesproken.
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 |
Voorbeeld in XML van een vrij document:
<customdocument> <customdocument_id>3003</customdocument_id> <uri>https://eenvoudigfactureren.be/api/v1/customdocuments/3003</uri> <external_customdocument_id>Invoice-0983984</external_customdocument_id> <client_id>1001</client_id> <client_uri>https://eenvoudigfactureren/api/v1/clients/1001</client_uri> <client_name>IT Services BVBA</client_name> <client_attention>Dienst administratie</client_attention> <type>customdocument</type> <number>2012-001</number> <layout_id>8001</layout_id> <reference>ID123456789</reference> <date>2012-02-15</date> <status>open</status> <billing_address> <street>Olifantstraat 200</street> <street2></street2> <postal_code>9000</postal_code> <city>Gent</city> <country_code>BE</country_code> <country>België</country> </billing_address> <delivery_address> <street>Olifantstraat 200</street> <street2></street2> <postal_code>9000</postal_code> <city>Gent</city> <country_code>BE</country_code> <country>België</country> </delivery_address> <site_address> <street>Olifantstraat 200</street> <street2></street2> <postal_code>9000</postal_code> <city>Gent</city> <country_code>BE</country_code> <country>België</country> </site_address> <discount_percentage>5</discount_percentage> <currency>EUR</currency> <exchange_rate>1</exchange_rate> <language>dutch</language> <tax_calculation>total</tax_calculation> <tax_included>no</tax_included> <items> <item> <item_id>4004</item_id> <uri>https://eenvoudigfactureren.be/api/v1/customdocuments/3003/items/4004</uri> <type>item</type> <description>product omschrijving</description> <description_html><![CDATA[<p>product omschrijving</p>]]></description_html> <amount>100.00</amount> <amount_with_tax>121.00</amount_with_tax> <quantity>2</quantity> <unit>stuk</unit> <stockitem_code>A000001</stockitem_code> <total_without_tax>200.00</total_without_tax> <tax_rate>21</tax_rate> <total_with_tax>242.00</total_with_tax> <general_ledger_account>700000</general_ledger_account> <custom_values> <custom_value> <name>ean</name> <description>EAN</description> <value>100000000000001</value> </custom_value> </custom_values> </item> </items> <discount_total_without_tax>10.00</discount_total_without_tax> <total_refundable_discount>0.00</total_refundable_discount> <total_without_tax>190.00</total_without_tax> <tax_rate_1>21</tax_rate_1> <total_tax_1>42.00</total_tax_1> <tax_rate_2>12</tax_rate_2> <total_tax_2>0.00</total_tax_2> <tax_rate_3>6</tax_rate_3> <total_tax_3>0.00</total_tax_3> <discount_total_with_tax>12.10</discount_total_with_tax> <total_with_tax>229.90</total_with_tax> <total_costs>5.00</total_costs> <total_paid>25.0</total_paid> <note>25 € kosten bij laattijdige betalingen.</note> <note_html><![CDATA[<p>25 € kosten bij laattijdige betalingen.</p>]]></note_html> <last_activity>2018-05-03 11:33:45</last_activity> <custom_values> <custom_value> <name>myreference</name> <description>Onze referentie</description> <value>123456</value> </custom_value> </custom_values> <tags> <tag> <tag_id>3</tag_id> <name>printed</name> </tag> </tags> <remarks> <remark> <remark_id>5020</remark_id> <uri>https://eenvoudigfactureren.be/api/v1/customdocuments/3003/remarks/5020</uri> <date>2012-02-15</date> <description>Klant heeft goederen reeds ontvangen</description> <description_html><![CDATA[<p>Klant heeft goederen reeds ontvangen</p>]]></description_html> </remark> </remarks> <events> <event> <event_id>5030</event_id> <uri>https://eenvoudigfactureren.be/api/v1/customdocuments/3003/events/5030</uri> <date>2012-02-16</date> <type>email sent</type> <content>In bijlage uw vrij document</content> <recipients> <recipient> <name>Bart Decouster</name> <email_address>[email protected]</email_address> <external_event_recipient_id>17ad5dfc-b03e-4fd3-b66b-05b264cfa0c6</external_event_recipient_id> <status>sending</status> <information>-</information> </recipient> </recipients> </event> </events> </customdocument>