API Dokumentation
Ergänzend zum Buchungsstapel für den Import in die Buchführungs-Software oder Weitergabe an den Steuerberater sind die verarbeiteten Daten über eine API (Application Programming Interface) abrufbar. Da Handelsberichte des Brokers häufig nur bedingt zur Analyse des Trading-Erfolgs geeignet sind, die Buchungsstapel auf der anderen Seite den primären Zweck der Buchführung erfüllen, wollen wir mit dieser API eine Lücke schließen. (Hinweis: die API ist nicht für den Abruf der Buchungsstapel erforderlich; diese werden per Mail zugestellt.)
Die API basiert auf einer RESTful und leicht verständlichen Anfrage- und Antwortstruktur. API-Anfragen werden stets über eine einfache URL mit einer Reihe obligatorischer und optionaler HTTP-GET-Parameter gesendet. API-Antworten werden im JSON-Format bereitgestellt.
API Authentifizierung
Für die individuelle Freischaltung der API und den Zugriff darauf ist die Aktivierung des API-Keys in den Benutzereinstellungen notwendig. Der Key muss beim Abruf der API als HTTP-Header mitgesendet werden.
Beispiel für einen Abruf:
> curl -H “X-API-KEY: <individueller API-Key>” “https://api.wertpapiere-verbuchen.de/?function=TradingJournal”
API Fehlermeldungen
API-Fehler bestehen aus Fehlercode- und Nachrichtenantwortobjekten. Tritt ein Fehler auf, wird ein HTTP-Statuscode zurückgegeben.
Bei Validierungsfehlern stellt die API außerdem ein Kontextantwortobjekt bereit, das zusätzliche Informationen zum aufgetretenen Fehler in Form eines oder mehrerer Unterobjekte zurückgibt. Jedes Unterobjekt enthält den Namen des betroffenen Parameters sowie Schlüssel- und Nachrichtenobjekte. Ein Beispiel für einen Fehler finden Sie unten.
Beispiel für eine Fehlermeldung:
{
“error”:”Invalid API key”
}
Liste der möglichen Fehlermeldungen:
| Fehlercode | Fehlermeldung | Beschreibung |
|---|---|---|
| 400 | Invalid date format | Ein Abfrage-Parameter weist ein falsches Datumsformat auf. Datumsangaben müssen in der Form JJJJ-MM-TT spezifiziert werden. |
| 400 | Invalid or missing function parameter | Es wurde kein oder eine falsche API-Funktion abgefragt (Parameter: ?function=...). |
| 400 | Invalid sort column | Es wurde ein falscher Parameter für die Sortierung übermittelt. |
| 400 | Invalid sort direction | Es wurde ein falscher Parameter für die Sortierungrichtung übermittelt. |
| 401 | API key is required | Es wurde kein API-Key im Header übermittelt. |
| 401 | Invalid API key | Es wurde ein falscher API-Key im Header übermittelt. |
| 500 | Authentication error | Es konnte mittels des API-Keys keine Authentifizierung vorgenommen werden. |
| 500 | Database query error | Es ist ein Fehler bei der Abfrage der Datenbank aufgetreten. |
| 500 | Database connection failed | Es konnte keine Verbindung zur Datenbank hergestellt werden. |
API Funktionen
API-Abrufe bestehen aus einer Kombination eines erforderlichen Funktionsparameters und optional mehreren Selektionsparametern. Beispiel für einen Abruf inkl. eines optionalen Selektionsparameters:Funktionsparameter:
| Parameter | Beschreibung |
|---|---|
| TradingJournal | Eine Aufstellung aller bereits geschlossenen und verbuchten Trades inkl. Angabe des Erlöses bzw. Verlustes in EUR so wie im Buchungsstapel enthalten. |
| AccountPositions | Eine Aufstellung aller offenen Positionen inkl. Angabe der Anschaffungskosten bzw. Verbindlichkeiten in EUR sowie des letzten Schlusskurses inkl. Wechselkurs. |
Selektionsparameter:
| Parameter | Beschreibung |
|---|---|
| symbol | Das Ticker-Symbol der Aktie bzw. des Wertpapiers. |
| assetCategory | Die Wertpapier-Gattung, z.B. STK, OPT, FUT, BOND. |
| securityID | Die ISIN (sofern für die jeweilige Wertpapier-Gattung verfügbar). |
| conid | Die seitens Interactive Brokers für z.B. Optionen oder Future verwendete Contract ID. |
| underlyingSecurityID | Die ISIN des Underlyings (bei z.B. Optionen). |
| transactionID | Die seitens des Brokers verwendete eindeutige ID für die Transaktion. |
| date_from | Eingrenzung auf Trades ab dem jeweiligen Datum (im Format JJJJ-MM-TT). |
| date_to | Eingrenzung auf Trades bis zum jeweiligen Datum (im Format JJJJ-MM-TT). |
| sort_by | Sortierung nach einem bestimmten Feld (standardmäßig erfolgt die Sortierung aufsteigend nach Datum). |
| sort_dir | Sortierrichtung (mögliche Werte: ASC / DESC). |