FAQ / Hilfe‎ > ‎

FAQ und Hilfe zur PayPal-API und zur Wechselarbeit mit CSV - API



iGraal - Geld zurück bei über 1500 Shops, garantiert und sicher

Beantragen einer PayPal API-Berechtigung

(Tipp: das PayPal-PlugIn kann für Sie diese Schritte übernehmen wenn Sie nur die API-Synchronisierung unter den Synchronisierungsoptionen aktivieren und den Rest frei lassen)

Sollten Sie bisher noch nie die API-Berechtigung von PayPal genutzt haben und somit noch kein API-Signatur beantragt haben, folgen Sie nun bitte diesen Schritten.


  • Nun navigieren Sie bitte über das Hauptmenü von PayPal über den Punkt
Vorgehensweise auf der neuen PayPal-Homepage: (bei klassischer Ansicht einfach überspringen)
  • Auf der neuen PayPal-Homepage befinden Sie sich auf einer neuen Startseite (gleich im richtigen Bereich "Übersicht")
    (ansonsten wird folgend beschrieben wie auf der klassischen Seite vorgegangen wird)
Dann scrollen Sie runter bis zum Abschnitt "Verkaufen mit PayPal" und wählen "Verkäufereinstellungen"

Alternativ: Auf der klassischen PayPal-Homepage klicken Sie zunächst unter "MeinKonto" auf "Mein Profil"
(beim neuen Design ist dies nicht notwendig)
und dann auf
Verkäufer/Händler (Kaufabwicklung, APIs, eBay...)


weiter gehts bei beiden
API-Zugriff --> Aktualisieren

  • Im nächsten Schritt können Sie Ihre "API-Berechtigung anfordern"
    (sollte hier eine andere Seite erscheinen mit dem Inhalt "API-Signatur anzeigen" hatten Sie schon einmal Ihre API-Berechtigung angefordert und können diesen Punkt betätigen)

Für den Abruf mit Hibiscus wird eine sogenannte "API-Signatur" benötigt
Daher "Fordern Sie eine API-Signatur an" und lassen Sie diese über "Zustimmen und senden" gleich anzeigen



  • Gleich auf der nächsten Seite werden Ihnen nun Ihre notwendigen Daten der API-Signatur angezeigt
    • API-Benutzername
    • API-Passwort
    • Unterschrift







iGraal - Geld zurück bei über 1500 Shops, garantiert und sicher





Anzeigen der API-Signatur (API-Benutzernamen, API-Passwort und Unterschrift)

(Tipp: das PayPal-PlugIn kann für Sie diese Schritte übernehmen wenn Sie nur die API-Synchronisierung unter den Synchronisierungsoptionen aktivieren und den Rest frei lassen)


Sollten Sie schon einmal die API-Berechtigung von PayPal genutzt haben und eine API-Signatur beantragt haben, folgen Sie nun bitte diesen Schritten um diese anzuzeigen.

  1. Bitte loggen Sie sich mit Ihrer E-Mail-Adresse und Ihrem PayPal-Passwort unter https://www.paypal.com ein

  2. Nun navigieren Sie bitte über das Hauptmenü von PayPal über den Punkt

    • Vorgehensweise auf der neuen PayPal-Homepage: (bei klassischer Ansicht einfach überspringen)
      • Auf der neuen PayPal-Homepage befinden Sie sich auf einer neuen Startseite (gleich im richtigen Bereich "Übersicht")
        (ansonsten wird folgend beschrieben wie auf der klassischen Seite vorgegangen wird)
      Dann scrollen Sie runter bis zum Abschnitt "Verkaufen mit PayPal" und wählen "Verkäufereinstellungen"

      Alternativ: Auf der klassischen PayPal-Homepage klicken Sie zunächst unter "MeinKonto" auf "Mein Profil"
      (beim neuen Design ist dies nicht notwendig)
      und dann auf
      Verkäufer/Händler (Kaufabwicklung, APIs, eBay...)


      weiter gehts bei beiden
      API-Zugriff --> Aktualisieren


  3. Im nächsten Schritt können Sie Ihre "API-Signatur anzeigen" lassen
    (sollte hier eine andere Seite erscheinen mit dem Inhalt "API-Berechtigung anfordern" haben Sie bisher noch keine API-Berechtigung angefordert und müssen diese zunächst wie im vorherigen Hauptpunkt dieser Seite beschrieben einrichten bzw. beantragen)

  4. Gleich auf der nächsten Seite werden Ihnen nun Ihre notwendigen Daten der API-Signatur angezeigt
    • API-Benutzername
    • API-Passwort
    • Unterschrift







iGraal - Geld zurück bei über 1500 Shops, garantiert und sicher




API-Signaturdaten (API-Benutzername und API-Unterschrift) in Hibiscus eintragen

(Tipp: das PayPal-PlugIn kann für Sie diese Schritte übernehmen wenn Sie nur die API-Synchronisierung unter den Synchronisierungsoptionen aktivieren und den Rest frei lassen,
dies kann übrigens auch genutzt werden um sein zurück gesetzes Passwort wieder zu hinterlegen, ohne es selbst setzen zu müssen; Einfach z. B. den Benutzernamen entfernen)


  1. Wechseln Sie in Hibiscus in die Datailansicht Ihres PayPal-Kontos bei dem der API-Abruf eingerichtet werden soll

  2. Öffnen Sie über den entsprechenden Button die Synchronisierungsoptionen für dieses Konto

  3. Kopieren Sie nun Ihre API-Signaturdaten in die entsprechenden Felder und bestätigen Sie diese mit "Übernehmen"
    (Tipp: Kopieren können Sie ganz einfach wenn Sie den jeweiligen Abschnitt auf der PayPal-Homepage markieren,
    dann Strg+C zum kopieren drücken,
    zum entsprechenden Feld in Hibiscus wechseln
    und dort Strg+V zum Einfügen drücken)

    • Den API-Benutzernamen finden Sie wie im Hauptpunkt Nummer 2 beschrieben (dieser muss ein "_api" enthalten!)
    • Die API-Unterschrift finden Sie ebenfalls wie im Hauptpunkt Nummer 2 beschrieben
    • Das API-Abrufintervall wird in ganzen Stunden angeben und stellt den Zeitraum dar in dem maximal 100 Transaktionen bei PayPal aufgetreten sind
      Je kleiner dieser Wert ist des so länger dauert ein Abruf und je größer der Wert gewählt wird des so schneller wird ein Abruf durchgeführt.
      Sollten Sie keinen oder einen ungültigen Wert eintragen wird automatisch ein Standardwert von 1000 Stunden gesetzt. Dies entspricht 41,6 Tage. Somit sollten bei diesem Beispiel in einem Zeitraum von ca. einem Monat und zehn Tagen in Ihrem PayPal-Account nicht mehr als 100 Transaktionen angefallen sein
    • Mit der letzten Option "API-Synchronisation" können Sie den API-Abruf aktivieren oder durch deaktivieren auf die klassische Abruf-Methode über "ScreenScrapping" wechseln bei der ein Kontoauszug als CSV-Export herunter geladen wird






iGraal - Geld zurück bei über 1500 Shops, garantiert und sicher




Erläuterung des API-Abrufintervalls

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.


Fall-Beispiel der zu diesen Problemen führte:

Nun treten zum Beispiel bei einer Privatperson angenommen 100 Transaktionen in drei Monaten auf und bei einem Unternehmen angenommen 100 Transaktionen in der Woche.

Die Homebanking-Software muss natürlich mit dem kleinsten Zeitraum der möglichen Fälle arbeiten um beide zu unterstützen. Da aber ein Unternehmen natürlich auch mehr als 100 Transaktionen pro Woche produzieren kann wurde dort von der Entwicklung ein fester Abrufzeitraum von einem Tag umgesetzt.

Es wird also für jeden einzelnen Tag ein API-Abruf ausgeführt.

Was ist nun aber wenn ein Unternehmen oder auch eine Privatperson mal über 100 Transaktionen an einem Tag aufweist, zum Beispiel wegen dem Weihnachtsgeschäft?! Es würden alle darüber hinausgehenden Transaktionen nicht abgerufen werden.

Zudem entsteht der Umstand dass auch bei den Privatpersonen die angenommen doch eigentlich nur 100 Transaktionen in Monaten aufweisen, diese dennoch einen sehr lange Abrufphase haben da dennoch jeder einzelne Tag für sich selbst abgerufen wird.


Hier soll das flexibel einstellbare Abruf-Intervall in Hibiscus beide Seiten zufrieden stellen und nur die Vorteile nutzen:

Das Abrufintervall wird in Stunden definiert und kann somit auf unter eine Tag, bis eben auf eine Stunde (in der 100 Transaktionen auftreten können eingestellt) oder auf zum Beispiel 1000 Stunden gestellt werden was einen Zeitraum von 41,6 entspricht.

Fall-Beispiele:

 Privatanwender:  alle sechs Monate kommen nicht mehr als
 100 Transaktionen zu Stande
 das Abrufintervall wird hier auf ca. 4.032 Stunden gestellt
 (24 Std * 7 Tage * 4 Wochen * 6 Monate)
 kleines Unternehmen:
 hier werden nicht mehr als 100
 Transaktionen in einer Woche anfallen
 das Abrufintervall wird hier auf ca. 168 Stunden gestellt
 (24 Std * 7 Tage)
 großes Unternehmen:
 es kommt sehr oft vor dass an einem Tag
 mehr als 100 Transaktionen anfallen
 das Abrufintervall wird auf unter 24 Stunden eingestellt
 (je nachdem in wie viel Stunden 100 Transaktionen anfallen)

Sollte das Abruf-Intervall zu hoch eingestellt sein und in einem Zeitraum des Abrufs doch überraschend mehr Transaktionen als erwartet anfallen wird eine Fehlermeldung ausgeben:

Fehler-Code: 11002: The number of results were truncated. Please change your search parameters if you wish to see all your results.

Hibiscus bricht bei dieser Meldung ab da es gewollt ist dass alle Umsätze bzw. Transaktionen abgerufen werden. Da es sich hier lediglich um eine Warnmeldung von PayPal handelt kann es vorkommen dass eine andere Homebanking-Software dies nicht als Fehler meldet und normal weiter arbeitet, dann aber Transaktionen fehlen und somit eine Lücke entsteht. Bei Hibiscus wollen wir dies nicht.

Abhilfe schafft hier dann das Herabsetzen des Abruf-Intervalls.

Es muss hierbei aber immer beachtet werden dass je niedriger das Abruf-Intervall gesetzt wird des so länger dauert der Datenabruf da der Abrufzeitraum immer in Abschnitte so groß wie das Abrufintervall aufgeteilt wird.


Beispiel eines Abrufs von einem Zeitraum von einem Jahr mit einem Abruf-Intervall von 1000 Stunden:

Abrufdatum: 31.12.2013 es wird also der Zeitraum von 01.01.2013 bis 31.12.2013 abgerufen.

Dies löst nun eine Transaktionssuche aus in dem der Abrufzeitraum in 41,6 Tage Abschnitte aufgeteilt wird:

von 01.01.2013 00:00:00  bis  11.02.2013 16:00:00
von 11.02.2013 16:00:00  bis  25.03.2013 08:00:00
von 11.02.2013 16:00:00  bis  25.03.2013 08:00:00
....... usw ......
von 11.01.2014 00:00:00  bis  21.02.2014 16:00:00
von 21.02.2014 16:00:00  bis  04.04.2014 09:00:00
von 04.04.2014 09:00:00  bis  15.04.2014 12:01:22

Insgesamt werden hier '12' Zeiträume abgerufen.

Stellt man nun das Stundenintervall auf z. B. 10 herab, dauert der Abruf 100x so lange da dem entsprechend mehr Abschnitte entstehen.

In diesem Beispiel würde ein Abruf von einem Jahr mit relativ wenigen Umsätzen und einem Abruf-Intervall von 10 Std. ungefähr 20 Minuten dauern da ca. 878 Abschnitte abzurufen wären.
Für zwei Jahre verdoppeln sich hier natürlich die Werte usw.

Daher bedeutet dies immer dass ein Komplett-Abruf bis zu zwei Jahren mit der klassischen Methode sehr wahrscheinlich schneller ist.





iGraal - Geld zurück bei über 1500 Shops, garantiert und sicher






Vor- und Nachteile von API und CSV gegenüber gestellt

Jede dieser beiden Abrufarten hat Ihre Vor- und auch Ihre Nachteile. 

Gleich zu Anfang kann als Tipp erwähnt werden dass ein Wechsel zwischen diesen beiden Abrufarten in Hibiscus jederzeit möglich ist da eine "Fusions- und Migrationsmethode" umgesetzt wurde die alle fehlerfreien Daten beider Abruf-Methoden in einer Umsatz-Liste miteinander vereint.

Es ist also sogar möglich z. B. einmal im Monat durch Kombination des "zurück setzten des Saldo und Datum des Kontos" und dem Wechsel der Abruf-Methode über die Synchronisierungsoptionen, einen neuen Komplett-Abruf zu starten. Warum dies sinnvoll sein kann wird Ihnen in der folgenden Tabelle aufgezeigt.


Um die Unterschiede und somit den Gewinner in der jeweiligen Kategorie auf den ersten Blick deutlich darzustellen werden

Vorteile grün dargestellt
Nachteile werden rot hinterlegt

   Klassisch
(CSV-Export über ScreenScrapping)
 API-Abruf
(Transaktionssuche über eine Schnittstelle)
 
 Abrufzeitraum  maximal die letzten zwei Jahre
 keine Einschränkung bekannt
 
 Dauer eines Komplett-Abruf
 (zwei Jahre mit ca. 125 Transaktionen)
 ca. 30 Sekunden
(inklusive Login und Logout auf der Homepage)
ca. 135 Sekunden
(mit einem Abruf-Intervall von 1000 Std)
 
 Dauer eines Aktualisierungsabruf
 
(zwei Wochen mit wenigen Transaktionen)
 ca. 20 Sekunden
(inklusive Login und Logout auf der Homepage)
 ca. 5 Sekunden
(mit einem Abruf-Intervall von 1000 Std)
 sollten sehr viele
 Transaktionen vorhanden
 sein wäre der CSV-Abruf
 vermutlich schneller
 Vollständigkeit der Transaktionen
 keine fehlenden Transaktionen aufgefallen
 sehr vereinzelt kann eine Transaktion fehlen
die aber im CSV-Auszug vorhanden ist
 
 Vollständigkeit der Daten einer
 Transaktion
 Durch Fehler bei PayPal kommt es regelmäßig vor dass der Verwendungszweck leer oder stattdessen der Text "Shopping Cart" eingetragen ist
Über die API werden keine Abrechnungsinformationen geliefert (Umsatzart) und die E-Mail-Adresse des Gegenkontos kann abweichen
 beide können somit keine
 lückenlosen Daten liefern,
 womit eine Kombination
 sinnvoll erscheint
 




iGraal - Geld zurück bei über 1500 Shops, garantiert und sicher






Erläuterung der Fusions- bzw. Migrationsmethode von Umsätzen (CSV<->API)

Wie in den Vor- und Nachteilen der beiden Abruf-Methoden (Klassisch als CSV-Export mittels ScreenScrapping oder über die PayPal API-Schnittstelle) beschrieben können sich die gelieferten Umsätze der beiden aufgrund von fehlenden oder fehlerhaften Daten doch ziemlich Unterscheiden.

Nun ist es in Hibiscus aber wie immer das Ziel eine sauberen Abruf mit hoher Kompatibilität zu gewährleisten ohne dass eben z. B. bei einem Wechsel der Abruf-Methode viele Umsatz-Doppler entstehen da sich die Umsätze ja eigentlich unterscheiden könnten.

Das PayPal-PlugIn merkt sich hier nun also ob eine Abruf-Methode schon einmal verwendet wurde um später in zwei Situationen eine Fusion bzw. Migration von vorhandenen Umsätzen mit den neu abgerufenen Umsätzen durchzuführen. Dieser Vorgang wird gestartet wenn:

  • Ein Wechsel von einer Abruf-Methode auf die andere statt findet (Aktivieren oder Deaktivieren der API-Synchronisation)
  • Ein erneuter Komplett-Abruf angestoßen wurde und vor der aktuell verwendeten Abruf-Methode schon einmal die alternative Abruf-Methode eingesetzt wurde


Hier wird nun dargestellt was dies bedeutet, was passiert bei einer Fusion/Migration:

Szenario #1:

Im Moment verwendete Abruf-Methode: Klassisch als CSV-Export mittels ScreenScrapping
Wechsel auf alternative Abruf-Methode: PayPal API-Schnittstelle

oder

Es wird ein erneuter Komplett-Abruf gestartet und ein Abrufzeitraum gewählt in dem Umsätze vorkommen die mit der alternativen Abruf-Methode übernommen wurden

früher schon einmal verwendete Abruf-Methode (Alternative): Klassisch als CSV-Export mittels ScreenScrapping
Im Moment verwendete Abruf-Methode: PayPal API-Schnittstelle

bisher vorhandener CSV-Umsatz  
abgerufener API-Umsatz der dem CSV-Umsatz entsprechen sollte
Ergebnis der Fusion/Migration
Vorgang
 Datum:
 15.01.2014
 Datum:
 15.01.2014
 Datum:
 15.01.2014
Daten sind hier mit CSV-Umsatz immer identisch, nichts zu tun
 Betrag:
 5,41 EUR
 Betrag:
 5,41 EUR
 Betrag:
 5,41 EUR
Daten sind hier mit CSV-Umsatz immer identisch, nichts zu tun
 Art der Buchung:
 Zahlung für Expresskaufabwicklung gesendet

 Art der Buchung:
 Zahlung (diverse)
 Art der Buchung:
 Zahlung für Expresskaufabwicklung gesendet
der hier zu allgemeine Wert wurde nicht in den CSV-Umsatz übernommen
 Status (Kundenreferenz):
 Abgeschlossen
 Status (Kundenreferenz):
 Abgeschlossen
 Status (Kundenreferenz):
 Abgeschlossen
 durch eine Übersetzungstabelle sind
 die gängigsten Werte gleich
 TransaktionsID (Primanota-Kennzeichen):
 9TR657546HD71724B
 TransaktionsID (Primanota-Kennzeichen):
 9TR657546HD71724B
 TransaktionsID (Primanota-Kennzeichen):
 9TR657546HD71724B
Daten sind hier mit CSV-Umsatz immer identisch, nichts zu tun
 Verwendungszweck: (kann auch leer sein)
 Shopping Cart

 Verwendungszweck:
 Arabica 1 kg ganze Bohne x3, Havannah 250 g

 Verwendungszweck:
 Arabica 1 kg ganze Bohne x3, Havannah 250 g
der hier falsche Wert im CSV-Umsatz wurde durch den API-Wert ersetzt

als zusätzlichen Sonderfall wird hier das Feld Notiz (im CSV-Kontoauszug "Hinweis") in das Hibiscus-Feld "Kommentar" eingetragen, falls dieses bisher im CSV-Kontoauszug nicht aktiviert war und somit beim klassischen Abruf als CSV-Export nicht mit übernommen wurde. (Tipp: Im PayPal-Konto die "Felder des herunter ladbaren Kontoauszug" um das Feld "Hinweis" erweitern)
 Notiz/Kommentar/Hinweis:
 

 Notiz/Kommentar/Hinweis:
 Versand erfolgt wie immer mit unserem
 Dienstleister. Die MwSt. ist im Preis enthalten

 Notiz/Kommentar/Hinweis:
 Versand erfolgt wie immer mit unserem
 Dienstleister. Die MwSt. ist im Preis enthalten
der hier eventuell nicht aktivierte und somit leere Wert im CSV-Umsatz wurde durch den API-Wert ersetzt



Szenario #2:

Im Moment verwendete Abruf-Methode: PayPal API-Schnittstelle
Wechsel auf alternative Abruf-Methode: Klassisch als CSV-Export mittels ScreenScrapping

oder

Es wird ein erneuter Komplett-Abruf gestartet und ein Abrufzeitraum gewählt in dem Umsätze vorkommen die mit der alternativen Abruf-Methode übernommen wurden

früher schon einmal verwendete Abruf-Methode (Alternative): PayPal API-Schnittstelle
Im Moment verwendete Abruf-Methode: Klassisch als CSV-Export mittels ScreenScrapping

bisher vorhandener API-Umsatz   abgerufener CSV-Umsatz der dem API-Umsatz entsprechen sollte
Ergebnis der Fusion/Migration
Vorgang
 Datum:
 17.01.2014
 Datum:
 17.01.2014
 Datum:
 17.01.2014
Daten sind hier mit API-Umsatz immer identisch, nichts zu tun
 Betrag:
 6,82 EUR
 Betrag:
 6,82 EUR
 Betrag:
 6,82 EUR
Daten sind hier mit API-Umsatz immer identisch, nichts zu tun
 Art der Buchung:
 Zahlung (diverse)
 Art der Buchung:
 Zahlung für Expresskaufabwicklung gesendet
 Art der Buchung:
 Zahlung für Expresskaufabwicklung gesendet
der hier falsche Wert im API-Umsatz wurde durch den CSV-Wert ersetzt
 Status (Kundenreferenz):
 Abgeschlossen
 Status (Kundenreferenz):
 Abgeschlossen
 Status (Kundenreferenz):
 Abgeschlossen
 durch eine Übersetzungstabelle sind
 die gängigsten Werte gleich
 TransaktionsID (Primanota-Kennzeichen):
 0TR657548HX71724R
 TransaktionsID (Primanota-Kennzeichen):
 0TR657548HX71724R
 TransaktionsID (Primanota-Kennzeichen):
 0TR657548HX71724R
Daten sind hier mit API-Umsatz immer identisch, nichts zu tun
 Verwendungszweck:
 Turnschuhe gr. 42, Socken gr. 42
 Verwendungszweck: (kann auch leer sein)
 Shopping Cart

 Verwendungszweck:
 Turnschuhe gr. 42, Socken gr. 42
der hier falsche Wert im CSV-Umsatz wurde nicht übernommen


Tipp: aufgrund dieser Beispiele scheint es sinnvoll in gewissen Abständen durch Kombination eines erneuten Komplett-Abrufs und dem Wechsel der Abruf-Methode über die Synchronisierungsoptionen die besehenden Umsätze miteinander zu fusionieren bzw. zu migrieren. Die Abruf-Methode kann dann sofort wieder auf die gewünschte zurück gestellt werden.



iGraal - Geld zurück bei über 1500 Shops, garantiert und sicher