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 kun je hierna de ID van het element doorgeven. Hierna kun je 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
Het formaat
Het formaat van de communicatie verloopt standaard langs XML maar ook JSON wordt ondersteund. Daarnaast kan je ook de standaard form-encoding gebruiken bij het wijzigen van gegevens. Stuur je bijvoorbeeld gegevens op langs JSON dan kan je ook een antwoord in JSON terug verwachten. Stuur je bijvoorbeeld jouw gegevens door in XML of form-encoding dan wordt er een antwoord in XML teruggestuurd. Wens je hiervan af te wijken en zelf te bepalen wat het teruggestuurde antwoord wordt, kan je 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, quotes, orders en deliveries)
- ?format=efff: E-fff formaat – elektronische factuur (enkel voor domein invoices)
- ?format=ublbe: UBL.BE formaat – elektronische factuur (enkel voor domein invoices)
- ?format=peppolbis3: PEPPOL BIS 3.0 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 aanduidt 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