Jortt API (Oud)

Deze API is vervangen door een nieuwe API.

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.

Naast een Ruby gem is er ook een Java library beschikbaar om met Jortt te koppelen: https://github.com/te-con/jorttconnector.

Ook voor PHP is een script beschikbaar: https://github.com/FabriceDelahaij/JORTTBV-PHP-API.

Sandbox

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.

  1. Klik rechtsboven op Instellingen.
  2. Klik op Jortt API.
  3. Geeft een Applicatie naam op om later eenvoudig terug te vinden welke API Key bij welke applicatie hoort.
  4. Klik op Opslaan.
  5. 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

curl -u [applicatie naam]:[api key] https://app.jortt.nl/api/invoices/status/due

Algemene statuscodes

StatusUitleg
400Treedt 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"}}}
401Authenticatie header ontbreekt of api key en app name zijn ongeldig.
403Gebruiker heeft geen Jortt MKB of Jortt Plus abonnement.

Operaties

Klanten

Klanten zoeken
GET /customers?query=Jortt
Parameters

query - (Gedeelte van de) naam van het bedrijf

Resultaat

Status 200 en een lijst van customers in JSON formaat:

{"customers":
  [
    {
      "customer_id": "unique identifier van de klant",
      "finance_company_name": "Naam",
      "finance_address_street": "Paleisstraat 1",
      "finance_address_city": "Amsterdam",
      "finance_address_postal_code": "1000AA",
      "finance_address_country_code": "NL",
      "finance_address_country_name": "Nederland",
      "finance_attn": "Financiële afdeling",
      "finance_email": "finance@localhost.local",
      "finance_extra_information": "Optionele extra informatie voor deze klant",
      "vat_number": "BTW nummer van de klant",
      "payment_term": 14,
      "deleted": false, (Is de klant gearchiveerd true / false)
      "invoice_language":"Taal waarin de facturen en offertes worden verstuurd."
    }
  ]
}
Alle klanten
GET /customers/all?page=1&per_page=25
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:

{"customers":
  [
    {
      "customer_id": "unique identifier van de klant",
      "finance_company_name": "Naam",
      "finance_address_street": "Paleisstraat 1",
      "finance_address_city": "Amsterdam",
      "finance_address_postal_code": "1000AA",
      "finance_address_country_code": "NL",
      "finance_address_country_name": "Nederland",
      "finance_attn": "Financiële afdeling",
      "finance_email": "finance@localhost.local",
      "finance_extra_information": "Optionele extra informatie voor deze klant",
      "vat_number": "BTW nummer van de klant",
      "payment_term": 14,
      "deleted": false, (Is de klant gearchiveerd true / false)
      "invoice_language":"Taal waarin de facturen en offertes worden verstuurd."
    }
  ],
  "page": 1,
  "per_page": 25
}
Klant aanmaken
POST /customers

De request body dient de volgende JSON data te bevatten voor een bedrijf:

{"customer":
  {
    "company_name": "Bedrijfsnaam, verplicht",
    "attn": "Ter attentie van, optioneel",
    "email": "E-mail adres, optioneel",
    "shift_vat": "Btw verlegd (true / false), optioneel",
    "vat_number": "Btw-nummer, optioneel",
    "phonenumber": "Telefoonnummer, optioneel",
    "coc_number": "KvK-nummer, optioneel",
    "website": "Website, optioneel",
    "reference": "Een vrij te gebruiken referentie, bijvoorbeeld klantnummer, optioneel",
    "additional_information": "Informatie over je klant, optioneel",
    "extra_information": "Extra adresinformatie, optioneel",
    "invoice_language": "Taal waarin de facturen en offertes worden verstuurd. Standaard 'nl'. Mogelijke waarden: 'nl', 'de', 'en', 'fr', 'es'",
    "payment_term": "Betalingstermijn in dagen, optioneel. Valt terug op de ingestelde standaard betalingstermijn van de organisatie.",
    "email_salutation": "De aanhef welke gebruikt wordt in de e-mails naar de klant, optioneel. Standaard 'Geachte heer, mevrouw,'",
    "address": {
      "street": "Straat, verplicht",
      "postal_code": "Postcode, verplicht",
      "city": "Plaats, verplicht",
      "country_code": "Tweeletterige ISO-landcode, verplicht. Voorbeeld: 'NL' voor Nederland, 'BE' voor België."
    }
  }
}

Voor een particuliere klant is veel minder data verplicht:

{"customer":
    {
      "company_name": "Naam van de particulier",
      "invoice_language": "nl",
      "is_private": true, (Geeft aan dat het hier om een particuliere klant gaat),
      "date_of_birth": "Geboortedatum, optioneel, formaat: DD-MM-YYYY",
      "salutation": "Aanhef, optioneel. Mogelijke waarden: 'sir', 'madam' of 'family'",
      "first_name": "Voornaam, optioneel",
      "last_name": "Achternaam, optioneel",
      "initials": "Initialen, optioneel",
      "citizen_service_number": "Burgerservicenummer, optioneel",
      "address": {
        "country_code": "NL"
      } 
    }
}

Resultaat

Statuscode 201 en de ID van de aangemaakte klant:

{"customer_id": "ID van de aangemaakte klant"}

Facturen

Factuur ophalen
GET /invoices/id/:invoice_id
Parameters

invoice_id - De id van de factuur

Resultaat

Status 200 en een lijst van facturen in JSON formaat:

{
  "invoice_id": "id-van-de-invoice",
  "recipient": {
    "company_name": "Naam van de klant",
    "attn": "Ter attentie van",
    "address": {
      "street": "straat",
      "city": "straat",
      "postal_code": "straat",
      "country": {
        "code": "Landcode",
        "name": "Naam van het land"
      },
    },
    "email": "E-mail adres van de klant",
    "customer_id": "ID van de klant",
    "extra_information": "Extra informatie",
    "shift_vat": "Indicator of de btw voor deze klant verlegd moet worden",
    "vat_number": "Btw nummer van de klant",
    "payment_term": "Betaaltermijn",
  },
  "recipient_in_eu": "",
  "creditor": { // Je eigen gegevens voor deze factuur
    "company_name": "Bedrijfsnaam",
    "company_name_line_2": "Extra informatie bedrijfsnaam",
    "address": {
      "street": "straat",
      "city": "straat",
      "postal_code": "straat",
      "country": {
        "code": "Landcode",
        "name": "Naam van het land"
      },
    },
    "phonenumber": "Telefoonnummer",
    "bank_information": {
      "bic": "BIC code",
      "iban": "IBAN",
      "in_the_name_of": "Tenaamstelling bankrekening",
      "description": "Omschrijving bankrekening",
    },
    "vat_number": "Btw nummer",
    "coc_number": "Kvk nummer",
    "profession": "Indicator of je een zorginstelling bent",
    "healthcare_data": {
      "bignummer": "BIG nummer",
      "agb_zorgverlenerscode": "Zorgverlenerscode",
      "agb_praktijkcode": "Praktijdcode",
    },
    "free_of_vat": "Indicator of je btw plichtig bent",
    "finance_email": "Je e-mail adres die als reply-to wordt vermeld bij je factuur",
  },
  "line_items": [{
    "description": "Factuurregel omschrijving",
    "vat": "Btw percentage",
    "amount": "Bedrag",
    "total_amount_ex_vat": "Totaal bedrag ex btw",
    "quantity": "Aantal",
    "currency": "Valutacode",
  }],
  "invoice_currency": "Valutacode",
  "invoice_total": "Totaalbedrag ex btw",
  "invoice_total_incl_vat": "Totaal bedrag incl btw",
  "invoice_number": "Factuur nummer",
  "invoice_status": "Factuur status",
  "invoice_due_date": "Vervaldatum",
  "invoice_date": "Factuurdatum",
  "invoice_delivery_period": "Leverdatum",
  "invoice_remarks": "Opmerkingen bij factuur",
  "invoice_language": "Taal van de factuur",
  "invoice_reference": "Referentie bij de factuur",
  "credited_invoice_id": "ID van de gecrediteerde factuur indien dit een creditfactuur is",
}
Factuur PDF downloaden
GET /invoices/id/:invoice_id?format=pdf
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
POST /invoices

De request body dient de volgende JSON data te bevatten:

{"invoice":
  {
    "customer_id": "ID van de klant aan wie de factuur is gericht, optioneel",
    "delivery_period": "Datumlevering, optioneel, formaat: DD-MM-YYYY",
    "reference": "Referentie, optioneel",
    "remarks": "Tekst onder de factuurregels, optioneel",
    "introduction": "Opmerkingen boven factuurregels, optioneel",
    "line_items":
      [
        {
          "vat": "BTW percentage, verplicht, formaat: Getal (voorbeeld: 21)",
          "amount": "Bedrag fatuurregel, verplicht, formaat: Getal (voorbeeld: 1359.50)",
          "quantity": "Aantal, verplicht, formaat: Getal",
          "description": "Beschrijving, verplicht"
        }
      ]
  }
}

Resultaat

Statuscode 201 en de ID van de aangemaakte factuur:

{"invoice_id": "ID van de aangemaakte factuur"}
Factuur versturen
POST /invoices/id/:invoice_id/send

De :invoice_id is de invoice_id uit het resultaat van een factuur aanmaken. De request body dient de volgende JSON data te bevatten:

{
  "mail_data": { // Alleen toevoegen wanneer verzonden met e-mail "send_method":"email"
    "to": "api@jortt.nl", // E-mail adres van de klant. Optioneel indien klant al een e-mail adres heeft in Jortt
    "subject": "Onderwerp", // Onderwerp van de e-mail. Optioneel, wordt standaard gevuld met de template waarde uit Jortt
    "body": "Body" // Body-tekst van de e-mail. Optioneel, wordt standaard gevuld met de template waarde uit Jortt
  },
  "invoice_date": "2018-12-31", // Factuur datum. Optioneel, wordt standaard gevuld met datum van vandaag
  "payment_term": 7, // Betaaltermijn in dagen. Optioneel, wordt standaard gevuld met de betaaltermijn van de klant of anders de standaard betaaltermijn van de organisatie
  "send_method": "email" // Manier hoe de factuur verstuurd dient te worden. Optioneel, standaard 'email'. Mogelijke keuzes: 'email', 'post', 'jortt'
}

Resultaat

Statuscode 200 en het factuurnummer van de verstuurde factuur:

{"invoice_number": "2016-002"}
Facturen zoeken
GET /invoices/search?query=jortt
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:

{"invoices":
  [
    {
      // payload van de facuur zoals bij Factuur ophalen
    }
  ]
}
Credit factuur maken voor bestaande factuur
POST /api/invoices/id/:invoice_id/credit
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:

{"invoice_id": "ID van de aangemaakte credit factuur"}
Lijst met facturen op basis van de status
GET /invoices/status/[all|due|draft|late|due_and_late|paid]

Resultaat

Status 200 en een lijst van facturen in JSON formaat:

{"invoices":
  [
    {
      // payload van de facuur zoals bij Factuur ophalen
    }
  ]
}

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.