EenvoudigFactureren.be API
U kunt uw klant- en factuurgegevens op http://eenvoudigfactureren.be ook uitwisselen met externe applicaties. Dit maakt het mogelijk om bijvoorbeeld vanuit een andere applicatie een nieuwe klant op EenvoudigFactureren.be aan te maken zonder dat u zich op de website hoeft te begeven.
Hiertoe werd een API opgezet die u kunt bereiken op http://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.
Hebt u een website en maakt u hiervoor gebruik van OpenCart? Dan kunt u onze extension gebruiken om langs de API te communiceren met deze website. Voor meer info kunt u terecht op de help-pagina voor de OpenCart extension.
De API maakt gebruikt van REST met basic authentication. U dient dus steeds uw e-mailadres en wachtwoord op eenvoudigfactureren.be 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 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 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
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 vermeldde gegevens ongewijzigd blijven
- PUT: Bijwerken van gegevens waarbij de vermeldde gegevens als enige nieuwe gegeven wordt beschouwd (bestaande niet vermeldde 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
- 404: Gevraagde gegeven niet gevonden
Opbouw URL
De opbouw van de URL is steeds dezelfde en begint met 'http://eenvoudigfactureren.be/api' gevolgd door het versienummer van de gegevens, momenteel 'v1'. Daarna komt het domein, nl. 'invoices' of 'clients'. 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: http://eenvoudigfactureren.be/api/v1/clients/101/contacts/9283 (contactpersoon met ID 9283 van klant met ID 101).
Een overzicht:
- http://eenvoudigfactureren.be/api/v1/clients: Klantgegevens
- http://eenvoudigfactureren.be/api/v1/clients/1001: Klant met ID 1001
- http://eenvoudigfactureren.be/api/v1/clients/1001/contacts: Contactgegevens van klant met ID 1001
- http://eenvoudigfactureren.be/api/v1/invoices: Factuurgegevens
- http://eenvoudigfactureren.be/api/v1/invoices/3003: Factuur met ID 3003
- http://eenvoudigfactureren.be/api/v1/invoices/3003/items: Items van factuur met ID 3003
- http://eenvoudigfactureren.be/api/v1/invoices/3003/items/4004: Item met ID 4004 van factuur met ID 3003
- http://eenvoudigfactureren.be/api/v1/invoices/3003/remarks: Opmerkingen van factuur met ID 3003
- http://eenvoudigfactureren.be/api/v1/invoices/3003/remarks/5010: Opmerking met ID 5010 van factuur met ID 3003
- http://eenvoudigfactureren.be/api/v1/invoices/3003/payments: Betalingen van factuur met ID 3003
- http://eenvoudigfactureren.be/api/v1/invoices/3003/payments/5020: Betaling met ID 5020 van factuur met ID 3003
- http://eenvoudigfactureren.be/api/v1/invoices/3003/events: Gebeurtenissen van factuur met ID 3003
- http://eenvoudigfactureren.be/api/v1/invoices/3003/events/5030: Gebeurtenis met ID 5030 van factuur met ID 3003
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 http://eenvoudigfactureren.be/api/v1/clients opgeven in een webbrowser om een lijst in XML te krijgen van alle klanten. Een ander voorbeeld: http://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@hotmail.com';
2
$password = '123456';
3
4
$p = curl_init('http://eenvoudigfactureren.be/api/v1/clients');
5
curl_setopt($p, CURLOPT_USERPWD, $email . ':' . $password);
6
curl_setopt($p, CURLOPT_RETURNTRANSFER, TRUE);
7
$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 http://eenvoudigfactureren.be/api/v1/clients/1001 dan krijgt u terug:
1 <data>
2 <error>client_id unknown</error>
3 </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 http://eenvoudigfactureren.be/api/v1/invoices of http://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:
1 <data>
2 <error>description is required</error>
3 </data>
Voorbeeld bij succes:
1 <data>
2 <success>invoice created</success>
3 <invoice_id>1001</invoice_id>
4 <uri>http://eenvoudigfactureren.be/api/v1/invoices/1001</uri>
5 </data>
Een voorbeeld in PHP hoe u een factuur kunt aanmaken:
$email = 'luc@hotmail.com';
2
$password = '123456';
3
4
$invoice = new stdClass();
5
$invoice->{'client_id'} = 101;
6
$invoice->{'number'} = "INV2012-001";
7
$invoice->{'days_due'} = 10;
8
$invoice->{'items'} = array();
9
10
$item = new stdClass();
11
$item->{'description'} = "jouw bestelling";
12
$item->{'amount'} = 20.5;
13
$item->{'tax_rate'} = 21;
14
15
$invoice->items[] = $item;
16
17
$item = new stdClass();
18
$item->{'description'} = "levering";
19
$item->{'amount'} = 4;
20
$item->{'tax_rate'} = 21;
21
22
$invoice->items[] = $item;
23
24
$p = curl_init('http://eenvoudigfactureren.be/api/v1/invoices');
25
curl_setopt($p, CURLOPT_HTTPHEADER, array('Content-Type: application/json',
26
'Accept: application/json'));
27
curl_setopt($p, CURLOPT_USERPWD, $email . ':' . $password);
28
curl_setopt($p, CURLOPT_POSTFIELDS, json_encode($invoice));
29
curl_setopt($p, CURLOPT_RETURNTRANSFER, TRUE);
30
$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 http://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 GET). 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@hotmail.com';
2
$password = '123456';
3
4
$item = "<item><description>bestelling van 1/4/2012</description>
5
<amount_with_tax>25</amount_with_tax><tax_rate>21</tax_rate></item>";
6
7
$p = curl_init('http://eenvoudigfactureren.be/api/v1/invoices/1001/items/2893');
8
curl_setopt($p, CURLOPT_HTTPHEADER, array('Content-Type: application/xml',
9
'Accept: application/xml'));
10
curl_setopt($p, CURLOPT_USERPWD, $email . ':' . $password);
11
curl_setopt($p, CURLOPT_POSTFIELDS, $item);
12
curl_setopt($p, CURLOPT_CUSTOMREQUEST, "PUT");
13
curl_setopt($p, CURLOPT_RETURNTRANSFER, TRUE);
14
$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 een alle factuur-items van een factuur kunt verwijderen:
$email = 'luc@hotmail.com';
2
$password = '123456';
3
4
$p = curl_init('http://eenvoudigfactureren.be/api/v1/invoices/1001/items/format/json');
5
curl_setopt($p, CURLOPT_USERPWD, $email . ':' . $password);
6
curl_setopt($p, CURLOPT_CUSTOMREQUEST, "DELETE");
7
curl_setopt($p, CURLOPT_RETURNTRANSFER, TRUE);
8
$result = json_decode(curl_exec($p));
Verstuur factuur (POST)
U kunt, net zoals u dit op de website kunt, ook een factuur per email versturen naar de klant langs de API.
Gebruik hiervoor de POST-methode met als URL bijvoorbeeld http://eenvoudigfactureren.be/api/v1/invoices/1001/sendemail.
U moet hierbij wel enkele bijkomende gegevens meegeven (in XML, JSON of form-encoding):
- email_address: email adressen waarnaartoe de mail moet worden verzonden. Formaat: array (JSON), space separated list (JSON, XML, form-encoding), list (XML)
- to_myself: waarde '1' indien u de email ook naar uzelf, in kopie, wenst te sturen.
- contact_id: ID's contactpersonen waarnaartoe de mail moet worden verzonden. Formaat: array (JSON), space separated list (JSON, XML, form-encoding), list (XML)
- all_contacts: waarde '1' om email naar alle contactpersonen van de klant te verzenden.
- message: de inhoud van de email
U moet bij een aanvraag tenminste 1 ontvanger meegeven. Uzelf als ontvanger opgeven is reeds voldoende. Een combinatie van verschillende velden ontvangers is mogelijk. Het veld 'message' is optioneel; indien niet opgegeven wordt de standaard email-inhoud genomen (zie uw instellingen).
In de velden 'email_address' en 'contact_id' kunt u 1 waarde opgeven of een lijst van waarden. Een lijst kunt u in elk formaat (XML, JSON en form-encoding) doorgeven.
Indien u een lijst met meerdere waarden wenst door te geven is de eenvoudigste manier (en de enige manier die toe te passen is in elk van de 3 formaten) om de lijst met waarden op te bouwen als 1 string met tussen elke waarde een spatie.
$post['email_address'] = 'customer1@hisdomain.com customer2@hisdomain.com';
Maakt u gebruik van JSON om uw gegevens door te geven kunt u de gegevens ook gewoon als array doorgeven.
$object->email_address = array('cust1@hisdomain.com','cust2@hisdomain.com');
2
//Alsook: $object->email_address = 'cust1@hisdomain.com cust2@hisdomain.com';
Maakt u gebruik van XML om uw gegevens door te geven dan kunt u de gegevens ook als een blok doorgeven. (Merk op dat de tag van het blok een bijkomende 's' heeft!)
1 <data>
2 <email_addresss>
3 <email_address>customer1@hisdomain.com</email_address>
4 <email_address>customer2@hisdomain.com</email_address>
5 </email_addresss>
6 </data>
Een voorbeeld in PHP hoe u een factuur kunt versturen langs email:
$email = 'luc@hotmail.com';
2
$password = '123456';
3
4
$post = array();
5
$post['email_address'] = "customer1@hisdomain.com customer2@hisdomain.com";
6
$post['to_myself'] = 1;
7
$post['message'] = "Beste,\nIn bijlage vindt u uw factuur terug.";
8
9
$p = curl_init('http://eenvoudigfactureren.be/api/v1/invoices/1001/sendemail');
10
curl_setopt($p, CURLOPT_USERPWD, $email . ':' . $password);
11
curl_setopt($p, CURLOPT_POSTFIELDS, $post);
12
curl_setopt($p, CURLOPT_RETURNTRANSFER, TRUE);
13
$result_in_xml_string = curl_exec($p);
De gegevensstructuur
Er zijn 3 types gegevens (domeinen) te benaderen langs de API nl. clients, invoices en activities. De domeinen clients en invoices hebben elk een aantal subdomeinen.
Een overzicht van de gegevens met hun velden:
| 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 |
| street | text | Straat + huisnummer van de klant. Niet verplicht, maximum 150 karakters lang. | Langestraat 189 |
| city | text | Stad van de klant. Niet verplicht, maximum 50 karakters lang. | Antwerpen |
| country | text | Land van de klant. Niet verplicht, maximum 25 karakters lang. | België |
| postal_code | text | De postcode van de stad van de klant. Niet verplicht, maximum 10 karakters lang. | 2000 |
| website | text | De URL van de website van de klant. Niet verplicht, maximum 150 karakters lang. | http://www.it-servicesbvba.be |
| tax_code | text | BTW-nummer van de klant. Niet verplicht, maximum 75 karakters lang. | BE 123.456.789 |
| private_note | text | Veld met private opmerkingen over de klant. Kan vrij gebruikt worden. Niet verplicht. | Betaald steeds correct. |
| invoice_count | int | Aantal facturen geregistreerd onder de klant. Wordt door systeem zelf bepaald. | 12 |
| contacts | list | Een lijst met contactpersonen binnen de firma/klant. | - |
| 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. | - |
| first_name | text | Voornaam van de contactpersoon. Verplicht mee te geven bij creatie. Maximum 25 karakters lang. | John |
| last_name | text | Familienaam van de contactpersoon. Verplicht mee te geven bij creatie. Maximum 25 karakters lang. | Smith |
| email_address | text | Email adres van de contactpersoon. Verplicht mee te geven bij creatie. Maximum 125 karakters lang. | john.smith@hisdomain.com |
| phone_number | text | Telefoonnummer van de contactpersoon. Niet verplicht, maximum 20 karakters lang. | 098/90.20.20 |
Voorbeeld in XML van een klant:
1 <client>
2 <client_id>1001</client_id>
3 <uri>http://eenvoudigfactureren.be/api/v1/clients/1001</uri>
4 <external_client_id>Client-98437</external_client_id>
5 <name>IT Services BVBA</name>
6 <street>Langestraat 189</street>
7 <city>Antwerpen</city>
8 <country>België</country>
9 <postal_code>2000</postal_code>
10 <website>http://www.it-servicesbvba.be</website>
11 <tax_code>BE 123.456.789</tax_code>
12 <private_note>Betaald steeds correct.</private_note>
13 <invoice_count>12</invoice_count>
14 <contacts>
15 <contact>
16 <contact_id>2002</contact_id>
17 <uri>http://eenvoudigfactureren.be/api/v1/clients/1001/contacts/2002</uri>
18 <first_name>John</first_name>
19 <last_name>Smith</last_name>
20 <email_address>john.smith@hisdomain.com</email_address>
21 <phone_number>098/90.20.20</phone_number>
22 </contact>
23 </contacts>
24 </client>
| 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. Gegenereerd door het systeem. Verplicht op te geven bij creatie. Kan ook in een blok 'client' worden gezet. | 1001 |
| 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 |
| date | date | Datum creatie van de factuur. Wordt gegenereerd indien niet meegegeven. Formaat YYYY-MM-DD. | 2012-02-15 |
| status | text | Betalingsstatus 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. | 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. | 0 |
| date_overdue | date | Datum waarop de betalingstermijn eindigt. Wordt automatisch bepaald a.d.h.v. het veld 'date' en 'days_due'. | 2012-02-25 |
| items | list | Lijst met factuur-items. | - |
| total_without_tax | float | Totaal bedrag over alle factuur-items heen zonder rekening te houden met BTW. 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 |
| 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 |
| note | text | Nota die onderaan de factuur wordt getoond. Optioneel mee te geven. Maximum 2000 karakters lang. | 25 € kosten bij laattijdige betalingen. |
| 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. | 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. Kan tot op 6 decimalen nauwkeurig opgegeven worden, echter wordt het bedrag slechts tot op 2 decimalen nauwkeurig op de factuur getoond. | 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. | 2 |
| 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 |
| 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 |
| 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 |
| description | text | Omschrijving van de betaling. Optioneel mee te geven. Maximum 255 karakters lang. | Voorschot |
| remaining_amount | int | Aanduiding dat ervoor zorgt dat het veld 'amount' het volledige resterende nog niet betaalde bedrag van de factuur bevat. Kan enkel bij opgave gebruikt worden. Heeft steeds waarde '1'. | 1 |
| 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. Kan niet worden opgegeven maar krijgt huidige datum bij creatie. 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 |
Opmerking: Het subdomein 'recipients' is geen volwaardige subdomein en kan niet los van subdomein 'events' worden aangesproken.
Voorbeeld in XML van een factuur:
1 <invoice>
2 <invoice_id>3003</invoice_id>
3 <uri>http://eenvoudigfactureren.be/api/v1/invoices/3003</uri>
4 <external_invoice_id>Invoice-0983984</external_invoice_id>
5 <client>
6 <client_id>1001</client_id>
7 <uri>http://eenvoudigfactureren/api/v1/clients/1001</uri>
8 </client>
9 <type>invoice</type>
10 <number>INV2012-001</number>
11 <date>2012-02-15</date>
12 <status>open</status>
13 <days_due>10</days_due>
14 <days_overdue>0</days_overdue>
15 <date_overdue>2012-02-25</date_overdue>
16 <items>
17 <item>
18 <item_id>4004</item_id>
19 <uri>http://eenvoudigfactureren.be/api/v1/invoices/3003/items/4004</uri>
20 <description>product omschrijving</description>
21 <amount>100.00</amount>
22 <quantity>2</quantity>
23 <total_without_tax>200.00</total_without_tax>
24 <tax_rate>21</tax_rate>
25 <total_with_tax>242.00</total_with_tax>
26 </item>
27 </items>
28 <total_without_tax>200.00</total_without_tax>
29 <tax_rate_1>21</tax_rate_1>
30 <total_tax_1>42.00</amount_tax_1>
31 <tax_rate_2>12</tax_rate_2>
32 <total_tax_2>0.00</amount_tax_2>
33 <tax_rate_3>6</tax_rate_2>
34 <total_tax_3>0.00</amount_tax_2>
35 <total_with_tax>242.00</total_with_tax>
36 <total_paid>25.0</total_paid>
37 <note>25 € kosten bij laattijdige betalingen.</note>
38 <payments>
39 <payment>
40 <payment_id>5010</payment_id>
41 <uri>http://eenvoudigfactureren.be/api/v1/invoices/3003/payments/5010</uri>
42 <date>2012-02-15</date>
43 <amount>25.00</amount>
44 <description>Voorschot</description>
45 </payment>
46 </payments>
47 <remarks>
48 <remark>
49 <remark_id>5020</remark_id>
50 <uri>http://eenvoudigfactureren.be/api/v1/invoices/3003/remarks/5020</uri>
51 <date>2012-02-15</date>
52 <description>Klant heeft goederen reeds ontvangen</description>
53 </remark>
54 </remarks>
55 <events>
56 <event>
57 <event_id>5030</event_id>
58 <uri>http://eenvoudigfactureren.be/api/v1/invoices/3003/events/5030</uri>
59 <date>2012-02-16</date>
60 <type>email sent</type>
61 <content>In bijlage uw factuur</content>
62 <recipients>
63 <recipient>
64 <name>Bart Decouster</name>
65 <email_address>bart.decouster@hisdomain.com</email_address>
66 </recipient>
67 </recipients>
68 </event>
69 </events>
70 </invoice>
| Domein : activities | |||
|---|---|---|---|
| Veldnaam | Type | Omschrijving | Voorbeeld |
| activity_id | int | Unieke ID van de activiteit. Gegenereerd door het systeem. Op te geven in URL. | 7001 |
| uri | text | URL naar de activiteit. Gegenereerd door het systeem. Te gebruiken bij aanspreken activiteit langs de API. | - |
| type | text | Codering dat het type van de activiteit bepaald. | invoice_create |
| date | datetime | Datum en tijd waarop de activiteit zich heeft voorgedaan. | 2012-10-01 18:28:35 |
| client_id | int | ID van de klant waarvoor de activiteit zich heeft voorgedaan. Bestaat enkel indien van toepassing voor dit type activiteit. | 1001 |
| client_uri | text | URL van de klant waarvoor de activiteit zich heeft voorgedaan. Bestaat enkel indien van toepassing voor dit type activiteit. | - |
| invoice_id | int | ID van de factuur waarvoor de activiteit zich heeft voorgedaan. Bestaat enkel indien van toepassing voor dit type activiteit. | 2002 |
| invoice_uri | text | URL van de factuur waarvoor de activiteit zich heeft voorgedaan. Bestaat enkel indien van toepassing voor dit type activiteit. | - |
| description | text | Omschrijving van de zich voorgedane activiteit. | Factuur aangemaakt |
| information | text | Bijkomende informatie over de zich voorgedane actiteit. | Factuur 2012-0001 aangemaakt (ID 2002) |
Mogelijke activiteitstypes: login, settings_create, settings_update, settings_password_reset, settings_password_forgot, client_create, client_update, client_delete, clientcontact_create, clientcontact_update, clientcontact_delete, clientcontact_delete_all, clientnote_update, invoice_create, invoice_update, invoice_create_copy, invoice_print, invoice_email, invoicepayment_create, invoicepayment_delete, invoicepayment_delete_all, invoicenote_create, invoicenote_delete, invoicenote_delete_all, backup_create, backup_restore, import_csv_outlook, import_other_account
Opmerking: Gegevens uit dit domein kunnen enkel worden opgevraagd (GET) en kunnen niet worden aangepast.
Voorbeeld in XML van een activiteit:
1 <activity>
2 <activity_id>7001</activity_id>
3 <uri>http://superhost/api/v1/activities/7001</uri>
4 <type>invoice_create</type>
5 <date>2012-10-01 18:28:35</date>
6 <client_id>1001</client_id>
7 <client_uri>http://superhost/api/v1/clients/1001</client_uri>
8 <invoice_id>2002</invoice_id>
9 <invoice_uri>http://superhost/api/v1/invoices/2002</invoice_uri>
10 <description>Factuur aangemaakt</description>
11 <information>Factuur 2012-0001 aangemaakt (ID 2002)</information>
12 </activity>