PhPepperShop ESRlight Modul

PhPepperShop ESRlight Anbindung Modul Datum: 4. September 2013 Version: 1.8 PhPepperShop ESRlight Modul Anleitung Glarotech GmbH

Inhaltsverzeichnis 1 Einleitung...3 2 Installation...3 2.1 Erste Anmeldung in ESRlight...3 2.2 Systemanforderungen...3 2.3 Dateien kopieren und hochladen...3 2.4 Modulinstallation...4 3 Anmeldung für ESRlight 1...4 4 Konfiguration...5 4.1 Standard Konfigurationsparameter:...5 4.2 Advanced Konfigurationsparameter:...6 5 Administration...7 5.1 Transaktionsidentifikation:...7 5.2 ESRlight Debitorenverwaltung...7 5.3 Logging...7 6 Log-Viewer Installation...8 7 Bedienung...8 7.1 Bestellung im Shop entgegen nehmen...8 7.2 Verwaltung in ESRlight Back-Office...8 8 Hinweis MwSt. Betragsrundung...9 9 Kommunikation ansehen / Debugging...10 10 Hinweis Fälligkeitsdatum...10 11 Kontakt...10 Kontakt leanux AG (ESRlight / SQL-Ledger)...10 Kontakt Glarotech GmbH (PhPepperShop)...10 12 Beispielrechnung mit ESR Einzahlungsschein...11 ESRlight funktioniert nur zusammen mit einem PostFinance Konto. Der Betrieb mit einem Bankkonto ist vorerst nicht vorgesehen. Glarotech GmbH Seite 2 von 11

1 Einleitung Mit diesem externen PhPepperShop Modul können Sie Ihre Debitoren mit viel geringerem Aufwand als bisher bewirtschaften ganz einfach online mit ESRlight Version 1. Sie haben stets die Übersicht über die Zahlungseingänge und brauchen keine ESR-Referenznummern zu erfassen. ESRlight Debitorenverwaltung: PhPepperShop übermittelt Bestellungen (Rechnung, Vorauskasse) automatisch an ESRlight 1 Rechnungen schreiben mit dem jeweiligen Betrag und Rechnungstext Rechnungen mit einem Klick im PDF-Format erstellen und drucken Automatisches Verbuchen der Zahlungseingänge Allfällige Mahnungen per Knopfdruck als PDF-Datei erstellen Auf Wunsch ist das Angebot individuell erweiterbar (kostenpflichtig) Sicher dank verschlüsselter Verbindung 2 Installation 2.1 Erste Anmeldung in ESRlight Vor der Modulinstallation muss man sich bei ESRlight mindestens einmal angemeldet haben. 2.2 Systemanforderungen Um das ESRlight Modul einsetzen zu können, ist mindestens ein PhPepperShop v.3.0 Professional oder Enterprise erforderlich. 2.3 Dateien kopieren und hochladen Das ESRlight Modul besteht im Wesentlichen aus drei Dateien und einem Verzeichnis, welche man in seinen installierten PhPepperShop kopieren muss. Dazu entpackt man zuerst das mitgelieferte ZIP-Archiv. Es sind folgende Dateien enthalten, hier mit den Zielverzeichnissen dargestellt: {shopdir}/shop/esrlight_def.php {shopdir}/shop/esrlight_payment.php {shopdir}/shop/admin/module/esrlight/* Datei Datei Verzeichnis Die Dateien und das Verzeichnis lassen sich einfach via FTP oder SCP zum Webserver hochladen. Der Platzhalter {shopdir} steht dabei für das Shopverzeichnis auf dem Webserver, wo unter anderem die Datei index.php zusammen mit README.txt zu finden ist. Glarotech GmbH Seite 3 von 11

2.4 Modulinstallation Nach dem Kopieren der Dateien kann man in die Shopadministration gehen und dort ins Menü 'Module' > 'Modulverwaltung' wechseln. Auf der linken Seite, bei den noch nicht installierten Modulen, sieht man nun das ESRlight Modul aufgelistet. Abbildung 1: ESRlight Modul wird aufgelistet (angezeigte Module können variieren) Nun muss das ESRlight Modul angewählt werden und auf den 'Installieren' Button geklickt werden. Wenn die Installationsroutine ohne Probleme durchläuft, wird dies auf der darauf folgenden Seite kommuniziert. Das Modul ist nun installiert. Wir klicken nun auf den Button ' Zurück zur Modulverwaltung' und dort 'Zurück zur Moduladministration'. Wir sehen jetzt einen Button für das ESRlight Modul. Wenn man auf diesen Button klickt, erscheint die ESRlight Modulverwaltung. Abbildung 2: ESRlight Modul Verwaltung Auswahlbutton Die Installation des ESRlight Moduls ist nun abgeschlossen. Damit das Modul eingesetzt werden kann, muss das Modul nun noch an die spezifische Konfiguration des Shopbetreibers angepasst werden, siehe dazu nächstes Kapitel. 3 Anmeldung für ESRlight 1 Damit alle hier beschriebenen Schritte durchgeführt werden können, wird davon ausgegangen, dass Sie als Shopbetreiber bereits über einen Account für ESRlight verfügen. Falls das noch nicht der Fall sein sollte, können Sie sich wie folgt registrieren: Senden Sie ein E-Mail mit folgendem Inhalt an folgende Adresse: esrlight@leanux.ch. Firma Vorname Name E-Mail Adresse ESR-Teilnehmer Nr. (erhalten Sie auf Anfrage von der Schweizerischen Post) Glarotech GmbH Seite 4 von 11

MwSt Nr. oder UID (falls vorhanden) Sprache nur wenn eine andere Sprache als Deutsch gewünscht wird Nach der Übermittlung dieser Daten wird für Sie ein ESRlight 1 Account eröffnet. Sie werden via E-Mail über die Eröffnung orientiert und können danach mit der Konfiguration beginnen. Info: Inzwischen hat Leanux AG zusammen mit PostFinance die Version 2 von ESRlight veröffentlicht. Der grosse Unterschied zu Version 1 liegt darin, dass die Artikel im ESRlight verwaltet werden und nicht im Shop, dies ist mit dieser Anbindung nicht verwendbar. Weitere Infos zur Anbindung von ESRlight Version 2 an den PhPepperShop erhalten Sie auf Anfrage direkt bei Leanux AG. Hinweis für Migration von PhPepperShop Kunden mit Aufschaltung von ESRlight 1 vor dem 17. Februar 2012: Siehe folgende URL: http://www.phpeppershop.com/phpeppershop_files/anleitungen_module/esrlight_migration.pdf 4 Konfiguration In der ESRlight Modulverwaltung gibt es folgende Einstellungsmöglichkeiten: Abbildung 3: ESRlight Modul Verwaltung (Administration) 4.1 Standard Konfigurationsparameter: Modul-Aktivierung: Hier ein Häkchen in die Checkbox setzen, wenn die Anbindung an ESRlight aktiviert sein soll. ESRlight für Rechnung verwenden: Wenn aktiviert, werden Bestell- und Kundendaten an ESRlight übermittelt, wenn alle Kriterien erfüllt sind und die Bezahlungsart Rechnung verwendet worden ist. Glarotech GmbH Seite 5 von 11

ESRlight für Vorauskasse verwenden: Wenn aktiviert, werden Bestell- und Kundendaten an ESRlight übermittelt werden, wenn alle Kriterien erfüllt sind und die Bezahlungsart Vorauskasse verwendet worden ist. E-Mail Adresse für Benachrichtigungen: E-Mail Adresse, welche für allfällige ESRlight Modul- Benachrichtigungen dieses Shopsystems verwendet werden. E-Mail, wenn keine ESRlight Notification: ESRlight kann nur über eine Bestellung informiert werden, wenn folgende Kriterien erfüllt sind: Maximal ein MwSt. Satz pro Bestellung (oder keine MwSt.) Währung ist CHF (Schweizer Franken) Es sind keine Kommunikationsfehler mit dem ESRlight Server aufgetreten...wenn dies nicht der Fall ist, wird eine E-Mail abgesendet, falls hier so konfiguriert. ESRlight Hostname: Name des Rechners, wo Ihr ESRlight Mandant installiert ist. Der Standardwert ist hier www.esrlight.ch. Die Einstellung lässt sich auch testen. ESRlight Pfad: Name des Pfads für Ihren ESRlight Zugriff wo sich Ihr Mandant befindet. Der Standardwert ist hier: sql-ledger-peppershop. Dies lässt sich auch testen. ESRlight Login: Der Loginname, welcher für die Anmeldung zu ESRlight verwendet wird. ESRlight Passwort: Das ESRlight Passwort. ESRlight Teilnehmernummer: Diese Teilnehmernummer (Format: xx-xxxxxx-x) erhalten Sie nach der Registrierung von ESRlight zugeteilt. ESRlight Kommunikation loggen: Soll die Kommunikation zwischen diesem PhPepperShop und ESRlight geloggt werden? Dies dient vor allem Nachforschungszwecken. Es können schnell viel Daten anfallen! Mit Hilfe des Log-Viewer Moduls kann das Logfile esrlight_calls.log angeschaut werden. Bitte nur zwecks Debugging aktivieren, da auch Passwörter in den Logs gespeichert werden. Zahlungsfrist in Tagen: Welche Zahlungsfrist wird bei der Neuerstellung eines Kunden hinterlegt. Diese Frist wird initial beim Kunden hinterlegt und erst bei einem Update (erneuter Einkauf eines bestehenden Kunden) aktualisiert. MwSt. Einstellung im Shop: Direktlink zu Mehrwertsteuereinstellungen im PhPepperShop. Wenn die MwSt. deaktiviert ist, wird hier das Menü 'Allgemeine Shopeinstellungen' verlinkt. Wenn MwSt. bereits aktiviert worden ist, so wird hier das aktive MwSt. Menü verlinkt. 4.2 Advanced Konfigurationsparameter: (In einem Datei-Editor in der PHP-Datei via {shop_verzeichnis}/shop/admin/module/esrlight/show_esrlight_admin.php freischaltbar) Die Andvanced Konfigurationsparameter gelten nur für Anbindungen an SQL-Ledger. Aktivierung: Hier ein Häkchen in die Checkbox setzen, wenn die ESRlight als Kreditkarten Handler verwendet werden können soll (nicht implementiert!). Bestellungsidentifikation mit Zeitangabe: Soll die Bestellungsidentifikation (Bestellreferenznummer) um eine Zeitstempel erweitert werden? (Testing / Debugging / Listenübersicht) Interner Pfad: Pfad der aufgerufenen Dateien auf dem ESRlight Server. Wird an den ESRlight-Pfad angehängt. AR-Konto: Konto für offene Posten (z.b. 1100--Debitoren) Glarotech GmbH Seite 6 von 11

AR-Paid1-Konto: Konto für Zahlungseingang (z.b. 1010--{konto_nr}). Hier bitte gut aufpassen. Das System ersetzt während eines Bestelleingangs in dieser Kontobezeichnung den Wert {konto_nr} mit der ESR-Teilnehmernummer. Hier nur etwas ändern, wenn man ganz genau weiss, was man tut. AR-Amount Konto (global): Globales Konto für Verbuchung der verkauften Ware (z.b. 3200--Ertrag) AR-Amount Konto pro Artikel: Falls das Konto zur Verbuchung der gekauften Ware pro Artikel erfolgen soll, kann hier ein Artikelzusatzfeld gewählt werden, in welchem das Konto steht (Fallback: Globales Konto). Bitte beachten! 1. Vor dem Betrieb muss man sich auf www.esrlight.ch mind. einmal angemeldet haben! 2. ESRlight verarbeitet pro Bestellung maximal 10 Positionen. Sobald in einer Shopbestellung mehr Positionen oder Rabatte definiert sind, werden alle überzähligen Positionen in eine einzelne zusammengefasst. 3. Die PhPepperShop Anbindung an ESRlight prüft vor der Übergabe der Daten einer Bestellung viele Details der für ESRlight aufbereiteten Parameter. Sollte etwas nicht mit erwarteten Werten übereinstimmen wird die Bestellung NICHT an ESRlight übermittelt und es wird ein Fehler an die angegebene E-Mail Adresse versendet. Diese Bestellung muss der Shopbetreiber dann gegebenenfalls manuell eintragen. Somit ist weitestgehend sichergestellt, dass keine falschen Bestelldaten in Rechnung gestellt werden. Nachdem die Angaben entsprechend konfiguriert wurden, sollte man sicherstellen, dass diese gespeichert worden sind. 5 Administration 5.1 Transaktionsidentifikation: Bei einer via ESRlight bezahlten Bestellung wird im Kundenmanagement zu jeder ESRlight Bestellung eine Infoanzeige hinter der Bezahlungsart gehängt: Abbildung 4: Kundenmanagement Bestellungsdarstellung 5.2 ESRlight Debitorenverwaltung ESRlight bietet die Loginmöglichkeit direkt auf der ESRlight Webseite an: http://www.esrlight.ch/ 5.3 Logging Der PhPepperShop kann alle Aufrufe die er ans ESRlight System absetzt loggen. Das entsprechende Logfile lautet esrlight_calls.log und kann via Log-Viewer (Modul) eingesehen werden (Shop-Administration Externe PhPepperShop Module Log-Viewer). Der Logging-Mechanismen kann über die Einstellung 'ESRlight Kommunikation loggen' gesteuert werden (ESRlight Verwaltung in Shop-Administration). Glarotech GmbH Seite 7 von 11

6 Log-Viewer Installation Bevor man die vom ESRlight Modul erzeugten Log-Dateien sehen kann, müssen wir noch das externe PhPepperShop Modul 'Log-Viewer' installieren, falls dieses Modul nicht schon installiert ist. Dies funktioniert analog wie die Modulinstallation des ESRlight Moduls. Wir klicken in der Shop-Administration auf den Punkt 'Module' > 'Modulverwaltung' und dort auf den Button, der mit PhPepperShop Modulverwaltung betitelt ist. Hier klicken wir im linken Fenster auf 'Log Viewer' und unten dran auf den Button 'Installieren'. Wir bestätigen den Verlauf der Installation mit Klick auf den Button 'Zurück zur Modulverwaltung'. Nach der Installation des Log-Viewers erscheint dieser nun im rechten Fenster, welches die installierten Module anzeigt. Wenn wir im rechten Fenster auf benutzen klicken, können wir die vorhandenen Log- Dateien sehen. 7 Bedienung 7.1 Bestellung im Shop entgegen nehmen Kundenseitig ist die Bedienung relativ einfach. Der Kunde bestellt im Shop ganz normal und bemerkt von der ESRlight Anbindung gar nichts. Ablauf der Anbindung im Shop: 1. Der Kunde legt sich Artikel in den Warenkorb und geht zur Kasse im Shop 2. Er wählt eine mit ESRlight verknüpfte Bezahlungsart z.b. Rechnung und akzeptiert die AGB 3. Der Shop schliesst die Bestellung ab und sendet dem Kunden und Shopbetreiber ein Bestellbestätigungs E-Mail. 4. Weiter werden die Kundendaten zu ESRlight übermittelt. (Falls der Kunde mit angegebener Kundennummer dort schon existiert, führt dies nicht zu einer Dublette) 5. Nun übermittelt der Shop die Bestellung in Form einzelner Artikel- und Zusatzpositionen und eröffnet in ESRlight eine neue, offene Rechnung. Ablauf im ESRlight Back-Office: 1. Offene Rechnungen durchschauen und Rechnungen (ESR-Einzahlungsscheine) drucken. 2. Periodisch über Import mit dem Postkonto abgleichen (eingegangene Zahlungen erfassen) 3. Gegebenenfalls Mahnungen versenden 7.2 Verwaltung in ESRlight Back-Office Die Verwaltung der offenen Posten in ESRlight kann man den Anleitungen auf folgender Webseite entnehmen: https://www.esrlight.ch/postportal/anleitungen.phtml Glarotech GmbH Seite 8 von 11

x Abbildung 5: Beispielansicht einer aus dem Shop übermittelten, offenen Rechnung 30 Abbildung 6: Ansicht eines aus dem Shop übermittelten Kundendatensatzes 8 Hinweis MwSt. Betragsrundung Im PhPepperShop werden die Beträge intern mit maximaler Genauigkeit berechnet und erst das Gesamttotal mit dem pro Währung definierbaren Rundungsfaktor (CHF = 0.05) gerundet. ESRlight unterstützt nur einen MwSt. Betrag. Dieser MwSt. Betrag wird bei ESRlight auf 5 Rappen gerundet, das Gesamttotal hingegen nicht mehr. Damit keine einzubezahlenden Beträge entstehen, welche nicht auf CHF x.x0 oder CHF x.x5 Rappen enden, übermittelt der PhPepperShop deshalb bei Bedarf einen um die Differenz angepassten MwSt. Betrag an ESRlight, was zu einem maximalen Unterschied von CHF 0.02 gegenüber dem im Shop aufgeführten MwSt. Betrag führen kann. Der zu verrechnende Totalbetrag wird übereinstimmen. Wenn Sie sich bei ESRlight in der 'Ausgangsbuchung bearbeiten'-maske befinden (Detailansicht einer Rechnung) und dort auf den Button 'Erneuern' klicken, so berechnet ESRlight die Bestellung anhand der eigenen Berechnungs- und Rundungsregeln (siehe Absatz weiter oben), was wiederum in einem anderen Total anstatt dem vom Shop an den Kunden kommunizierten Betrag resultieren kann (max. CHF 0.02 Differenz). Falls der 'Erneuern'-Button geklicket worden ist, einfach die Ansicht schliessen und nochmals öffnen, dann zeigt ESRlight wieder die vom Shop berechneten Werte an. Glarotech GmbH Seite 9 von 11

9 Kommunikation ansehen / Debugging Debugging der Kommunikation (erfordert PHP-Kenntnisse): Falls die Analyse des Kommunikationslogs nicht ausreicht, kann man in der Datei {shop_verzeichnis}/shop/config.inc.php beim Punkt 'DEBUG_ONLY_ON_HOST' die eigene IP-Adresse eintragen und in der Datei {shop_verzeichnis}/ shop/esrlight_api.def.php die public Membervariable 'show_http_requests' temporär auf true stellen. Jetzt sieht man vom angegebenen Rechner aus beim Bestellabschluss alle Kommunikationsdaten mit ESRlight (Anfrageparameter und Antwortseiten). Bitte beachten Sie, dass es bei Anpassungen am Sourcecode kein Support von Glarotech GmbH und leanux AG gibt und darauf resultierende Probleme in Rechnung gestellt werden müssen. 10 Hinweis Fälligkeitsdatum Erste ESRlight Modulversionen berechnen das Fälligkeitsdatum erst nach Klick auf 'Erneuern'. 11 Kontakt Kontakt leanux AG (ESRlight / SQL-Ledger) leanux.ch AG Tel: 044 947 11 22 Industriestrasse 25 Fax: 044 947 11 33 CH-8604 Volketswil E-Mail: info@leanux.ch Web: http://www.esrlight.ch/ Kontakt Glarotech GmbH (PhPepperShop) Glarotech GmbH Tel: 071 923 08 58 Toggenburgerstrasse 156 Fax: 071 923 08 59 CH-9500 Wil E-Mail: info@glarotech.ch Web: http://www.phpeppershop.com/ Glarotech GmbH Seite 10 von 11

12 Beispielrechnung mit ESR Einzahlungsschein Abbildung 7: Beispiel einer aus ESRlight generierten Rechnung mit ESR-Einzahlungsschein Die hier abgebildete Beispiel Rechnung wurde in ESRlight generiert. Diese wird einfach auf ein spezielles Papier mit perforiertem ESR-Einzahlungsschein Teil gedruckt und dem Kunden per Briefpost zugestellt. Beim Drucken bitte darauf achten, dass keine Auto-Grössenanpassung läuft. Glarotech GmbH Seite 11 von 11