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. Wat koppelen ondernemers oplevert, staat in het API-center.

Waarom een koppeling met jortt loont

• Je bereikt een grote groep ondernemers. Jortt heeft 144.400+ gebruikers, 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.
• Je koppeling is te vinden. Ondernemers zoeken op de combinatie van hun pakket en hun boekhoudprogramma. Met een koppeling kun je die vraag beantwoorden.
• 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, waarmee je je eerste klant en factuur via de API aanmaakt.
• 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:

Bij authorization code logt je gebruiker zelf in bij jortt, geeft toestemming, en krijgt jouw applicatie toegang tot díé administratie. Een applicatie met client credentials 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 en daarna in jortt.
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, Jortt API-koppeling, Eigen API-koppeling. Hoe dat gaat, staat bij de jortt API.

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. Het versienummer staat in het pad, en elk onderdeel heeft zijn eigen nieuwste versie: facturen, offertes en boekingen op v3, klanten op v2. Een factuurlijst vraag je dus op met https://api.jortt.nl/v3/invoices.

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>.

Zo ziet stap 3 en 5 eruit, met verzonnen gegevens:

curl -X POST -u "VOORBEELD_CLIENT_ID:VOORBEELD_SECRET" \
  -d "grant_type=authorization_code&code=VOORBEELD_CODE&redirect_uri=https://koertt.example/jortt/terug" \
  https://app.jortt.nl/oauth-provider/oauth/token

curl https://api.jortt.nl/v3/invoices \
  -H "Authorization: Bearer VOORBEELD_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. Je gebruiker ziet de rechten in jortt met de naam tussen haakjes.

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.

Versies en verouderde endpoints

De endpoints van v1, en dezelfde endpoints zonder versie in het pad (zoals /invoices), zijn sinds 28 augustus 2026 verouderd. Ze blijven werken voor bestaande koppelingen, maar krijgen geen verbeteringen meer en worden later uitgezet. In de documentatie staan ze als DEPRECATED, en elk antwoord van zo’n endpoint draagt deze headers:

Deprecation: @1787875200
Link: <https://developer.jortt.nl/#deprecation-of-v1>; rel="deprecation"

De datum waarop een endpoint echt stopt, komt later in een Sunset-header. Bouw je iets nieuws, gebruik dan per onderdeel de nieuwste versie.

Jortt werkt aan een volgende versie van de API. Die is nog niet openbaar; de huidige versies blijven werken. Volg developer.jortt.nl voor nieuws.

Foutmeldingen

Elk antwoord is een JSON-object, met data bij succes en error bij een fout. Een fout ziet er zo uit:

{
  "error": {
    "code": 422,
    "key": "params.invalid",
    "message": "The parameters are invalid (either missing, not of the correct type or incorrect format).",
    "details": [
      { "param": "customer_id", "key": "is_missing", "message": "is missing" }
    ]
  }
}

Stuur je logica op key, niet op message; de tekst kan veranderen. De sleutels die je het vaakst tegenkomt:

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. In de proefperiode werkt de API wel.
• Er zijn geen webhooks. De API stuurt geen berichten uit als er iets verandert. 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.

Een AI-agent bouwen

Bouw je een AI-agent of wil je een AI-assistent met jortt laten werken, dan heb je geen aanmelding per e-mail nodig. De MCP-server van jortt laat een AI-tool zichzelf aanmelden zodra de gebruiker inlogt en toestemming geeft. Zo’n koppeling staat in jortt bij de gebruikers, met de rol AI-agent, en de gebruiker bepaalt per module wat hij mag. Lees de MCP-koppeling en een AI-agent als gebruiker.

Liever geen koppeling bouwen

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

• Via een koppelplatform. Partner APIcenter.io maakt en beheert koppelingen tussen jortt en tientallen pakketten. Zie Meer dan 50 apps koppelen via APIcenter.io.
• Via MCP. Voor rapportages en losse vragen kan een AI-assistent rechtstreeks bij een administratie, zonder dat er iets gebouwd wordt. Zie De jortt MCP-koppeling voor AI-assistenten.

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.