De Jortt API is bedoeld voor ontwikkelaars van applicaties die met Jortt willen koppelen. De REST API is alleen beschikbaar voor klanten met een Jortt MKB of Jortt Plus abonnement. Iedereen kan een koppeling maken, we stellen het wel op prijs als je ons laat weten dat je een koppeling hebt gemaakt. Dan kunnen we je applicatie ook op onze website vermelden. Je kunt de API testen door een gebruikt te maken van de 30 dagen proefperiode bij het afsluiten van een proef abonnement.
Ontwikkel je een Ruby (on Rails) applicatie? Dan is er naast de REST API is er ook een Ruby gem beschikbaar. Zie Jortt op Rubygems en of kijk op onze Github pagina.
Om de Jortt API te maken en te testen kun je het beste een (extra) Jortt Starter account aanmaken. Hiermee kun je de API 30 dagen lang gratis testen.
Maak een API Key aan
Om met de Jortt API te kunnen koppelen met Jortt heb je een API Key nodig.
Klik rechtsboven op Instellingen.
Klik op Jortt API.
Geeft een Applicatie naam op om later eenvoudig terug te vinden welke API Key bij welke applicatie hoort.
Klik op Opslaan.
Er wordt een nieuwe API Key gegenereerd en getoond.
Houd de API Key altijd geheim om toegang tot je administratie te voorkomen. Wanneer iemand in het bezit is van je API key dan heeft deze persoon ook volledig toegang tot je administratie.
Beschrijving REST API
Autorisatie en authenticatie
De Jortt API is alleen beschikbaar voor klanten met een Jortt MKB rn Jortt Plus abonnement. Alle urls voor de Jortt API starten met https://app.jortt.nl/api. Bij elk request moet er een basic authentication header worden mee gestuurd met daarin als usernaam de applicatie naam en als wachtwoord de api key.
Voorbeeld
Algemene statuscodes
Status
Uitleg
400
Treedt op indien de invoer ongeldig is. Bijvoorbeeld een verplicht veld vergeten, of een veld is in het verkeerde formaat. De response body bevat extra informatie indien mogelijk: {"errors": {"delivery_period": {"code": "invalid"}}}
401
Authenticatie header ontbreekt of api key en app name zijn ongeldig.
403
Gebruiker heeft geen Jortt MKB of Jortt Plus abonnement.
Operaties
Klanten
Klanten zoeken
Parameters
query - (Gedeelte van de) naam van het bedrijf
Resultaat
Status 200 en een lijst van customers in JSON formaat:
Alle klanten
Parameters
page - Paginanummer, begint bij 1
per_page - Aantal klanten per pagina, default en maximaal 50
Resultaat
Status 200 en een lijst van customers in JSON formaat:
Klant aanmaken
De request body dient de volgende JSON data te bevatten voor een bedrijf:
Voor een particuliere klant is veel minder data verplicht:
Resultaat
Statuscode 201 en de ID van de aangemaakte klant:
Facturen
Factuur ophalen
Parameters
invoice_id - De id van de factuur
Resultaat
Status 200 en een lijst van facturen in JSON formaat:
Factuur PDF downloaden
Parameters
invoice_id - De id van de factuur
Resultaat
Status 302 met redirect naar een link om de factuur PDF te downloaden. Deze link is 10 minuten geldig.
Factuur aanmaken
De request body dient de volgende JSON data te bevatten:
Resultaat
Statuscode 201 en de ID van de aangemaakte factuur:
Factuur versturen
De :invoice_id is de invoice_id uit het resultaat van een factuur aanmaken. De request body dient de volgende JSON data te bevatten:
Resultaat
Statuscode 200 en het factuurnummer van de verstuurde factuur:
Facturen zoeken
Parameters
query - Zoekterm
Je kan zoeken naar de meeste onderdelen binnen de factuur zoals factuurnummer, klantnaam en adresgegevens, referentie, omschrijving in de factuurregels, bedrag, e.d.
Resultaat
Status 200 en een lijst van facturen in JSON formaat:
Credit factuur maken voor bestaande factuur
Parameters
:invoice_id - De id van de factuur waarvoor je een credit factuur maakt.
Resultaat
Statuscode 201 en de ID van de aangemaakte credit factuur:
Lijst met facturen op basis van de status
Resultaat
Status 200 en een lijst van facturen in JSON formaat:
De content is door Jortt met de grootst mogelijke zorg samengesteld, doch, aanvaardt Jortt geen aansprakelijkheid ten aanzien van mogelijke onjuistheden van het getoonde. Lees de volledige disclaimer.