Een koppeling met jortt bouwen voor je eigen software

Heb je een eigen SaaS-product, webshopplatform, urenregistratie of branchepakket, dan lopen je gebruikers vroeg of laat tegen dezelfde vraag aan: hoe krijg ik dit in mijn boekhouding? Met de jortt API bouw je die brug één keer, waarna al je gebruikers hem kunnen aanzetten.

Deze pagina is voor softwareontwikkelaars en producteigenaren. Gebruik je zelf jortt en wil je weten hoe je een koppeling aanzet, kijk dan bij De jortt API en koppelingen bouwen.

Waarom een koppeling met jortt loont

  • Je bereikt een grote groep ondernemers. 110.000+ ondernemers doen hun boekhouding in jortt, van zzp’er tot mkb-bedrijf.
  • Je haalt dubbel werk weg. Uren, orders, werkbonnen en betalingen die al in jouw software staan, hoeven niet nog een keer te worden overgetypt. Dat is voor de meeste gebruikers precies de reden om voor een pakket met koppeling te kiezen.
  • Een koppeling is een koopargument. Ondernemers zoeken actief op de combinatie van hun pakket en hun boekhoudprogramma. Een werkende koppeling is vaak het verschil tussen wel en niet op de shortlist staan.
  • Je koppeling blijft zichtbaar. Je komt in het overzicht met kant-en-klare koppelingen en in het App-center, de twee plekken waar ondernemers kijken of hun software met jortt praat.

Wat je krijgt

Je hoeft geen partnerprogramma te doorlopen en geen certificering te halen. Wat er beschikbaar is:

  • Openbare documentatie op developer.jortt.nl, zonder inloggen.
  • Een OpenAPI-specificatie (Swagger 2.0) op api.jortt.nl/swagger_doc, waaruit je met standaardgereedschap een client genereert in je eigen taal.
  • Een Postman-collectie, zodat je binnen een uur je eerste klant en factuur via de API hebt aangemaakt.
  • Een vermelding in het koppelingenoverzicht en in het App-center zodra je koppeling werkt.

Twee soorten koppelingen

De jortt API ondersteunt twee OAuth 2.0-varianten. Welke je nodig hebt, hangt af van voor wie je bouwt:

  • Authorization code. Voor een koppeling die door andere jortt-gebruikers wordt gebruikt, bijvoorbeeld een webshop, een urenregistratie of een branchepakket. Je gebruiker logt bij jortt in, geeft toestemming, en jouw applicatie krijgt toegang tot díé administratie. Dit is de variant die je nodig hebt als je iets voor je klanten bouwt.
  • Client credentials. Voor een applicatie die je alleen voor je eigen administratie maakt. Die applicatie is vast verbonden aan de administratie die hem heeft aangemaakt.

Zo meld je je applicatie aan

Voor de authorization code-flow is er geen selfservice-registratie. Je meldt je applicatie aan per e-mail:

  1. Bepaal welke scopes je nodig hebt. Vraag er niet meer aan dan je gebruikt; je gebruiker ziet ze op het toestemmingsscherm.
  2. Stuur een e-mail naar support@jortt.nl met de naam van je applicatie, je redirect-URL en de scopes die je nodig hebt.
  3. Je ontvangt daarna je client ID en client secret.

Bouw je alleen iets voor je eigen administratie, dan registreer je de applicatie zelf in jortt onder Instellingen, Koppelingen.

Tip
Zet in dezelfde e-mail meteen de gegevens voor je vermelding: de naam van je product, één of twee zinnen over wat de koppeling doet en de URL van je eigen pagina over de koppeling.

Zo werkt de koppeling technisch

De API is een REST-API op https://api.jortt.nl met JSON als formaat. De actuele versie is v3; het versienummer staat in het pad, bijvoorbeeld https://api.jortt.nl/v3/customers.

De autorisatie loopt via app.jortt.nl:

Autorisatie  https://app.jortt.nl/oauth-provider/oauth/authorize
Token        https://app.jortt.nl/oauth-provider/oauth/token

De flow in het kort:

  1. Stuur je gebruiker naar de autorisatie-URL met je client_id, je redirect_uri, response_type=code, de gevraagde scope (meerdere scopes gescheiden door een spatie) en een willekeurige state.
  2. Je gebruiker geeft toestemming en komt terug op je redirect_uri met een code en dezelfde state. Controleer die state en gooi alles weg wat niet klopt. De code is 10 minuten geldig.
  3. Wissel de code in bij de token-URL. Je client ID en secret stuur je mee via Basic Authentication, en de redirect_uri moet exact dezelfde zijn als in stap 1.
  4. Je krijgt een access_token dat 2 uur geldig is, plus een refresh_token. Bij het verversen krijg je zowel een nieuw access token als een nieuw refresh token terug.
  5. Roep de API aan met de header Authorization: Bearer <access_token>.

De redirect_uri moet er precies een zijn die je bij de aanmelding hebt doorgegeven, en je mag nooit meer scopes vragen dan je hebt laten registreren.

Wat je kunt koppelen

Je vraagt per onderdeel toegang aan, apart voor lezen en voor schrijven:

  • Klanten (customers:read, customers:write): klanten aanmaken, bijwerken, archiveren en btw-percentages ophalen.
  • Facturen (invoices:read, invoices:write): facturen aanmaken en in dezelfde aanroep versturen, crediteren, kopiëren, labelen en de pdf ophalen. Projecten en projectregels vallen ook onder deze scopes.
  • Offertes (estimates:read, estimates:write): offertes aanmaken, versturen, accepteren, afwijzen en met één aanroep omzetten in een factuur.
  • Uitgaven (expenses:read, expenses:write): uitgaven aanmaken en bijwerken, en er een bon aan koppelen.
  • Bonnen (inbox:write): afbeeldingen naar de Inbox uploaden, zodat de Boekhoudbot ze verwerkt.
  • Rapporten (reports:read): samenvattingen van facturen, btw, balans, winst-en-verlies en liquide middelen, bedoeld voor een dashboard.
  • Salaris (payroll:read, payroll:write): loonjournaalposten lezen en wegschrijven.
  • Bankgegevens (financing:read): bankrekeningen en banktransacties lezen.
  • Organisatie (organizations:read, organizations:write): bedrijfsgegevens, handelsnamen en labels.

Twee dingen die vaak net het verschil maken in een koppeling:

  • Versturen zit in de aanroep. Bij het aanmaken van een factuur of offerte geef je optioneel een verzendmethode mee: email, peppol of self. Laat je die weg, dan blijft het een concept dat je gebruiker zelf nog controleert. Verzenden via Peppol werkt alleen op v3.
  • Categorieën zijn opvraagbaar. Via de ledger accounts-endpoints haal je de categorieën op die je gebruiker in zijn eigen administratie kan kiezen, zodat je niets hoeft te raden of hard te coderen.

Goed om te weten voor je begint

Vier dingen die je beter vooraf weet dan halverwege:

  • Je gebruiker heeft jortt MKB of jortt Plus nodig. Een administratie op jortt Starter of jortt ZZP krijgt bij een API-verzoek de fout organization.requires_mkb_plan. Vang die netjes af en leg in je eigen interface uit wat je gebruiker moet doen.
  • Er zijn geen webhooks. De documentatie beschrijft geen callbacks. Wil je weten of er iets is veranderd, dan haal je de resource opnieuw op.
  • De limiet is 10 verzoeken per seconde, en je krijgt maximaal 100 resultaten per pagina. Bouw je een synchronisatie over veel administraties, houd daar dan rekening mee. Bij overschrijding krijg je een 429 met request.throttled.
  • Er is geen aparte testomgeving. Je test tegen een gewone administratie. Een gratis account aanmaken kan via jortt proberen.

Liever geen koppeling bouwen

Wil je je gebruikers wel een koppeling bieden zonder er zelf een te onderhouden, dan zijn er twee routes:

Aanmelden

Klaar om te beginnen? Stuur een e-mail naar support@jortt.nl met de naam van je applicatie, je redirect-URL en de scopes die je nodig hebt. Vermeld erbij dat je in het koppelingenoverzicht wilt komen, dan regelen we dat zodra je koppeling werkt.

De volledige technische documentatie staat op developer.jortt.nl.

Veelgestelde vragen over koppelen met de jortt API

Heb je een vraag? Wij hebben de antwoorden!

Voor een koppeling die namens andere jortt-gebruikers werkt, stuur je een e-mail naar support@jortt.nl met de naam van je applicatie, je redirect-URL en de scopes die je nodig hebt. Je krijgt daarna een client ID en een client secret. Bouw je alleen iets voor je eigen administratie, dan registreer je de applicatie zelf in jortt bij Instellingen, Koppelingen.

De documentatie, de OpenAPI-specificatie en de Postman-collectie zijn openbaar en vrij te gebruiken. Je gebruikers hebben wel jortt MKB of jortt Plus nodig: een administratie op jortt Starter of jortt ZZP krijgt bij een API-verzoek de foutmelding organization.requires_mkb_plan.

Bouw je een koppeling die door al je eigen gebruikers gebruikt moet kunnen worden, dan gebruik je de authorization code-flow. Bouw je iets voor één administratie, bijvoorbeeld je eigen boekhouding, dan gebruik je client credentials. Die applicatie is dan vast verbonden aan de administratie die hem heeft aangemaakt.

Nee. De documentatie beschrijft geen webhooks of callbacks. Om te zien of er iets is veranderd, bijvoorbeeld of een factuur is verstuurd, haal je de resource opnieuw op. Houd daarbij rekening met de limiet van 10 verzoeken per seconde.

De documentatie beschrijft geen aparte testomgeving. Ontwikkelaars testen tegen een gewone jortt-administratie. Je kunt daarvoor een gratis account aanmaken; voor de authorization code-flow heb je zelf geen jortt-account nodig, maar voor testen is het wel handig.

Ja. Werkende koppelingen komen in het overzicht met kant-en-klare koppelingen en in het App-center van jortt, zodat ondernemers die jouw software gebruiken je koppeling kunnen vinden. Stuur een e-mail naar support@jortt.nl met de naam van je product, een korte omschrijving en de URL van je eigen pagina over de koppeling.

De documentatie staat op developer.jortt.nl. De OpenAPI-specificatie (Swagger 2.0) staat op https://api.jortt.nl/swagger_doc en kun je gebruiken om een client te genereren. Er is ook een Postman-collectie, waarmee je je eerste klant en factuur via de API aanmaakt.

Ja. Bij het versturen van een factuur kies je als verzendmethode email, peppol of self. Verzenden via Peppol werkt alleen op v3 van de API.