Facturen en creditnota’s

Items uit het domein “invoices” stellen een factuur of creditnota voor.
Bij een factuur is het totaalbedrag positief, bij een creditnota is het totaalbedrag negatief.

Opbouw URL’s:

  • https://eenvoudigfactureren.be/api/v1/invoices: Factuurgegevens
  • https://eenvoudigfactureren.be/api/v1/invoices/3003: Factuur met ID 3003
  • https://eenvoudigfactureren.be/api/v1/invoices/3003/items: Items van factuur met ID 3003
  • https://eenvoudigfactureren.be/api/v1/invoices/3003/items/4005: Item met ID 4005 van factuur met ID 3003
  • https://eenvoudigfactureren.be/api/v1/invoices/3003/remarks: Opmerkingen van factuur met ID 3003
  • https://eenvoudigfactureren.be/api/v1/invoices/3003/remarks/5010: Opmerking met ID 5010 van factuur met ID 3003
  • https://eenvoudigfactureren.be/api/v1/invoices/3003/payments: Betalingen van factuur met ID 3003
  • https://eenvoudigfactureren.be/api/v1/invoices/3003/payments/5020: Betaling met ID 5020 van factuur met ID 3003
  • https://eenvoudigfactureren.be/api/v1/invoices/3003/events: Gebeurtenissen van factuur met ID 3003
  • https://eenvoudigfactureren.be/api/v1/invoices/3003/events/5030: Gebeurtenis met ID 5030 van factuur met ID 3003
  • https://eenvoudigfactureren.be/api/v1/uploads: Bestand-uploads/Attachments

Domein : invoices

Veldnaam Type Omschrijving Voorbeeld
invoice_id int Unieke ID van de factuur. Gegenereerd door het systeem. Verplicht op te geven in URL (behalve bij creatie). 3003
uri text URL naar factuur. Gegenereerd door het systeem. Te gebruiken bij aanspreken factuur langs de API.
external_invoice_id text (Unieke) ID van de factuur dat kan worden ingesteld door een externe partij. Maximum 50 karakters lang. Uniekheid van de waarde wordt niet afgedwongen. Invoice-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.
type text Type van de factuur. Mogelijke waarden: ‘creditnote’ of ‘invoice’. Wordt bepaald door het systeem en kan niet zelf worden doorgegeven. invoice
number text Uniek nummer van de factuur zoals getoond op de factuur. Wordt gegenereerd indien niet meegegeven. Maximum 255 karakters lang. INV2012-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 factuur. Niet verplicht. Maximum 250 karakters lang. ID123456789
date date Datum creatie van de factuur. Wordt gegenereerd indien niet meegegeven. Formaat YYYY-MM-DD. 2012-02-15
date_delivery date Datum levering goederen/diensten op de factuur. Wordt gegenereerd indien niet meegegeven. Formaat YYYY-MM-DD. 2012-02-15
status text Status van de factuur. Mogelijke waarden: ‘open’, ‘overdue’, ‘closed’. Wordt bepaald door het systeem en kan niet zelf worden opgegeven. open
days_due int Betalingstermijn in aantal dagen van de factuur. Indien niet opgegeven worden de standaard volgens instellingen genomen. Maximumwaarde 999 dagen. Indien 0 is er geen betalingstermijn. Niet van toepassing voor creditnota (type = ‘creditnote’). 10
days_overdue int Aantal dagen dat betalingstermijn reeds werd overschreden t.o.v. de huidige datum. Wordt enkel getoond indien status ‘overdue’. Wordt gegenereerd door het systeem en kan niet zelf worden opgegeven. Niet van toepassing voor creditnota. 0
date_overdue date Datum waarop de betalingstermijn verstreken is. Wordt automatisch bepaald a.d.h.v. het veld ‘date’ en ‘days_due’. Niet van toepassing voor creditnota. 2012-02-25
discount_percentage float Kortingspercentage die geldt voor de hele 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 hele 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
cash_discount_date_valid date Datum tot wanneer de financiële korting geldig is. Kan niet worden opgegeven maar wordt automatisch berekend aan de hand van veld ‘cash_discount_days_valid’ en ‘date’. 2012-02-23
currency text De munteenheid waarin de 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 factuur om te zetten naar EUR. 1
show_tax_for_exchange_rate text Toon de BTW omgerekend naar EURO op de 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 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 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. total
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
total_paid float Totaal bedrag dat reeds werd betaald door klant. Is de sommatie van alle bedragen in payments. Wordt automatisch berekend en kan niet zelf worden opgegeven. 25.00
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. Niet van toepassing voor creditnota (type = ‘creditnote’). Wordt automatisch gegenereerd indien niet opgegeven en indien deze optie werd geactiveerd in de Instellingen. 278781035591
note text Nota die onderaan de factuur wordt getoond. Optioneel mee te geven. Maximum 2000 karakters lang. 25 € kosten bij laattijdige betalingen.
last_activity datetime Tijdstip met de laatste activiteit van de factuur. 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 de factuur.
payments list Lijst met ontvangen betalingen van de factuur.
remarks list Lijst met persoonlijke opmerkingen op de factuur
events list Lijst met gebeurtenissen van de factuur.

Subdomein : items ( < invoices )

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.
amount float Bedrag per eenheid (1 quantity) van het factuur-item zonder BTW. Verplicht op te geven bij creatie of als alternatief kan veld ‘amount_with_tax’ opgegeven worden. Kan tot op 6 decimalen nauwkeurig opgegeven worden, echter wordt het bedrag slechts tot op 2 decimalen nauwkeurig op de factuur getoond. Het maximumbedrag is 9.999.999,99. 100.00
amount_with_tax float Bedrag per eenheid (1 quantity) van het factuur-item inclusief BTW. Wordt automatisch berekend of kan opgegeven worden als alternatief voor het verplichte veld ‘amount’. Veld wordt enkel gebruikt bij opgave en wordt niet gebruikt bij weergave van het factuur-item. 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
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. product omschrijving
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

Subdomein : tags ( < invoices )

Veldnaam Type Omschrijving Voorbeeld
tag_id number Unieke ID van de tag 3
name text Naam of code van de tag. Mogelijke waardes: ‘@pdf’ (tag_id=3), ‘@email’ (tag_id=6), ‘@accountant’ (tag_id=9). @pdf

Opmerking: Het subdomein ‘tags’ is geen volwaardige subdomein en kan niet los van domein ‘invoices’ 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 : payments ( < invoices )

Veldnaam Type Omschrijving Voorbeeld
payment_id int Unieke ID van de betaling. Gegenereerd door het systeem. Verplicht op te geven in URL (behalve bij creatie). 5010
invoice_id int Unieke ID van de factuur. Gegenereerd door het systeem. Verplicht op te geven in URL. 3003
uri text URL naar betaling. Gegenereerd door het systeem. Te gebruiken bij aanspreken betaling langs de API.
date date Datum waarop de betaling werd geregistreerd. Heeft het formaat YYYY-MM-DD. Indien niet opgegeven bij creatie wordt huidige datum gebruikt. 2012-02-15
amount float Bedrag van de betaling. Verplicht mee te geven bij creatie als alternatief kan veld ‘remaining_amount’ opgegeven worden. 25.00
method text Betaalwijze van de betaling. Optioneel mee te geven. Geldige waarden: transfer, cash, debitcard, creditcard, directcollection, online, bancontact, ideal. cash
description text Omschrijving van de betaling. Optioneel mee te geven. Maximum 255 karakters lang. Voorschot
remaining_amount text Enkel van toepassing bij toevoegen van een betaling (POST/PUT). Deze aanduiding zorgt ervoor dat het veld ‘amount’ het volledige resterende nog niet betaalde bedrag van de factuur bevat. Niet verplicht veld, indien opgegeven heeft het steeds waarde ‘yes’. yes

Subdomein : remarks ( < invoices )

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. Klant heeft goederen reeds ontvangen

Subdomein : events ( < invoices )

Veldnaam Type Omschrijving Voorbeeld
event_id int Unieke ID van de gebeurtenis. Gegenereerd door het systeem. Verplicht op te geven in URL. 5030
invoice_id int Unieke ID van de factuur. 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 factuur
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 < invoices )

Veldnaam Type Omschrijving Voorbeeld
name text Naam (voornaam + familienaam) van de ontvanger. Bart Decouster
email_address text Email adres van de ontvanger. bart.decouster@hisdomain.com
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 subdomein ‘events’ worden aangesproken.

Voorbeeld in XML van een factuur:

<invoice>
  <invoice_id>3003</invoice_id>
  <uri>https://eenvoudigfactureren.be/api/v1/invoices/3003</uri>
  <external_invoice_id>Invoice-0983984</external_invoice_id>
  <client_id>1001</client_id>
  <client_uri>https://eenvoudigfactureren/api/v1/clients/1001</client_uri>
  <type>invoice</type>
  <number>INV2012-001</number>
  <layout_id>8001</layout_id>
  <reference>ID123456789</reference>
  <date>2012-02-15</date>
  <date_delivery>2012-02-15</date_delivery>
  <status>open</status>
  <days_due>10</days_due>
  <days_overdue>0</days_overdue>
  <date_overdue>2012-02-25</date_overdue>
  <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>
  <items>
    <item>
      <item_id>4004</item_id>
      <uri>https://eenvoudigfactureren.be/api/v1/invoices/3003/items/4004</uri>
      <description>product omschrijving</description>
      <amount>100.00</amount>
      <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>
    </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>
  <structured_message>278781035591</structured_message>
  <note>25 € kosten bij laattijdige betalingen.</note>
  <last_activity>2018-05-03 11:33:45</last_activity>
  <tags>
    <tag>
      <tag_id>3</tag_id>
      <name>@pdf</name>
    </tag>
  </tags>
  <payments>
    <payment>
      <payment_id>5010</payment_id>
      <uri>https://eenvoudigfactureren.be/api/v1/invoices/3003/payments/5010</uri>
      <date>2012-02-15</date>
      <amount>25.00</amount>
	  <method>cash</method>
      <description>Voorschot</description>
    </payment>
  </payments>
  <remarks>
  	<remark>
  		<remark_id>5020</remark_id>
  		<uri>https://eenvoudigfactureren.be/api/v1/invoices/3003/remarks/5020</uri>
  		<date>2012-02-15</date>
  		<description>Klant heeft goederen reeds ontvangen</description>
  	</remark>
  </remarks>
  <events>
    <event>
      <event_id>5030</event_id>
      <uri>https://eenvoudigfactureren.be/api/v1/invoices/3003/events/5030</uri>
      <date>2012-02-16</date>
      <type>email sent</type>
      <content>In bijlage uw factuur</content>
      <recipients>
        <recipient>
          <name>Bart Decouster</name>
          <email_address>bart.decouster@hisdomain.com</email_address>
          <external_event_recipient_id>17ad5dfc-b03e-4fd3-b66b-05b264cfa0c6</external_event_recipient_id>
          <status>sending</status>
          <information>-</information>
        </recipient>
      </recipients>
    </event>
  </events>
</invoice>

Verstuur factuur naar boekhouder (POST)

Een factuur kan rechtstreeks worden doorgestuurd naar het boekhoudpakket van uw boekhouder. Dit is enkel mogelijk indien een koppeling via CodaBox, ClearFacts of Yuki werd opgezet.

Een factuur kan slechts 1x worden doorgestuurd naar de boekhouder.

Gebruik hiervoor de POST-methode met als URL bijvoorbeeld https://eenvoudigfactureren.be/api/v1/invoices/1001?send_accountant.

Een voorbeeld in PHP hoe u een factuur kunt versturen naar uw boekhouder:

$email = 'luc@mymail.com';
$password = '123456';

$p = curl_init('https://eenvoudigfactureren.be/api/v1/invoices/1001?send_accountant');
curl_setopt($p, CURLOPT_USERPWD, $email . ':' . $password);
curl_setopt($p, CURLOPT_POST, 1);
curl_setopt($p, CURLOPT_RETURNTRANSFER, TRUE);
		
$result_in_xml_string = curl_exec($p);

Betaling via domiciliëring aanvragen (POST)

Door een domiciliëring kan een factuur rechtstreeks worden betaald zonder tussenkomst van de klant. Dit is enkel mogelijk indien een koppeling via Mollie werd opgezet.

Om een betaling via domiciliëring aan te vragen gebruikt u de POST-methode met als URL bijvoorbeeld https://eenvoudigfactureren.be/api/v1/invoices/1001?make_direct_collection.

Een voorbeeld in PHP hoe een betaling via domiciliëring kan worden aangevraagd:

$email = 'luc@mymail.com';
$password = '123456';

$p = curl_init('https://eenvoudigfactureren.be/api/v1/invoices/1001?make_direct_collection');
curl_setopt($p, CURLOPT_USERPWD, $email . ':' . $password);
curl_setopt($p, CURLOPT_POST, 1);
curl_setopt($p, CURLOPT_RETURNTRANSFER, TRUE);
		
$result_in_xml_string = curl_exec($p);