Grundlagen

Die bookamat wurde als RESTful Webservice umgesetzt. Alle Daten besitzen eine eindeutige URL und werden mittels GET, POST, PUT, PATCH und DELETE gelesen bzw. bearbeitet (wobei nicht für alle Ressourcen auch alle Methoden zur Verfügung stehen).

Datenformate

bookamat versteht die Formate XML und JSON (wobei innerhalb dieser Dokumentation ausschließlich das JSON Format verwendet wird).

Für einen schreibenden Request wird das Format im Content-Type definiert:

Content-Type: application/json bzw. application/xml

Für einen lesenden Request wird das Format entweder als Query String übergeben

?format=[xml|json]

oder im HTTP Header definiert:

Accept: application/json bzw. application/xml

UTF-8

Sämtliche Texte innerhalb der API werden als UTF-8 kodiert. Auch beim Senden von Requests (POST/PUT/PATCH) erwartet die API UTF-8 kodierte Strings.

Authentifizierung

Für einen privaten Zugriff erfolgt die Authentifizierung über Username und API–Key. Jeder Benutzer findet unter Mein Account seinen persönlichen API–Key.

Authorization: ApiKey username:apikey

Für den Zugriff mittels Applikation wird eine Kombination von SOURCE–Key (zur Identifizierung der Applikation) und API–Key (zur Identifizierung des Users) benötigt.

Authorization: SourceApiKey sourcekey:apikey

In beiden Fällen kann nur auf Daten eines aktiven, bezahlten Jahrespakete ab 2015 zugegriffen werden.

URLs

Prefixes

Vor jede in dieser Dokumentation erwähnten URL muss https://www.bookamat.com/api/<api-version>/<country>/<year>/ gestellt werden.

Wenn in der Dokumentation folgendes steht ...

/bookings/

ist die gesamte URL für einen Zugriff auf das Paket AT 2015 für Version v1 der API ...

https://www.bookamat.com/api/v1/at/2015/bookings/

Query Parameter

Parameter (z.B. für die Sortierung oder Filterung von Listen) werden der URL als Query String angehängt.

https://www.bookamat.com/api/v1/at/2015/bookings/?ordering=id&group=1

Liste/Detail

Wenn nicht anders angegeben ist die Detail URL einer Ressource deckungsgleich mit der Listen URL plus Angabe der ID.

Liste der Zahlungsmittelkonten:

/preferences/bankaccounts/

Einzelnes Zahlungsmittelkonto:

/preferences/bankaccounts/{id}/

POST Requests müssen die URL der Liste verwenden. PATCH/PUT und DELETE Requests müssen die Detail URL verwenden.

Filter, Sortierung

Für die Filterung bzw. Sortierung von Listen (GET Requests) stehen in den meisten Fällen unterschiedliche Optionen zur Verfügung. Die Parameter werden der URL als Query String übergeben.

https://www.bookamat.com/api/v1/at/2015/bookings/?group=1

Die Felder für die Filter können auch kombiniert werden, zB:

https://www.bookamat.com/api/v1/at/2015/bookings/?group=1&costaccount=2361

Dasselbe gilt für die Sortierung, d.h. auch hier können die verschiedenen Optionen kombiniert werden (getrennt durch Beistrich):

https://www.bookamat.com/api/v1/at/2015/bookings/?ordering=date,group

Fehlermeldungen

Sollte ein Zugriff nicht möglich sein (z.B. aufgrund fehlgeschlagener Authentifizierung), wird der entsprechende Status–Code im HTTP–Header zurückgegeben. Bei einem fehlerhaften Schreibzugriff wird zudem eine genauere Fehlermeldung innerhalb des Response–Body ausgegeben. Alle Status–Codes und Fehlermeldungen werden ausschließlich in Englisch angegeben.

  • 200: OK Wird bei einem erfolgreichen Request zurückgegeben.
  • 201: CREATED Wird beim erfolgreichen hinzufügen eines Objektes zurückgegeben.
  • 202: ACCEPTED Wird beim erfolgreichen ändern eines Objektes zurückgegeben.
  • 204: NO CONTENT Wird beim erfolgreichen Löschen eines Objektes zurückgegeben.
  • 400: BAD REQUEST Wird bei einem Fehler zurückgegeben. Der Response–Body enthält die genaue Fehlermeldung.
  • 401: UNAUTHORIZED Wird zurückgegeben, wenn kein Zugriff auf die Ressource erlaubt ist.
  • 404: NOT FOUND Wird zurückgegeben, wenn die Ressource nicht existiert.
  • 405: METHOD NOT ALLOWED Wird zurückgegeben, wenn eine Methode (z.B. POST) für eine bestimmte Ressource nicht erlaubt ist.
  • 415: UNSUPPORTED MEDIA TYPE Wird zurückgegeben, der content-type falsch gesetzt ist.
  • 500: INTERNAL SERVER ERROR Wird bei einem Server-Fehler zurückgegeben.

Beim Zugriff mittels POST werden die Daten validiert. Ein Validierungsfehler wird durch den Status–Code 400 und eine Fehlermeldung im Response-Body angezeigt. Die Fehlermeldung besteht aus einem key-value-pair für Feldname und Fehlerbeschreibung.

  • fieldname: Error message
{
    "costaccount": [
        "This field may not be null."
    ]
}

Wenn der Fehler nicht notwendigerweise einem einzigen Feld zuordenbar ist, wird als key non_field_errors verwendet:

{
    "non_field_errors": [
        "deductibility_amount_percent is blocked with the selected cost account."
    ]
}

Felder

Für einen POST Request benötigte Felder sind immer mit * gekennzeichnet (siehe Feld Ganzzahl in der unten angeführten Liste).

Ganzzahl *:

1234567

Anmerkung
Ganzzahlen sind die einzigen Werte innerhalb der API, die nicht als String formatiert ausgegeben werden.
Dezimalzahl:

"222222222.00"

Format
Max. 9 Vorkommastellen, max. 2 Nachkommastellen
Anmerkung
Dezimalfelder werden als String formatiert ausgegeben, damit die Dezimalstellen korrekt dargestellt werden.
String:

"Buchungstitel"

Anmerkung
Die max. Anzahl an Buchstaben ist beim jeweiligen Feld angegeben.
String (Auswahl):

"1", "DE"

Anmerkung
String, für den nur bestimmte – beim jeweiligen Feld angegebene – Inhalte zulässig sind.
Text:

"Beschreibungstext"

Anmerkung
Die max. Anzahl an Buchstaben ist beim jeweiligen Feld angegeben.
Base64:

"ZGFzaXN0ZWluYmFzZTY0c3RyaW5n"

Anmerkung
Spezielles Text-Feld, das einen Base64-kodierten String enthält.
Boolean:

true/false

Anmerkung
Bei einem GET Request werden Boolean Felder als true bzw. false ausgegeben.
Bei einem POST Request sind sowohl true und false als auch 0 und 1 zulässig.
Datum:

"YYYY-MM-DD"

Format
"YYYY-MM-DD"
Datum/Zeit:

"YYYY-MM-DD hh:mm:ss"

Format
"YYYY-MM-DD hh:mm:ss"
Objekt:

{}

Anmerkung
Ein Objekt kann sämtliche bisher aufgelisteten Elemente beinhalten (z.B. String, Boolean, Datum).
Beispiele
{"id": 1, "name": "eins"}
Liste:

[]

Anmerkung
Eine Liste kann sämtliche bisher aufgelisteten Elemente beinhalten (z.B. String, Boolean, Datum, Objekt).
Beispiele
["1", "2", "3", "4"]
[{"id": 1, "name": "eins"}, {"id": 2, "name": "zwei"}]

Positionsfelder

Positionsfelder werden in der Dokumentation entsprechend gekennzeichnet und Verhalten sich folgendermaßen: Wenn Objekte (z.B. Zahlungsmittelkonten) ein Positionsfeld haben und dieses Feld verändert wird, dann werden automatisch alle Positionen aller Objekte (z.B. aller Zahlungsmittelkonten) verändert.

position:

Position

Format
Ganzzahl
Anmerkung
Abhängig vom Positionswert ändern sich automatisch die Positionen aller anderen Objekte
Default
Letzte Position (falls keine Position angegeben wird)

Beispiel 1

Ich habe 2 aktive Zahlungsmittelkonten mit den Positionen 0 und 1:

{
    "results": [
        {
            "id": 1254,
            "name": "Bankkonto",
            "position": 0
        },
        {
            "id": 1255,
            "name": "Kreditkarte",
            "position": 1
        },
    ]
}

Jetzt füge ich ein neues Konto mit der Position 0 hinzu. Das neue Konto ist damit an der ersten Stelle. Die Positionen der beiden vorhandenen Konten verändern sich entsprechend.

{
    "results": [
        {
            "id": 1256,
            "name": "Paypal",
            "position": 0
        },
        {
            "id": 1254,
            "name": "Bankkonto",
            "position": 1
        },
        {
            "id": 1255,
            "name": "Kreditkarte",
            "position": 2
        },
    ]
}

Beispiel 2

Ich habe 2 aktive Zahlungsmittelkonten mit den Positionen 0 und 1 (siehe vorheriges Beispiel). Jetzt füge ich ein neues Konto ohne Positionsangabe hinzu. Das neue Konto ist an der letzten Stelle. Die vorhandenen Konten werden nicht geändert.

{
    "results": [
        {
            "id": 1254,
            "name": "Bankkonto",
            "position": 0
        },
        {
            "id": 1255,
            "name": "Kreditkarte",
            "position": 1
        },
        {
            "id": 1256,
            "name": "Paypal",
            "position": 2
        }
    ]
}

Länder

Für die Angabe von Ländern (EU) stehen folgende Optionen zur Verfügung:

BE — Belgien
BG — Bulgarien
DK — Dänemark
DE — Deutschland
EE — Estland
FI — Finnland
FR — Frankreich
GR — Griechenland
IE — Irland
IT — Italien
HR — Kroatien
LV — Lettland
LT — Litauen
LU — Luxemburg
MT — Malta
NL — Niederlande
PL — Polen
PT — Portugal
RO — Rumänien
SE — Schweden
SK — Slowakei
SI — Slowenien
ES — Spanien
CZ — Tschechien
HU — Ungarn
GB — Vereinigtes Königreich
CY — Zypern

Für die Angabe von Ländern (Drittland) gibt es diese Möglichkeiten:

IS — Island
JP — Japan
CA — Kanada
LI — Liechtenstein
NO — Norwegen
CH — Schweiz
KR — Südkorea
TR — Türkei