Koppeling boekhoudprogramma

Jortt 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 Compleet abonnement. Iedereen kan een koppeling maken, we stellen het wel op prijs als je ons laat weten dat je een koppeling gaat maken. Dan kunnen we je applicatie ook op onze website noemen. Er is er een testomgeving beschikbaar om de integratie te testen. Wil je toegang tot de testomgeving of heb je andere vragen stuur ons dan een e-mail.

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

Maak een API Key

Om met een API te kunnen koppelen met Jortt heb je een API Key nodig. Deze kun je aanmaken in je Profiel onder ‘Externe koppeling’. Geeft een naam op voor de koppeling om later eenvoudig terug te vinden welke API Key bij welke applicatie hoort en klik op ‘Registreer externe applicatie’. Er wordt een nieuwe API Key gegenereerd en getoond.

Houd de API Key altijd geheim om ongeoorloofde toegang tot je administratie te voorkomen. Beschrijving REST API

Autorisatie en authenticatie

De Jortt API is alleen beschikbaar voor klanten met een Jortt Compleet 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 de Base64 encoded waarde van de 'applicatie naam:api key'.

Voorbeeld

Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

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 Compleet 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,
      "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,
      "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:

{"customer":
  {
    "company_name": "Bedrijfsnaam, verplicht",
    "attn": "Ter attentie van, optioneel",
    "email": "E-mail adres, optioneel",
    "extra_information": "Extra informatie over de klant, optioneel",
    "invoice_language":"Taal waarin de facturen en offertes worden verstuurd. Standaard 'nl'. Mogelijke waarden: 'nl', 'de', 'en', 'fr', 'es'"
    "address":
      {
        "street": "Straat, verplicht",
        "postal_code": "Postcode, verplicht",
        "city": "Plaats, verplicht",
        "country_code": "Tweecijferige landcode, verplicht"
      }
  }
}

Resultaat

Statuscode 201 en de ID van de aangemaakte klant:

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

Facturen

Factuur ophalen

GET /invoices/: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 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",
    "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": {
		"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": "31-12-2016", // 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?query=Jortt

Parameters

query - Zoekterm

Resultaat

Status 200 en een lijst van facturen in JSON formaat:

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


boekhouding kopplen met eHour urentool urenregistratie