PayPal-PlugIn ver. 2.1.5 - API-Synchronisation mit CSV-Fusion

veröffentlicht um 14.05.2014, 09:33 von Sebastian Richter
Liebe Hibiscus-Scripting User,

nun ist es endlich so weit. Entgegen der ursprünglichen Planung die PayPal-API erst in der Release 3 zu Verfügung zu stellen hält aus einem plausiblen Grund nun doch schon der Abruf von Transaktionen über die PayPal-API in die Release 2 Einzug.

Vielen Dank auch an dieser Stelle noch einmal an Matthias der auch mit Vertrauen in meine selbstverständliche Diskretion seinen Account zur Entwicklung zu Verfügung gestellt hat und auch wie gewünscht mit getestet hat.

Erster und wichtigster Grund hierfür ist dass dies die beste Lösung für das Problem ist, dass der CSV-Kontoauszug bei gewissen Kunden von PayPal nicht mehr direkt herunter geladen werden konnte und statt dessen später in einem Postkorb hinterlegt wurde.
Aber auch für Benutzer die keine Probleme hatten ist dies nun ein Mehrwert, da bei der Entwicklung (warum auch immer nicht schon früher) aufgefallen ist dass die Umsätze im CSV-Kontoauszug z. B. gravierende Lücken im Verwendungszweck aufwiesen.


Voraussetzungen für eine komfortable Nutzung:
Grundsätzlich wird für eine vollständig kompatible Nutzung der API-Abrufmethode "Jameica ab der Version 2.6.1" und "Hibiscus ab der Version 2.6.5" vorausgesetzt.
Technisch gesehen ist das PlugIn auch fähig diesen Abruf unter früheren Versionen zu tätigen aber die Synchronisierungsoptionen hierfür sind entweder nur eingeschränkt oder gar nicht zugänglich, was dann einiger Kreativität bedarf.



Je mehr die beiden Abrufarten analysiert wurden, des so mehr Ungereimtheiten sind dort untergekommen. Zum Beispiel fällt es auf dass PayPal über die API-Schnittstelle keine detaillierten Zahlungsmethoden mehr zur Verfügung stellt. Zum anderen kann sich der Verwendungszweck einer Buchung unter den Abruf-Methoden unterscheiden da dieser wie schon erwähnt z. B. im CSV-Kontoauszug fehlen könnte. Dies würde natürlich unweigerlich zu Umsatz-Dopplern durch erneuten Abruf führen.
Aus diesem Grunde und allein schon wegen der notwendigen Kompatibilität zu den bisher existierenden Umsätzen in einem Hibiscus-Konto wurde eine Fusions- oder Migrationsmethode umgesetzt die alle guten Eigenschaften der beiden Abrufmethoden miteinander kombinieren soll.
Eine Erläuterung zu den Vor- und Nachteilen der beiden Abrufmethoden findet man in der FAQ für die PayPal-API.
Somit könnte man in gewissen Abständen durch Kombination eines erneuten Komplett-Abrufs und dem Wechsel der Abruf-Methode über die Synchronisierungsoptionen die besehenden Umsätze miteinander fusionieren bzw. migrieren.


Gleich als Tipp vor dem Einsatz kann erwähnt werden dass die notwendigen API-Authentifizierungsdaten (API-Benutzername, API-Passwort und Unterschrift) immer automatisch vom PlugIn abgerufen und in die Konfiguration eingetragen lassen werden können. Hierzu müsste man nur den API-Abruf in den Synchronisierungsoptionen des Hibiscus-Kontos aktivieren und die anderen Felder leer lassen oder falsche Daten eintragen, zum Beispiel den API-Benutzernamen raus löschen. Beim nächsten Abruf wird man dann automatisch gefragt ob man diese Einträge korrigieren lassen möchte.


Zu guter Letzt möchte ich die Möglichkeit erwähnen ein Abruf-Intervall konfigurieren zu können.
Durch Beiträge von Anwendern anderer Homebanking-Programme wurde das Problem angesprochen dass nicht alle Transaktionen über die PayPal-API abgerufen wurden.
Dieses Problem entstand daraus dass man über die PayPal-API pro Abruf- oder Abrufzeitraum maximal 100 Transaktionen zurück geliefert bekommt.
Das Abruf-Intervall ist nun dafür da dass man einen Zeitraum in Stunden angeben kann in dem man selbst der Meinung ist dass bei seinem PayPal-Account maximal 100 Transaktionen anfallen werden.
Wichtig ist hier eben zu erwähnen dass je niedriger dieser Wert eingestellt wird des so länger wird ein Abruf (besonders ein Komplett-Abruf) dauern. Und im Umkehrschluss, je höher der Wert ist umso schneller wird eine Synchronisation ablaufen.
Eine genaue Erläuterung dieses Themas findet man auch in der neuen FAQ für die PayPal-API.




Welche Änderungen und Erweiterungen sich genau ergeben haben, lest ihr wie gewohnt hier weiter unten nach
oder als vollständige ChangeLog in der jeweiligen Version unter Projekt Dateien.
Die relevanten Teile zur neuen Abrufmethode über die PayPal-API aus den vorherigen Versionen der Entwicklung wurden dieses Mal der Vollständigkeit halber noch mit angehängt.


Diese neue Version kann wie immer am besten mit der Installations-Methode #1 (über das Online-Repository) übernommen werden
oder für den manuellen Download und Installation hier auf der Projektseite bezogen werden.



Neuerungen und/oder Änderungen sollten hier vollständig gelesen werden und sind wie folgt:

ver. 2.1.5 (chronologisch von unten nach oben)
  • BUG [140513]: In der Gegenkonto-Kontonummer wird nun nicht mehr "undefined" eingetragen und die richtige Mail-Adresse gesetzt
  • BUG [140511]: Weiterer Check ob die alte Schreibweise "PayPal-Gebuehren" nicht doch schon vorhanden ist um bei einem erneutem Komplett-Abruf Doppler zu vermeiden
  • CHG [140511]: Anpassungen von der Übernahme von Umsatztypen an den CSV-Export der Art "Guthaben-relevante Zahlungen"; Art "Bill" und Status "Canceled" nicht übernehmen
  • BUG [140507]: Zum Vergleich der Gegenkonto-Adresse werden diese automatisch in Kleinbuchstaben formatiert um vermeintliche Unterschiede zu vermeiden und somit die eigene Adresse als Gegenkonto eingetragen wird
  • CHG [140506]: Da die Transaktionen in Ihrer UTC(GMT)-Zeit bei der PayPal-API vorliegen wird dem API-Abrufdatum die Differenz der aktuellen Zeitverschiebung abgezochen um alle Umsätze des ersten Abruftages nach unserer Zeitzone zu erhalten
  • CHG [140506]: Start des Abrufdatum wird bei einem API-Abruf nun auf 00:00 Uhr gesetzt und nicht auf die aktuelle Tageszeit
  • BUG [140506]: Datums-Prüfung beim doppelten DopplerCheck korrigiert
  • BUG [140417]: Fehler beim Auslesen der Details einer Fehlermeldung der API korrigiert; Unter Linux kommt nun keine "StringIndexOutOfBoundsException" mehr
  • NEW [140415]: Übersetzungstabelle für die gängigsten Fehlercodes der PayPal-API eingeführt; Es wird der englische Original-Fehler, Hinweise zur Abrufart und wenn vorhanden eine Übersetzung in einem Info-Fester ausgegeben
  • NEW [140415]: Eingegebenes Datum bei einem Komplett-Abruf wird nun auf Plausibilität überprüft; Somit kann kein fast endloser Abruf mit der API erzeugt werden; Es wird nicht abgebrochen wenn für CSV ein Zeitraum von mehr als zwei Jahren angeben wird
  • CHG [140414]: Anpassungen von der Übernahme von Umsatztypen an den CSV-Export der Art "Guthaben-relevante Zahlungen"; Übersetzung hinzugefügt (Eigenübersetzungen temporär entfernt um fehlende zu erkennen)
  • CHG [140414]: Aktualisierung des Statusbalken im Log-Monitor an den Transaktionsabruf über die PayPal-API angepasst
  • NEW [140413]: Routine zur Einrichtung des API-Abruf; Die API-Zugangsdaten können automatisch beantragt, ausgelesen und eingerichtet werden lassen und der API-Abruf aktiviert werden
    Integriert oder wird angeboten wenn:
    • Im Kontoanlage-Assistenten kann gesetzt werden dass diese beim ersten Login automatisch eingerichtet werden oder gleich manuell eingetragen werden (Von Benutzern von Hibiscus unter Version 2.6.2 ist dies zu verwenden)
    • Wenn das PayPal-Konto auf Kontoauszüge über den Posteingang umgestellt wurde und ein klassischer Abruf über ScreenScrapping und das Herunterladen der CSV nicht mehr möglich ist
    • In den Synchronisierungsoptionen die API-Synchronisierung aktiviert wurde und kein API-Benutzername/Unterschrift oder diese fehlerhaft hinterlegt wurden
  • CHG [140411]: Die Zeitspanne (Intervall) in der maximal 100 Transaktionen bei PayPal vorhanden sein sollten wird automatisch als Standardwert "1000 Std" (= 41,6 Tage) gesetzt, wenn
    vom Benutzer keine gültie Zeitspanne gesetzt wurde (Ganzzahl in Stunden); 1000 Stunden orientieren sich an Privatanwendern, je orientieren der Wert umso länger dauert der Abruf
  • NEW [140410]: Auswerten des API-Response auf Fehlermeldungen; Diese werden aufgrund der Komplexität zuerst in einem Infofenster, im Moment nur auf englisch, ausgegeben
  • CHG [140410]: Übersetzungstabelle für die Felder Umsatzart und Status (Kundenreferenz) erweitert; Durch das Fehlen von Informationen zur Zahlungsart über die API wurde für die Art "Payment" der Eintrag "Zahlung (diverse)" gewählt
  • CHG [140410]: Secure-LogOut für den API-Abruf angepasst; Dieser setzt hier wenn notwendig nur noch das Passwort zurück da es keinen LogOut geben kann
  • CHG [140410]: Eine Fusion oder Migration wird nun auch bei einem Komplett-Abruf durchgeführt wenn die alternative Abrufmethode schon einmal im Einsatz war
  • BUG [140410]: Verbesserungen und Fehlerbeseitigung in den Dopplerchecks und der Fusionsmethode
  • NEW [140410]: Erweiterung bzw. Aktivierung der neuen Sync-Option (sichtbar ab Hibiscus 2.6.2) zum Angeben eines Abruf-Intervalls in Stunden; Somit ist der API-Abruf flexibel einstellbar
    Hintergrund: Die API von PayPal liefert pro TransactionSearch maximal 100 Umsätze. Aus diesem Grund müssen für den Abrufzeitraum mehrere Abrufe in Teilzeiträumen durchgeführt werden.
    Bei anderer Software traten hier Probleme auf da es vorkommen kann dass Benutzer mehr als 100 Transaktionen pro Tag aufweisen und der Abruf aber pro Tag durchgeführt wurde.
    Diese Arbeitsweise wäre aber bei Benutzern mit sehr wenigen Umsätzen (z. B. pro Monat) auch unnötig langsam da jeder Tag einzeln abgerufen werden würde
    Hier wählt man nun den Zeitraum in Stunden für sein PayPal-Konto in dem maximal 100 Transaktionen vorkommen sollten. Dies ergibt zwei herausragende Vorteile:
    1. Benutzer mit sehr vielen Transaktionen (z. B. Geschäftsleute) können den Zeitraum auf unter einen Tag, eben bis auf eine Stunde einstellen und erhalten alle Transaktionen ohne Fehler
    1. Benutzer mit sehr wenigen Transaktionen (z. B. Privatleute) können den Zeitraum recht hoch setzen (z. B. auf 672 Std, wären vier Wochen) und haben somit einen sehr viel schnelleren Abruf
  • CHG [140407]: Weiterer Umsatz-Dopplercheck eingebaut um zu prüfen ob ein Umsatz z. B. schon einmal Fusioniert wurde; Check eindeutig durch Vergleich von PayPal-Transaktionsnummer, Datum und Betrag
  • CHG [140407]: Ein Detailabruf per API wird nun nur noch für den Typ "Payment" durchgeführt da für andere Typen kein "GetTransactionDetails" durchgeführt werden kann (Aus Referenz nicht nachzuvollziehen); Somit schnellerer Abruf
  • CHG [140407]: Transaktionen der Kategorie "Gebührenrückzahlung" und "Wartet temporär" werden bei einem API-Abruf nun nicht mehr im Kontoauszug eingeschlossen; Somit Angleichung an den CSV-Abruf
  • BUG [140407]: Der Kontoanalage-Assistent unterstützt nun auch das Anlegen eines Kontos unter einer Java 8 Umgebung



Die relevanten Teile zur neuen Abrufmethode über die PayPal-API aus den vorherigen Versionen der Entwicklung werden dieses Mal der Vollständigkeit halber noch mit angehängt.

ver. 2.1.4 (chronologisch von unten nach oben)
  • CHG [140404]: Im Fusions- oder Migrationsmechanismus wird nun bei einem Wechsel von API zu CSV auch die Gegenkontonummer (E-Mail) geprüft und korrigiert; Diese könnte im API-Umsatz falsch oder vertauscht sein
  • NEW [140403]: Am Ende der Synchronisierung wird nun auch zusätzlich ausgegeben wie viele Umsätze fusioniert wurden falls ein Wechsel durchgeführt wurde
  • NEW [140403]: Fusions- oder Migrationsmechanismus der bei einem Wechsel zwischen den Abrufarten CSV (ScreenScrapping) und API-Abruf greift und schon vorhandene aber unterschiedliche Buchungen zu einer sauberen Buchung vereint
    >>> Wechsel von CSV- bzw. ScreenScrapping zum API-Abruf:
    • Ein Verwendungszweck der CSV kann aufgrund eines Fehlers bei PayPal entweder ganz fehlen oder falsch mit "Shopping Cart" gesetzt worden sein. Hier wird der meist korrekte API-Verwendungszweck migriert
    • Die meisten Benutzer haben das Feld "Hinweis" im CSV-Kontoauszug nicht aktiviert. Da dieses über die API immer ausgelesen wird, wird diese Notiz als Kommentar in den Umsatz eingefügt
    >>> Wechsel vom API-Abruf zum CSV-Kontoauszug über Screenscrapping:
    • Migrierte Datensätze von einem Wechsel CSV->API werden natürlich in dem besseren Zustand beibehalten
    • Da PayPal über die API keine detaillierten Informationen zu der Zahlungsmethode zu Verfügung stellt welche als Umsatzart eingetragen wird, werden in die API-Umsätze diese zusätzlichen Informationen eingetragen
    • Es gibt einen Fall bei dem im API-Umsatz die E-Mail-Adresse (Business) vertauscht war; Passt API- und CSV-Gegenkontonummer nicht zusammen wird die Information übernommen
    > Beide Migrationsfälle greifen nur bei einem Wechsel der Abrufart über die Synchronisationsoptionen und gelten natürlich nur für schon vorhandene Umsätze
    > Mit einem gleichzeitig durchgeführten Komplettabruf können somit alle Umsätze immer wieder in einen optimalen Zustand gebracht werden; Alle Verwendungszwecke und Zahlungsinformationen zum Beispiel
    > Am Ende der Synchronisierung wird ausgegeben wie viele Umsätze fusioniert wurden
  • CHG [140403]: Dekodieren von BASE64-Zeichenketten im Verwendungsweck eines API-Abrufs; zusätzlich Sicherung falls dieser nicht dekodiert wurde aber ein Zweck aus dem Feld "Subject" gelesen werden kann
  • CHG [140325]: Neue Einstellung in den Synchronisierungsoptionen mit der man steuert ob der API-Abruf aktiviert oder deaktiviert ist; Entscheidung nicht mehr rein über den Benutzernamen (Danke an Olaf)
    Diese Option ist ab Hibiscus 2.6.5 sauber als Checkbox sichtbar und benutzbar; bis Hibiscus 2.6.2 ist dies ein Textfeld in das die Werte "true" oder "false" eingetragen werden können
  • CHG [140320]: Weitere verbesserte Formatierung, Anpassung und parsen von fehlerhaften Teilen der API-Daten und Anpassungen am Kontoauszug; Auskommentieren von nicht verwendeten Spalten
    Der Kontoauszug sollte soweit wie nur möglich dem CSV gleichen um die bestmögliche Variante einer Crossover-Funktion zu gewährleisten (Wechsel zwischen API und ScreenScraping)
    (Leider fehlt z. B. manchmal in der CSV der Verwendungszweck was dann natürlich zu Umsatzdopplern führt; Oder können bei der API keine Bezahlmethoden und andere Felder ausgelesen werden)
  • CHG [140320]: Umrechnung der GMT-Zeit aus dem API-Abruf in die eigentlichen Werte der Zeitzone MEZ bzw. MESZ und Angabe der richtigen Zeitzone im Kontoauszug (hierdurch Dopplervermeidung)
  • CHG [140319]: Erweiterung bzw. Aktivierung der neuen Sync-Option (sichtbar ab Hibiscus 2.6.2) zum Hinterlegen und Ändern des API-Benutzernamen vom eigenen PayPal-Account
    Somit erste Variante für die Möglichkeit jederzeit zwischen ScreenScrapping- und API-Abruf wechseln zu können (Daten hinterlegt oder nicht)
  • NEW [140318]: Berechnung des Zwischensaldo jeder Buchung; Dieser wird gleich beim Abruf berechnet und wie bei der CSV in das Feld 'Guthaben' (im automatischen Kontoauszug) eingetragen
  • BUG [140318]: Neusetzen der Trennzeichen in Beträgen nur beim CSV-Abruf; Format scheint beim API-Abruf schon zu stimmen und ist zu Hibiscus kompatibel
  • BUG [140318]: Erweitern des definieren eines String-Ende um z. B. Namen die das Zeichen '&' enthalten nicht abzutrennen
  • NEW [140318]: Einfügen der ersten Version einer Übersetzungsmatrix; Übersetzung von bisher bekannten Ausdrücken in den Feldern L_NAME, L_TYP und L_STATUS in die deutsche Variante
  • CHG [140317]: Anpassen des automatischen Kontoauszugs vom API-Abruf an den Aufbau des CSV-Kontoauszug; Header wieder entfernt; Trennzeichen ist TAB; somit erster Test von Datenübernahme (Alpha)
  • NEW [140317]: Auslesen des aktuellen Saldo mit der Methode "GetBalance" über API; Eintragen des Datenfeldes in einen automatisch generierten Kontoauszug (ohne Übernahme)
  • NEW [140317]: Auswerten des Detaildatensatz der Methode "GetTransactionDetails" über API; Eintragen der Datenfelder in einen automatisch generierten Kontoauszug (ohne Übernahme)
  • BUG [140317]: Kodierung des Antwortstring und des Decode beim API-Abruf gefixt; Umlaute werden nun korrekt übernommen


ver. 2.1.3 (chronologisch von unten nach oben)
  • NEW [140316]: Auswerten des Hauptdatensatz der Methode "TransactionSearch" über API; Eintragen der Datenfelder in einen automatisch generierten Kontoauszug (ohne Übernahme)
  • NEW [140114]: Erweiterung der Funktion für den Abruf von Transaktionen über die PayPal-API-Schnittstelle; Erster Test-Code für den Abruf von Details zu den erhaltenen Transaktionen


ver. 2.1.2 (chronologisch von unten nach oben)
  • NEW [140110]: Anpassung der Funktion für den Abruf des Kontoauszug; Erster Test-Code für den Abruf von Transaktionen über die PayPal-API-Schnittstelle
  • CHG [140109]: Anpassung der Aufrufe von Hauptfunktionen an die zusätzliche Abrufmethode über die PayPal-API
  • NEW [140109]: Prüfung eingebaut ob bei scheinbarer Verwendung der PayPal-API eine API-Unterschrift hinterlegt wurde um diese dann vom User setzen zu lassen
    Dies ist notwendig da in Hibiscus-Versionen früher als 2.6.2 die API-Unterschrift nicht einfach vom User nachträglich gesetzt werden kann
  • CHG [140109]: Das Script reagiert nun auf die Situation dass ein Kontoauszug aufgrund des Umfangs erst später heruntergeladen werden kann und gibt hierzu einen Info-Dialog aus
  • CHG [140109]: Erweiterung des Kennwort-Eingabedialog um die Anforderung das API-Passwort zum API-Benutzernamen einzugeben
  • CHG [140108]: Erweiterung der Kontoprüfungen von einer E-Mail-Adresse auf zusätzlich einen API-Benutzernamen
  • CHG [140108]: Anpassung des Kontoanlage-Assistenten an die Eingabe eines API-Benutzernamen und einer API-Unterschrift (incl. automatischer Formatierungskorrektur)
  • NEW [140108]: Einbau bzw. Aktivierung einer neuen Sync-Option (sichtbar ab Hibiscus 2.6.2) zum Hinterlegen und Ändern der API-Unterschrift vom eigenen PayPal-Account



Gruß
Comments