EenvoudigFactureren API

U kunt uw klant- en factuurgegevens op EenvoudigFactureren ook uitwisselen met externe applicaties. Dit maakt het mogelijk om bijvoorbeeld vanuit uw online webshop een nieuwe factuur op EenvoudigFactureren aan te maken zonder dat u zich op de website hoeft te begeven.

Hiertoe werd een API opgezet die u kunt bereiken op https://eenvoudigfactureren.be/api . Langs deze API kunnen andere applicaties communiceren met de website, hiervoor moeten deze externe applicaties dan wel specifiek aangepast worden. Om dit te kunnen uitvoeren hebt u specifieke technische kennis nodig.

Op deze pagina krijgt u een overzicht van alle technische details van de API.

Toegang

De API maakt gebruikt van REST met basic authentication. U dient dus steeds uw e-mailadres en wachtwoord op EenvoudigFactureren in te geven om toegang tot de API te hebben.

U kunt zowel gegevens ophalen, toevoegen, bijwerken als verwijderen. U kunt ook per email de factuur naar de klant versturen met behulp van de API.

Het is aan te raden om een afzonderlijke gebruiker aan uw account toe te voegen die enkel bij API-toegang wordt gebruikt. Zo heeft u geen nood aan de credentials van de normale gebruikers.

Indien een gebruiker toegang heeft tot verschillende accounts kunt u de gewenste account doorgeven in de header via “X-AccountId”. Het account-nummer (AccountId) van een account kunt u opvragen langs “Account” (menu rechtsboven). Wordt er geen account-nummer opgegeven dan wordt de standaard account van de gebruiker gebruikt (in te stellen langs “Gebruiker” (menu rechtsboven).

Het formaat

Het formaat van de communicatie gebeurt standaard langs XML maar ook JSON wordt ondersteund. Daarnaast kunt u ook de standaard form-encoding gebruiken bij het wijzigen van gegevens. Stuurt u bijvoorbeeld gegevens op langs JSON dan kunt u ook een antwoord in JSON terug verwachten. Stuurt u uw gegevens door in XML of form-encoding dan wordt er een antwoord in XML teruggestuurd. Wenst u hiervan afwijken en zelf te bepalen wat het teruggestuurde antwoord wordt kunt u dit meegeven als argument in de doorgegeven URL.

  • ?format=xml: XML-formaat (standaard)
  • ?format=json: JSON-formaat
  • ?format=csv: CSV-formaat, kan worden geopend in Excel
  • ?format=html: een HTML-tabel
  • ?format=pdf: als PDF (enkel voor domeinen invoices, receipts en quotes)
  • ?format=ubl: UBL/E-fff formaat – elektronische factuur (enkel voor domein invoices)

De 4 methodes

De 4 standaard form-methodes worden ondersteund: GET, POST, PUT en DELETE:

  • GET: Ophalen van gegevens
  • POST: Creëren of bijwerken van gegevens waarbij niet vermelde gegevens ongewijzigd blijven
  • PUT: Bijwerken van gegevens waarbij de vermelde gegevens als enige nieuwe gegeven wordt beschouwd (bestaande niet vermelde gegevens worden verwijderd)
  • DELETE: Verwijderen van gegevens

Resultcodes

Bij aanvragen naar de API wordt er steeds een resultaat teruggegeven in het gevraagde formaat. Daarnaast wordt er telkens een resultcode teruggegeven die algemeen aanduid of een actie al dan niet geslaagd is.

De resultcodes die kunnen worden teruggegeven

  • 200: Actie geslaagd
  • 201: Gegeven aangemaakt
  • 400: Fout door foutieve gegevens
  • 401: Authenticatie gebruiker niet aanvaard
  • 403: Geen toegang
  • 404: Gevraagde gegeven niet gevonden
  • 500: Interne fout

Opbouw URL

De opbouw van de URL is steeds dezelfde en begint met ‘https://eenvoudigfactureren.be/api‘ gevolgd door het versienummer van de gegevens, momenteel ‘v1‘. Daarna komt het domein, bvb. ‘invoices‘, ‘clients‘ of ‘activities‘. Dit is reeds een volwaardige URL maar eventueel kunt u hierna de ID van het element doorgeven. Hierna kunt u terug optioneel een subdomein doorgegeven al dan niet gevolgd door een ID. Dit geeft dan bijvoorbeeld: https://eenvoudigfactureren.be/api/v1/clients/101/contacts/9283 (contactpersoon met ID 9283 van klant met ID 101).

Enkele voorbeelden:

  • https://eenvoudigfactureren.be/api/v1/clients: Klantgegevens
  • https://eenvoudigfactureren.be/api/v1/invoices/3003: Factuur met ID 3003
  • https://eenvoudigfactureren.be/api/v1/quotes/4004/items: Items van offerte met ID 4004
  • https://eenvoudigfactureren.be/api/v1/invoices/3003/items/4005: Item met ID 4005 van factuur met ID 3003
  • https://eenvoudigfactureren.be/api/v1/uploads: Bestand-uploads/Attachments

Beperken teruggegeven velden

Indien u een lijst met gegevens opvraagt kunt u zelf bepalen welke velden worden teruggegeven. Geeft u niets op dan worden alle velden teruggegeven.

Geef een lijst door met de gewenste velden met de parameter ?fields=. U kunt enkel velden van het hoogste niveau meegeven en dus niet van onderliggende niveau’s.

Bvb. ?fields=name,email_address

Filteren gegevens

Indien u een lijst met gegevens opvraagt kunt u deze lijst filteren door enkel items met specifieke gegevens op te nemen.

Geef een lijst door met de gewenste waarden langs de parameter ?filter=. U kunt enkel filteren op velden van het hoogste niveau (Dus niet van onderliggende niveau’s). Als eerste waarde geeft u de naam van het veld door met hierna een vergelijkingsteken en daarna de eigenlijke waarde. De mogelijke vergelijkingstekens zijn =, !=, <=, >=, <, >, =~ (=bevat de tekst). Alle waarden moeten URL-encoded worden doorgegeven. Meerdere filters plaats u met een komma-teken na elkaar.

Bvb. ?filter=city%3DBrussel,name%3D%7ERestaurant

URL-encoderingen:

  • Gelijk aan (=): %3D
  • Verschillend van (!=): %21%3D
  • Kleiner dan of gelijk (<=): %3C%3D
  • Groter dan of gelijk (>=): %3E%3D
  • Kleiner dan (<): %3C
  • Groter dan (>): %3E
  • bevat (=~): %3D%7E
  • spatie (‘ ‘): +

Zoeken

U kunt ook vrij zoeken indien u een lijst met gegevens opvraagt. U kunt slechts 1 zoekterm meegeven.

Geef de zoekterm op met de parameter ?search=. De zoekterm is niet hoofdlettergevoelig en moet u URL-encoded doorgeven (om een spatie op te geven kunt u ‘+’ gebruiken).

Bvb. ?search=Gent

Sorteren

Indien u een lijst met gegevens opvraagt kunt u deze lijst oplopend of aflopend sorteren op enkele velden.

Niet op alle velden kunt u sorteren. Indien u een veld opgeeft waarop niet gesorteerd kan worden wordt er een foutmelding gegeven. Voor het domein ‘activities’ is er geen sortering mogelijk.

Geef een lijst door met de gewenste velden langs de parameter ?sort=. Meerdere velden kunt u met een ‘+’ scheiden (URL-encoded = %2B). Om een veld aflopend te sorteren plaats u er een min-teken voor.

Bvb. ?sort=status%2B-date

Paginering

Indien u een lijst met gegevens opvraagt kunt u ook slechts een deel van deze lijst opvragen. Dit is handig om paginering mogelijk te maken. Voor het domain ‘stockitems’ is er geen paginering mogelijk.

Het is ten sterkste aan te raden om bij het ophalen van documenten (facturen, offertes, …) steeds maximaal 100 documenten per aanvraag op te halen.

Om gegevens over te slaan gebruikt u de parameter ?skip= en om het aantal gegevens te beperken gebruikt u parameter ?take=.

Bvb. ?skip=30&take=10

Formattering

Teksten kunnen worden opgegeven in het Markdown formaat waardoor formattering wordt toegevoegd. Zie ook Hoe tekst formatteren?. Teksten teruggegeven langs de API bevatten de opgegeven formatterings-codes in Markdown-formaat, het is echter ook mogelijk om deze om te zetten naar de gepaste formattering in HTML.

Om teksten om te zetten gebruikt u de parameter ?markup=markdown.

Gegevens ophalen (GET)

Gegevens kunt u ophalen langs de GET-methode. Dit is de techniek die u ook gebruikt wanneer u eenvoudigweg een URL doorgeeft in een webbrowser.

U kunt dus bijvoorbeeld https://eenvoudigfactureren.be/api/v1/clients opgeven in een webbrowser om een lijst in XML te krijgen van alle klanten. Een ander voorbeeld: https://eenvoudigfactureren.be/api/v1/invoices/1001/payments. Wat een lijst teruggeeft met alle betalingen van factuur met ID 1001.

Zoals eerder vermeld kunt u het formaat aanpassen waarin de verkregen gegevens worden teruggegeven. Voeg hiervoor de extensie bijvoorbeeld ‘?format/json’ toe aan de URL. De mogelijke formaten zijn xml, json, csv en html.

Een voorbeeld in PHP hoe u gegevens kunt ophalen:

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

$p = curl_init('https://eenvoudigfactureren.be/api/v1/clients');
curl_setopt($p, CURLOPT_USERPWD, $email . ':' . $password);
curl_setopt($p, CURLOPT_RETURNTRANSFER, TRUE);
$xml_string_all_clients = curl_exec($p); 

Indien u een verkeerde URL opgeeft omdat bijvoorbeeld de gevraagde klant niet bestaat dan krijgt u als response ook een XML (of het gevraagde formaat) terug met de reden van de fout.

Vraagt u bijvoorbeeld de gegevens aan voor de onbestaande klant met ID 1001 met URL https://eenvoudigfactureren.be/api/v1/clients/1001 dan krijgt u terug:

<data>
  <error>client_id unknown</error>
</data>

Gegevens creëren (POST)

Gegevens kunt u enkel aanmaken langs de POST-methode. Gebruik hiervoor het domein en eventueel subdomein van de gegevens die u wilt aanmaken.

Wilt u bvb een nieuwe factuur aanmaken gebruik dan als URL https://eenvoudigfactureren.be/api/v1/invoices of https://eenvoudigfactureren.be/api/v1/invoices/1001/payments om een nieuwe betaling voor factuur met ID 1001 aan te maken.

De gegevens die u doorgeeft kunnen zowel in XML, JSON als in form-encoding doorgegeven worden. Bij XML en JSON kunt u alle gegevens in 1x doorgeven (bvb een factuur met items), met form-encoding moet u elk blok afzonderlijk doorgeven (bvb eerst de factuur en daarna één voor één de items).

Als resultaat krijgt u een ‘error’ of ‘success’ terug. Als de gegevens correct werden aangemaakt krijgt u bovendien ook nog de nieuwe ID van het aangemaakte gegeven terug alsook de URI waarmee u het volledige gegeven kunt opvragen.

Voorbeeld bij fout:

<data>
  <error>description is required</error>
</data>

Voorbeeld bij succes:

<data>
  <success>invoice created</success>
  <invoice_id>1001</invoice_id>
  <uri>https://eenvoudigfactureren.be/api/v1/invoices/1001</uri>
</data>

Een voorbeeld in PHP hoe u een factuur kunt aanmaken:

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

$invoice = new stdClass();
$invoice->{'client_id'} = 101;
$invoice->{'number'} = "INV2012-001";
$invoice->{'days_due'} = 10;
$invoice->{'items'} = array();

$item = new stdClass();
$item->{'description'} = "jouw bestelling";
$item->{'amount'} = 20.5;
$item->{'tax_rate'} = 21;

$invoice->items[] = $item;

$item = new stdClass();
$item->{'description'} = "levering";
$item->{'amount'} = 4;
$item->{'tax_rate'} = 21;

$invoice->items[] = $item;

$p = curl_init('https://eenvoudigfactureren.be/api/v1/invoices');
curl_setopt($p, CURLOPT_HTTPHEADER, array('Content-Type: application/json', 
                                          'Accept: application/json'));
curl_setopt($p, CURLOPT_USERPWD, $email . ':' . $password);
curl_setopt($p, CURLOPT_POSTFIELDS, json_encode($invoice));
curl_setopt($p, CURLOPT_RETURNTRANSFER, TRUE);
$result = json_decode(curl_exec($p));

Gegevens wijzigen (POST & PUT)

Het wijzigen van gegevens gebeurt op min of meer dezelfde manier als het aanmaken van een gegeven.

Echter moet u bij wijzigingen steeds de volledige URI van het gegeven dat u wilt wijzigen meegeven (dus inclusief ID). Zo geeft u bijvoorbeeld https://eenvoudigfactureren.be/api/v1/invoices/1001 door om factuur met ID 1001 te wijzigen.

De gebruikte methode (POST of PUT) heeft een grote invloed op hoe de gegevens worden gewijzigd.

De methode POST gebruikt u om slechts een gedeelte van de bestaande gegevens te wijzigen. Zo kunt u bijvoorbeeld enkel de omschrijving van een factuur-item meegeven en zullen andere velden zoals het bedrag ongewijzigd blijven.

Bij gebruik van de methode PUT moet u steeds alle gegevens meegeven. Niet meegegeven gegevens zullen worden verwijderd.

Als u XML of JSON als formaat gebruikt is het belangrijk om de ID van onderliggende elementen mee te geven (zowel bij POST als bij PUT). Geeft u een onderliggend element mee zonder ID dan wordt veronderstelt dat u dit gegeven wilt aanmaken.

Gebruikt u de methode PUT en wenst u bijvoorbeeld enkele details van een factuur wijzigen maar daarnaast ook alle betalingen van de factuur te verwijderen dan moet u in de factuur een leeg blok (XML) of lege array (JSON) voor ‘payments’ meegeven. Geeft u geen ‘payments’-blok of array mee dan worden er ook geen ‘payments’ verwijderd. Dus bij het meegeven van een leeg blok of lege array worden de gegevens uit deze blok/array verwijderd. Anders worden ze ongemoeid gelaten.

Een voorbeeld in PHP hoe u een item van een factuur kunt wijzigen (methode PUT):

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

$item = "<item><description>bestelling van 1/4/2012</description>
		 <amount_with_tax>25</amount_with_tax><tax_rate>21</tax_rate></item>";

$p = curl_init('https://eenvoudigfactureren.be/api/v1/invoices/1001/items/2893');
curl_setopt($p, CURLOPT_HTTPHEADER, array('Content-Type: application/xml', 
                                          'Accept: application/xml'));
curl_setopt($p, CURLOPT_USERPWD, $email . ':' . $password);
curl_setopt($p, CURLOPT_POSTFIELDS, $item);
curl_setopt($p, CURLOPT_CUSTOMREQUEST, "PUT");
curl_setopt($p, CURLOPT_RETURNTRANSFER, TRUE);
$result_in_xml_string = curl_exec($p);

Gegevens verwijderen (DELETE)

Gegevens kunt u verwijderen met de methode DELETE. Hiervoor geeft u in de URL het domein en de ID mee.

Wenst u een onderliggend gegeven te verwijderen geef dan ook het subdomein mee met eventueel de ID (geeft u geen ID mee dan worden alle gegevens van het subdomein verwijderd).

Een voorbeeld in PHP hoe u alle factuur-items van een factuur kunt verwijderen:

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

$p = curl_init('https://eenvoudigfactureren.be/api/v1/invoices/1001/items?format=json');
curl_setopt($p, CURLOPT_USERPWD, $email . ':' . $password);
curl_setopt($p, CURLOPT_CUSTOMREQUEST, "DELETE");
curl_setopt($p, CURLOPT_RETURNTRANSFER, TRUE);
$result = json_decode(curl_exec($p));

Verstuur een factuur, offerte of ander document (POST)

U kunt, net zoals u dit op de website kunt, ook een factuur, offerte, kasticket, bestelbon of leveringsbon per e-mail versturen naar de klant langs de API.

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

U moet hierbij wel enkele bijkomende gegevens meegeven (in XML, JSON of form-encoding):

  • recipient (text): E-mailadres of contact_id van de klant waarnaartoe de e-mail wordt verzonden. Kan ook worden opgegeven: ‘myself’ (uzelf in kopie), ‘main_contact’ (algemeen adres van de klant), ‘first_contact’ (algemeen adres of een ander beschikbaar e-mail adres), ‘all_contacts’ (alle beschikbare e-mailadressen). Het is ook mogelijk om een space separated lijst van voorgaande waarden op te geven.
  • recipients (list): Lijst met recipient-waarden (zie voorgaande).
  • message (text): De tekst-inhoud van de email. Indien niet opgegeven wordt de standaard email-inhoud gebruikt (zie Instellingen van uw account).
  • attachments (list): Optioneel een lijst met attachments (zie verder).

U moet bij een aanvraag tenminste 1 ontvanger meegeven. Uzelf als ontvanger opgeven is reeds voldoende. Een combinatie van verschillende velden ontvangers is mogelijk.

Een voorbeeld in XML om uw gegevens door te geven:

<data>
  <recipients>
    <recipient>customer1@hisdomain.com</recipient>
    <recipient>123548</recipient>
    <recipient>myself</recipient>
  </recipients>
  <message>Beste,
In bijlage vindt u uw factuur terug.</message>
  <attachments>
	  <attachment>
		  <upload_id>a9c4c541-33fc-4c34-894b-fcd091d45fc9</upload_id>
		  <filename>Mijn Bijlage.docx</filename>
	  </attachment>
  </attachments>
</data>

of

<data>
  <recipient>customer1@hisdomain.com 123548 myself</recipient>
  <message>Beste,
In bijlage vindt u uw factuur terug.</message>
</data>

Een voorbeeld in PHP hoe u een factuur kunt versturen langs email:

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

$post = array();
$post['recipient'] = "customer@hisdomain.com myself";
$post['message'] = "Beste,\\nIn bijlage vindt u uw factuur terug.";

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

Attachments toevoegen tijdens versturen e-mail (POST)

Tijdens het versturen van een factuur of offerte per e-mail kunt u ook bijkomend attachments toevoegen.

Gebruik hiervoor de POST-methode met als URL https://eenvoudigfactureren.be/api/v1/uploads.

Verstuur het bestand als form-data met als key ‘file’. Het bestand mag niet groter zijn dan 5MB. U kunt meerdere bestanden in één keer toevoegen door ‘file[]’ te gebruiken. Optioneel kunt u ook een bestandsnaam meegeven langs key ‘filename’.

Als antwoord krijgt u een lijst terug met per opgeladen bestand:

  • upload_id: Deze gebruikt u bij het verzenden van de e-mail (argument attachments)
  • filename: Doorgegeven bestandsnaam (deze wordt echter niet bijgehouden en dient u opnieuw door te geven tijdens doorsturen van de attachment per e-mail).
  • available_until: Geldigheidsperiode waarin het bestand beschikbaar blijft (tot 1 uur na opladen van het bestand).

Versturen in bulk

Om DDOS aanvallen tegen te gaan is het niet toegestaan om te veel bewerkingen na elkaar uit te voeren. Indien te veel API-calls na elkaar worden uitgevoerd kunt u mogelijks tijdelijk worden geblokkeerd. Voor het importeren/bewerken van een groot aantal artikelen of klanten kunt u deze daarom beter in bulk doorsturen. Hierdoor kunt u de artikelen/klanten als lijst van max. 100 items doorgeven.

Om de gegevens in bulk door te geven gebruik je de optie ‘?bulk’ als POST-method. De lijst met items geeft u door langs respectievelijk “clients” of “stockitems”.

$data['clients'] = [
	(object)[
		"name" => "IT Services BVBA"
	],
	(object)[
	    "client_id" => 11111,
		"name" => "Demo Company"
	],
];

$p = curl_init('https://eenvoudigfactureren.be/api/v1/clients?bulk');
curl_setopt($p, CURLOPT_HTTPHEADER, array('Content-Type: application/json', 
                                          'Accept: application/json'));
curl_setopt($p, CURLOPT_USERPWD, $email . ':' . $password);
curl_setopt($p, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($p, CURLOPT_RETURNTRANSFER, TRUE);
$result = json_decode(curl_exec($p));
Of in XML:
<clients>
  <client>
	<name>IT Services BVBA</name>
	...
  </client>
  <client>
	<name>Demo Company</name>
	...
  </client>
</clients>

De gegevensstructuur

Er zijn veschillende types gegevens (domeinen) te benaderen langs de API. Deze domeinen hebben veelal elk een aantal subdomeinen.

Een overzicht van de verschillende domeinen: