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

Bei der Sortierung kann die Reihenfolge mit Angabe eines Minus vor dem Attribut geändert werden:

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

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 (EU)
CY — Zypern

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

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

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

AF — Afghanistan
AL — Albanien
DZ — Algerien
AD — Andorra
AO — Angola
AR — Argentinien
AM — Armenien
AZ — Aserbaidschan
AU — Australien
BH — Bahrain
BD — Bangladesch
BO — Bolivien
BA — Bosnien und Herzegowina
BW — Botsuana
BR — Brasilien
KY — Cayman-Inseln
CL — Chile
CN — China
CR — Costa Rica
CI — Côte d'Ivoire
CD — Demokratische Republik Kongo
DO — Dominikanische Republik
EC — Ecuador
SV — El Salvador
ER — Eritrea
FO — Färöer-Inseln
GM — Gambia
GE — Georgien
GH — Ghana
GD — Grenada
GL — Grönland
GT — Guatemala
GN — Guinea
HN — Honduras
HK — Hongkong
IN — Indien
ID — Indonesien
IQ — Irak
IR — Iran
IL — Israel
JM — Jamaika
YE — Jemen
JO — Jordanien
KH — Kambodscha
CM — Kamerun
KZ — Kasachstan
QA — Katar
KE — Kenia
KG — Kirgisistan
CO — Kolumbien
CG — Kongo
CU — Kuba
KW — Kuwait
LA — Laos
LB — Libanon
LR — Liberia
LY — Libyen
MY — Malaysia
ML — Mali
MA — Marokko
MK — Mazedonien
MX — Mexiko
MD — Moldawien
MC — Monaco
MN — Mongolei
ME — Montenegro
MZ — Mosambik
MM — Myanmar
NA — Namibia
NP — Nepal
NZ — Neuseeland
NI — Nicaragua
NE — Niger
NG — Nigeria
OM — Oman
PK — Pakistan
PA — Panama
PY — Paraguay
PE — Peru
PH — Philippinen
PR — Puerto Rico
RW — Ruanda
RU — Russland
ZM — Sambia
SM — San Marino
SA — Saudi-Arabien
SN — Senegal
RS — Serbien
ZW — Simbabwe
SG — Singapur
SO — Somalia
LK — Sri Lanka
SD — Sudan
SR — Suriname
SY — Syrien
ZA — Südafrika
SS — Südsudan
TJ — Tadschikistan
TW — Taiwan
TZ — Tansania
TH — Thailand
TG — Togo
TD — Tschad
TN — Tunesien
TM — Turkmenistan
UG — Uganda
UA — Ukraine
UY — Uruguay
UZ — Usbekistan
VE — Venezuela
AE — Vereinigte Arabische Emirate
US — Vereinigte Staaten von Amerika
VN — Vietnam
BY — Weißrussland
CF — Zentralafrikanische Republik
EG — Ägypten
ET — Äthiopien