Items uit het domein “subscriptions” stellen een abonnement voor. Met een abonnement kunnen periodiek facturen worden aangemaakt.
Opbouw URL’s:
https://eenvoudigfactureren.be/api/v1/subscriptions: Abonnementsgegevens
https://eenvoudigfactureren.be/api/v1/subscriptions/3003: Abonnement met ID 3003
https://eenvoudigfactureren.be/api/v1/subscriptions/3003/items: Items van abonnement met ID 3003
https://eenvoudigfactureren.be/api/v1/subscriptions/3003/items/4005: Item met ID 4005 van abonnement met ID 3003
https://eenvoudigfactureren.be/api/v1/subscriptions/3003/remarks: Opmerkingen van abonnement met ID 3003
https://eenvoudigfactureren.be/api/v1/subscriptions/3003/remarks/5010: Opmerking met ID 5010 van abonnement met ID 3003
Domein : subscriptions
Veldnaam | Type | Omschrijving | Voorbeeld |
---|---|---|---|
subscription_id | int | Unieke ID van het abonnement. Gegenereerd door het systeem. Verplicht op te geven in URL (behalve bij creatie). | 3003 |
uri | text | URL naar abonnement. Gegenereerd door het systeem. Te gebruiken bij aanspreken abonnement langs de API. | – |
external_subscription_id | text | (Unieke) ID van het abonnement dat kan worden ingesteld door een externe partij. Maximum 50 karakters lang. Uniekheid van de waarde wordt niet afgedwongen. | Subscription-0983984 |
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. Bevat steeds de waarde ‘subscription’. Wordt bepaald door het systeem en kan niet zelf worden doorgegeven. | subscription |
number | text | Uniek nummer van het abonnement. Wordt gegenereerd indien niet meegegeven. Maximum 255 karakters lang. | SUB2018-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 de gegenereerde factuur. Niet verplicht. Maximum 250 karakters lang. | ID123456789 |
status | text | Status van het abonnement. Mogelijke waarden: ‘open’, ‘completed’, ‘disabled’. | open |
days_due | int | Betalingstermijn in aantal dagen van de gegenereerde factuur. Indien niet opgegeven worden de standaard volgens instellingen genomen. Maximumwaarde 999 dagen. Indien 0 is er geen betalingstermijn. Niet van toepassing voor creditnota. | 10 |
days_due_end_of_month | text | Betalingstermijn van de gegenereerde factuur steeds op het einde van de maand laten vallen. Kan waarde ‘yes’ of ‘no’ hebben. Indien niet opgegeven wordt de standaard volgens instellingen overgenomen. Niet van toepassing voor creditnota. | yes |
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 de gegenereerde factuur. Bedrag moet tussen 0 en 100 liggen. Getallen tot 2 cijfers na de komma zijn toegestaan. Indien niet opgegeven is deze waarde 0. | 5 |
cash_discount_percentage | float | Kortingspercentage financiële korting die geldt voor de gegenereerde factuur. Bedrag moet tussen 0 en 100 liggen. Getallen tot 2 cijfers na de komma zijn toegestaan. Indien niet opgegeven is deze waarde 0. Indien groter dan 0 is het veld ‘cash_discount_days_valid’ verplicht. | 2 |
cash_discount_days_valid | int | Aantal dagen dat de financiële korting geldig is. Bedrag moet tussen 0 en 100 liggen. Enkel gehele getallen zijn toegestaan. Indien niet opgegeven is deze waarde 0. Dit veld kan enkel worden opgegeven indien het veld ‘cash_discount_percentage’ ook werd opgegeven. | 8 |
currency | text | De munteenheid waarin de gegenereerde factuur 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 de gegenereerde factuur om te zetten naar EUR. | 1 |
show_tax_for_exchange_rate | text | Toon de BTW omgerekend naar EURO op de gegenereerde factuur 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 de gegenereerde factuur 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 de gegenereerde factuur. Mogelijke waardes: ‘total’, ‘item’. Standaard wordt ‘total’ gebruikt. Bij berekeningswijze ‘total’ wordt de BTW berekend op het totaalbedrag van de factuur, bij berekeningswijze ‘item’ wordt de BTW berekend per factuurlijn. 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 de gegenereerde factuur 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 factuur-items. | – |
discount_total_without_tax | float | Totaal bedrag van de toegekende korting op het factuurtotaal zonder rekening te houden met BTW. Wordt automatisch berekend en kan niet zelf worden opgegeven. | 10.00 |
total_refundable_deposit | float | Totaal bedrag van factuurlijnen 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 factuur-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 de factuur. 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 factuur-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 de factuur. 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 factuur-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 de factuur. 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 factuur-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 factuurtotaal. Wordt automatisch berekend en kan niet zelf worden opgegeven. | 1.20 |
discount_total_with_tax | float | Totaal bedrag van de toegekende korting op het factuurtotaal inclusief BTW. Wordt automatisch berekend en kan niet zelf worden opgegeven. | 12.10 |
total_with_tax | float | Totaal bedrag over alle factuur-items heen inclusief BTW. Wordt automatisch berekend en kan niet zelf worden opgegeven. | 242.00 |
generate_structured_message | text | Gestructureerde mededeling genereren bij aanmaak factuur. Kan waarde ‘yes’ of ‘no’ hebben. Indien niet opgegeven wordt de standaard volgens instellingen overgenomen. Niet van toepassing voor creditnota. | no |
structured_message | number | Gestructureerde mededeling volgens Belgisch bankformaat (zonder formatering) met een lengte van 12 cijfers en met controle op de checksum (laatste 2 cijfers). Optioneel mee te geven. Kan niet worden opgegeven indien ‘generate_structured_message’ actief is. Niet van toepassing voor creditnota. | 278781035591 |
note | text | Nota die onderaan de gegenereerde factuur wordt getoond. Optioneel mee te geven. Maximum 2000 karakters lang. | 25 € kosten bij laattijdige betalingen. |
note_html | html | Nota die onderaan de gegenereerde factuur wordt getoond in HTML formaat. Optioneel mee te geven. Maximum 2000 karakters lang. | <p>25 € kosten bij laattijdige betalingen.</p> |
next_date | date | Eerstvolgende datum waarop een factuur moet worden gegenereerd voor het abonnement. Formaat YYYY-MM-DD. Indien niet opgegeven wordt als datum morgen t.o.v. creatiedatum abonnement ingesteld. Datum wordt verhoogd telkens een factuur werd gegenereerd. | 2018-07-01 |
frequency | number | Frequentie die samen met ‘interval’ bepaald met welke frequentie een factuur wordt gegenereerd (bijvoorbeeld “elke 2 maanden”). Waarde moet tussen 1 en 999 liggen. Indien niet meegegeven wordt 1 ingesteld. | 2 |
interval | text | Interval die samen met ‘frequency’ bepaald met welke frequentie een factuur wordt gegenereerd (bijvoorbeeld “elke 2 maanden”). Toegelaten waarden: ‘day’, ‘week’, ‘month’, ‘year’. Verplicht op te geven. | month |
times | number | Aantal keren dat een factuur voor het abonnement nog moet worden gegenereerd. Optioneel mee te geven. Indien opgegeven wordt de waarde met 1 verminderd telkens een factuur wordt gegenereerd. Indien waarde 0 wordt de status van het abonnement automatisch op ‘completed’ geplaatst. | 10 |
expiration_date | date | Einddatum tot wanneer facturen voor het abonnement moeten worden gegenereerd. Optioneel mee te geven. Indien ‘next_date’ groter dan ‘expiration_date’ wordt wordt de status van het abonnement automatisch op ‘completed’ geplaatst. | 2030-12-31 |
direct_collection | text | Automatische betaling via domiciliëring indien beschikbaar (via Mollie). Kan waarde ‘yes’ of ‘no’ hebben. Standaard waarde is ‘no’ indien niet opgegeven. | no |
auto_send_invoice | text | Automatisch versturen per e-mail van de gegenereerde factuur. Kan waarde ‘yes’ of ‘no’ hebben. Standaard waarde is ‘no’ indien niet opgegeven. | yes |
email_recipients | text | Ontvangers van de automatisch per e-mail verstuurde factuur. Kan contact_id van de klant bevatten of één van volgende waarden: ‘main_contact’ (e-mailadres klant), ‘first_contact’ (e-mailadres klant of een ander beschikbaar e-mailadres van de klant), ‘all_contacts’ (alle e-mailadressen van de klant) of ‘myself’ (e-mailadres account-eigenaar in kopie). Het is ook mogelijk om een space separated lijst van voorgaande waarden op te geven of in JSON-formaat kunnen de gegevens als array worden doorgegeven. Verplicht op te geven indien ‘auto_send_invoice’ werd geactiveerd. | first_contact |
email_subject | text | Onderwerp van de verstuurde e-mail. Wordt overgenomen uit de instellingen indien niet opgegeven. | |
email_content | text | Inhoud (body) van de verstuurde e-mail. Wordt overgenomen uit de instellingen indien niet opgegeven. | |
email_filetype | text | Bestandsformaat van de factuur bij versturen per e-mail. Kan waarde ‘pdf’, ‘ubl’ of ‘both’ bevatten. Indien niet opgegeven wordt ‘pdf’ ingesteld. | |
last_activity | datetime | Tijdstip met de laatste activiteit van het abonnement. Kan niet worden opgegeven, wordt automatisch bepaald door het systeem. | 2018-05-03 11:33:45 |
custom_values | list | Lijst met extra velden die kunnen worden toegevoegd aan het abonnement. De beschikbare extra velden kunnen worden ingesteld via “Instellingen” > “Geavanceerd”. | – |
remarks | list | Lijst met persoonlijke opmerkingen op het abonnement | – |
Subdomein : items ( < subscriptions )
Veldnaam | Type | Omschrijving | Voorbeeld |
---|---|---|---|
item_id | int | Unieke ID van het factuur-item. Gegenereerd door het systeem. Verplicht op te geven in URL (behalve bij creatie). | 4004 |
invoice_id | int | Unieke ID van de factuur. Gegenereerd door het systeem. Verplicht op te geven in URL. | 3003 |
uri | text | URL naar factuur-item. Gegenereerd door het systeem. Te gebruiken bij aanspreken factuur-item langs de API. | – |
type | text | Type van het factuur-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 factuur-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 factuur-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 factuur-item. Kan tot op 2 decimalen nauwkeurig opgegeven worden. Indien niet opgegeven wordt standaard ‘1’ gebruikt. Het maximumbedrag is 99.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 factuur-item. Verplicht op te geven bij creatie (alternatief kan veld description_html worden gebruikt). | product omschrijving |
description_html | html | Omschrijving van het factuur-item in HTML formaat. Verplicht op te geven bij creatie (alternatief kan veld description worden gebruikt). | <p>product omschrijving</p> |
total_without_tax | float | Totaal bedrag van het factuur-item zonder BTW. Wordt berekend a.d.h.v. veld ‘amount’ en ‘quantity’. | 200.00 |
tax_rate | float | BTW-percentage van het factuur-item. Moet overeenkomen met één van de BTW-percentages van de factuur 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 factuur-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 factuur-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 factuur-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 ( < subscriptions + items < subscriptions )
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 : remarks ( < subscriptions )
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 |
invoice_id | int | Unieke ID van de factuur. 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 (alternatief kan veld description_html worden gebruikt). | Klant heeft goederen reeds ontvangen |
description_html | html | Omschrijving van de opmerking in HTML formaat. Verplicht op te geven bij creatie of wijziging (alternatief kan veld description worden gebruikt). | <p>Klant heeft goederen reeds ontvangen</p> |
Voorbeeld in XML van een abonnement:
<subscription> <subscription_id>3003</subscription_id> <uri>https://eenvoudigfactureren.be/api/v1/subscriptions/3003</uri> <external_subscription_id>Invoice-0983984</external_subscription_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>subscription</type> <number>SUB2018-001</number> <layout_id>8001</layout_id> <reference>ID123456789</reference> <status>open</status> <days_due>10</days_due> <days_due_end_of_month>yes</days_due_end_of_month> <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> <cash_discount_percentage>2</cash_discount_percentage> <cash_discount_days_valid>8</cash_discount_days_valid> <cash_discount_date_valid>2012-02-23</cash_discount_date_valid> <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/subscriptions/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_paid>25.0</total_paid> <generate_structured_message>no</generate_structured_message> <structured_message>278781035591</structured_message> <note>25 € kosten bij laattijdige betalingen.</note> <note_html><![CDATA[<p>25 € kosten bij laattijdige betalingen.</p>]]></note_html> <next_date>2018-07-01</next_date> <frequency>2</frequency> <interval>month</interval> <times>10</times> <expiration_date>2030-12-31</expiration_date> <direct_collection>no</direct_collection> <auto_send_invoice>yes</auto_send_invoice> <email_recipients>first_contact</email_recipients> <email_subject>Factuur %document-number%</email_subject> <email_content>In bijlage uw factuur</email_content> <email_filetype>pdf</email_filetype> <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> <remarks> <remark> <remark_id>5020</remark_id> <uri>https://eenvoudigfactureren.be/api/v1/subscriptions/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> </subscription>