Startgids: de Reeleezee-REST-API

Transcriptie

1 Startgids: de Reeleezee-REST-API Iedere gebruiker moet bij al zijn administratiegegevens kunnen. Overal en altijd. Met die gedachte verwachten gebruikers ook dat andere softwareprogramma s toegang kunnen hebben tot de financiële gegevens in hun boekhouding. Dat kan nu nog makkelijker, maar uiteraard wel veilig. De nieuwe Reeleezee-API (Application Programming Interface), gebaseerd op het REST-principe, biedt een technisch koppelvlak voor softwareontwikkelaars om koppelingen, sneller, eenvoudiger en completer voor Reeleezeegebruikers te bouwen. Elke Reeleezee-administratie kan benaderd worden via de REST-API. U kunt zowel uw bestaande administratie geschikt maken voor REST-API-gebruik, of hiervoor een nieuwe (test)administratie aanmaken op onze website ( U kunt daar een abonnement met de gratis varianten van Reeleezee Administratie en Reeleezee Factuur aanmaken. Er zit geen tijdsbeperking aan een gratis abonnement: u kunt deze zo lang gebruiken als u wilt. U kunt er eventueel voor kiezen op een later moment uw abonnement te upgraden. 1

2 REST-API-login aanmaken Om een Reeleezee-administratie via de REST-API te kunnen benaderen, moet gebruik worden gemaakt van een speciaal logintype. In iedere Reeleezee-administratie kan één gratis login van dit type worden aangemaakt. Als u bent ingelogd in uw administratie, kunt u deze login aanmaken via de map Instellingen - Algemene instellingen - Webservice-koppelingen. Klik rechtsboven op Nieuw om een REST-API-login aanmaken. Nadat u een naam voor de koppeling heeft ingevoerd, klikt u rechtsonder op Opslaan. Hierdoor verschijnt het tabblad Toegang. Hier kunt u de gebruikersnaam en het wachtwoord voor de REST-API-login invoeren. Deze logingegevens gebruikt u om de REST-API geauthentiseerd aan te spreken. Let op: voor het einde van het jaar zal authenticatie voor het gebruik van de REST-API volledig overgaan op OAuth 2.0 de authenticatie op basis van gebruikersnaam en wachtwoord komt dan te vervallen. Houdt u hier alvast rekening mee. 2

3 Onder het tabblad Rechten kunt u instellen tot welke (sub)mappen de REST-API-login rechten dient te krijgen. SOAP/XML API Onze eerdere XML/SOAP-API blijft beschikbaar voor het importeren van gegevens in een Reeleezeeadministratie. Informatie omtrent deze API kunt u vinden op Daar vindt u de schemabestanden die u kunt gebruiken om een valide xml-bestand te genereren. Ook kunt u daar aanvullende technische informatie en een PHP-voorbeeld vinden, waarin de taxonomiewebservice wordt aangeroepen, incl. XML-voorbeeld met uitleg bij een aantal elementen. Wij adviseren echter alle gebruikers van de SOAP/XML-API om nieuwe ontwikkelingen te doen op basis van de nieuwe REST-API. 3

4 REST-API en OData U kunt alle resources terugvinden op De resources worden ontsloten middels OData versie 4.0 ( Op dit moment ondersteunen wij alle logische en rekenkundige operators en de volgende query s: $filter $select $orderby $top $skip $count Om een lijst met verkoopfacturen van de doeladministratie op te vragen, roept u (geauthentiseerd) het volgende aan: Elke individuele resource heeft een GUID toegekend gekregen onder de elementnaam id. Deze kunt u gebruiken als direct pad naar de desbetreffende resource, bijvoorbeeld: Voor sommige resources zult u extra informatie kunnen opvragen middels gebruik van dit directe pad. Daarnaast kunt u in de documentatie (op eigenschappen van resources tegenkomen die u niet direct terugziet als u deze resource opvraagt. Het gaat hierbij om eigenschappen die een verwijzing vormen. Bij de resource SalesInvoices ( SalesInvoices-id) vindt u bijvoorbeeld de eigenschap DocumentCategory terug. Deze kunt u opvragen door middel van de $expand query, die u eventueel in geneste vorm kunt gebruiken: cbdaed4652ba?$expand=documentcategory($expand=documentbinder) U kunt meerdere OData query s in één call kwijt. Als u bijvoorbeeld een lijst wilt van verkoopfacturen van ná 2012, waarvan het totaalbedrag groter is dan 100, gerangschikt op totaalbedrag (hoog naar laag), roept u dat op onderstaande wijze op: gt 100 and year(date) gt 2012&$orderby=TotalPayableAmount desc We verzoeken u bij het opvragen van resources de volgende HTTP-headers te gebruiken: Accept: application/json Accept-Charset: iso Accept-Encoding: gzip, deflate Accept-Language: nl-nl Een call aan onze REST-service kan de volgende HTTP-statuscodes teruggeven: 401 (Unauthorized): De gebruikte REST-API-logingegevens zijn niet bekend. 402 (PaymentRequired): Het abonnement van de aangesproken administratie is niet betaald. 403 (Forbidden): De gebruikte REST-API-login heeft niet genoeg rechten voor de gevraagde actie 429 (Too Many Requests): U heeft te veel REST-API-calls gedaan in te korte tijd 404 (NotFound): De webservice zoals deze is aangesproken, is niet gevonden. 500 (InternalServerError): Dit betreft een generieke foutmelding. 4

5 REST-API-limieten Om een goede performance van de REST-API voor alle gebruikers te kunnen garanderen, willen we onnodig overmatig gebruik ervan voorkomen. Het is daarom belangrijk dat partijen die een koppeling maken op basis van de REST-API een aantal uitgangspunten in acht nemen om overmatige belasting te voorkomen. Wij adviseren de volgende aandachtspunten: Vermijd het meermaals opvragen van resources binnen een te korte tijd, zeker in het geval van resources die niet regelmatig gewijzigd worden. Vraag alleen data op die u nodig heeft. Als u al weet dat u een slechts een bepaalde subset van de facturenlijst nodig heeft, geef deze parameters dan mee in de $filter en $select query s. Als u enkel een specifieke resource wil opvragen, gebruik dan de GUID, bijvoorbeeld: Streef ernaar om periodieke geautomatiseerde calls zoveel als mogelijk buiten kantooruren uit te laten voeren. Om desondanks beschermd te zijn tegen te hoge belastingen door 1 enkele partij heeft Reeleezee een aantal limieten ingebouwd die automatisch actief worden. Standaard zijn er daarom de volgende grenzen gesteld aan het gebruik van de REST-API: Maximaal 60 REST-API-calls per minuut Maximaal 60 records per call (geldt alleen voor de importfunctie van de REST-API) Dezelfde REST-API-login kan niet gebruikt worden voor meerdere simultane REST-API-calls. In zo n geval zal de tweede aanroep een response terugkrijgen dat de REST-API-login reeds in gebruik is. Bij het driemaal achtereen foutief importeren van data naar een Reeleezee-administratie binnen 1 minuut, zal de desbetreffende REST-API-login voor 10 minuten geblokkeerd worden. Dit zal tevens worden meegegeven in de response, zodat u uw code hierop kunt laten reageren en zodoende niet tevergeefs blijft proberen dezelfde data in te lezen. Voor de bovenstaande limieten geldt dat Reeleezee, op basis van o.a. de serverbelasting die we ondervinden, in de toekomst de specifieke parameters van deze limietmechanismen zowel naar boven als wel naar beneden kan aanpassen. Tevens kunnen er in de toekomst extra limieten toegepast worden of limieten komen te vervallen. U zult hier uiteraard tijdig van op de hoogte gesteld worden. Postman U kunt eventueel Postman gebruiken om snel bekend te worden met onze REST-API. Dit is een gratis Google Chrome add-on, die dient als REST-client. Meer informatie vindt u op de website van Postman ( Commentaar en vragen Mocht u vragen hebben over, of commentaar hebben op onze REST-API, dan kunt u ons telefonisch bereiken op , of per op [email protected]. 5