URL-structuur
Elke API-aanroep begint met een basis-URL:
- https://eenvoudigfactureren.be/api
- https://app.simplybooks.be/api
Daarna volgt de versie van de API, momenteel: v1. Vervolgens geef je het domein op, zoals invoices, clients of activities.
Je kan dit verder uitbreiden met:
- een ID van een specifiek object,
- een optioneel subdomein (zoals items, contacts),
- en desgewenst opnieuw een ID.
Voorbeeld: https://eenvoudigfactureren.be/api/v1/clients/101/contacts/9283
Dit verwijst naar contactpersoon 9283 van klant 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
Formaat van communicatie
Standaard gebruikt de API XML als formaat voor zowel verzoeken (requests) als antwoorden (responses). Daarnaast worden ook JSON en form-encoded data ondersteund.
JSON is aanbevolen voor moderne integraties en applicaties.
Form-encoding kan nuttig zijn bij eenvoudige updates via webformulieren.
Het antwoordformaat volgt standaard het formaat van het verzonden verzoek.
Werken met JSON
Wil je consistent werken met JSON? Voeg dan de volgende HTTP-headers toe aan je verzoek:
- 'Content-Type': 'application/json'
- 'Accept': 'application/json'
Antwoordformaat expliciet instellen
Wil je het antwoord in een ander formaat ontvangen dan je aanvraagformaat? Dan kan je dit specificeren via de format-parameter in de URL:
| Parameter | Omschrijving |
|---|---|
?format=xml | XML (standaard) |
?format=json | JSON |
?format=csv | CSV (bruikbaar in Excel) |
?format=html | HTML-tabel |
?format=pdf | PDF-bestand (enkel voor afdrukbare documenten) |
?format=efff | E-fff elektronisch factuurformaat (enkel voor: invoices) |
?format=ublbe | UBL.BE elektronisch factuurformaat (enkel voor: invoices) |
?format=peppolbis3 | PEPPOL BIS 3.0 formaat (enkel voor: invoices) |
HTTP-methodes
De API ondersteunt de vier standaard HTTP-methodes:
| Methode | Betekenis |
|---|---|
GET | Ophalen van gegevens |
POST | Aanmaken of gedeeltelijk bijwerken van gegevens (niet opgegeven velden blijven ongewijzigd) |
PUT | Volledig overschrijven van gegevens (alleen opgegeven velden blijven behouden) |
DELETE | Verwijderen van gegevens |
Resultcodes
Elke API-aanvraag retourneert:
een antwoord in het gevraagde formaat (XML, JSON, enz.),
én een HTTP-statuscode die de uitkomst van de actie aanduidt.
Mogelijke statuscodes
| Code | Betekenis |
|---|---|
200 | Succesvolle aanvraag |
201 | Gegeven werd aangemaakt |
400 | Fout door ongeldige gegevens |
401 | Authenticatie mislukt |
403 | Toegang geweigerd |
404 | Gevraagd object niet gevonden |
500 | Interne serverfout |