PickPost und My Post 24

Webservice «PickPost und My Post 24»
inkl. Kartenapplikation «Standortsuche»
Handbuch für die Integration
Webservice «PickPost und My Post 24», Version 3
Standortsuche im Responsive Design
März 2016
1
Inhaltsverzeichnis
1
Einleitung
4
1.1
An wen richtet sich dieses Handbuch?
4
1.2
Wie ist dieses Handbuch aufgebaut?
4
1.3
Gültigkeit
4
1.4
Kosten
4
1.5
Nutzungsbedingungen
4
1.6
Teilnahmebedingungen
4
2
Ablauf der PickPost / My Post 24-Integration und Support
5
2.1 Anmeldung und Aufschaltung
5
2.1.1 Aktivieren des Webservices «PickPost und My Post 24»5
2.2 Support bei der Integration und bei Problemen
5
2.2.1 Unterstützung bei der Integration5
2.2.2 Systemunterbrüche und Fehlermeldungen5
3
Beispiele von PickPost / My Post 24-Integration
6
3.1 Die technischen Systeme kurz erklärt
6
3.1.1 Webservice «PickPost und My Post 24»6
3.2
PickPost- oder My Post 24-Standorte
3.3
Bestellerfassung
12
3.4
Bestellmaske online und Bestellschein
12
3.5
Gestaltungsvorgaben (Layout)
13
7
3.5.1 Postlogo13
3.5.2 PickPost / My Post 24 Icons14
3.5.3Einbindung
15
3.6
Datenschutz
16
4
Technische Informationen und Anleitungen
17
4.1 Webservice «PickPost und My Post 24»
17
4.1.1 Übertragungsprotokoll17
4.1.2 Authentifizierungsmechanismus17
4.1.3 Endpunkt-Adresse des Webservices «PickPost und My Post 24» V317
4.1.4 Dienstleistungsbeschreibung17
4.1.5 Operation «FindCustomerPickPostNumberRequest»17
4.1.6 Antwort «FindCustomerPickPostNumberRequest»18
4.1.7 Integrierte Fehlermeldung18
4.1.8 Struktur des Webservices «PickPost und My Post 24»19
2
4.2 Integration der Kartenapplikation «Standortsuche»
22
4.2.1 Aufbau und Design der neuen Standortsuche22
4.2.2 Aufbau für die Einbindung der Standortsuche25
4.2.3 Technische Einbindung im HTML-Code25
4.2.4 Adressierung übernehmen27
4.2.5 URL Parameter28
4.2.6 URL Encoding29
4.2.7 Abschliessende Bemerkungen29
4.2.8 Anmeldeformular für die Integration der Kartenapplikation «Standortsuche»30
4.3 PickPost- oder My Post 24-Standorte-Datei
31
4.3.1 Allgemeine Beschreibung31
4.3.2 Aktualisierungen31
4.3.3 Dateiname31
4.3.4 PickPost- oder My Post 24-Standorte-Liste im XML-Format31
4.3.5 Prüfschema zum XML-File der PickPost- oder My Post 24-Standorte-Liste31
4.3.6 Übermittlungseinstellungen31
4.3.7 Aktualisierungen der PickPost- oder My Post 24-Standorte-Datei31
4.3.8 Dateistruktur PickPost- oder My Post 24-Standorte-Datei31
4.3.9 Download der Daten der PickPost- oder My Post 24-Standorte-Datei34
4.3.10Verwendung der Daten der PickPost- oder My Post 24-Standorte-Datei34
4.3.11Beispiele35
5
Links
37
3
1Einleitung
1.1 An wen richtet sich dieses Handbuch?
1.3Gültigkeit
Dieses Handbuch haben Sie von Ihrer Kundenberaterin oder
Ihrem Kundenberater erhalten. Es enthält alle Informationen, um
PickPost / My Post 24 in Ihren Bestellprozess zu integrieren.
Ihre Kundenberaterin oder Ihr Kundenberater informieren Sie
gerne über weitere Möglichkeiten zu unseren empfängerorien­
tierten Dienstleistungen wie zum Beispiel den Login PostCon­
nector und weiteren dazugehörigen Angeboten.
Der Vorteil für Sie im Gegensatz zur alleinigen Integration des
Webservices «PickPost und My Post 24»: Bei technischen Aktua­
lisierungen der von PickPost betroffenen Systemen oder bei
neuen Möglichkeiten einer PickPost / My Post 24-Integration fällt
für Sie keine Neuprogrammierung an. Sprechen Sie Ihre Kunden­
beraterin oder Ihren Kundenberater darauf an.
Ihre Kundenberaterin oder Ihr Kundenberater der Post begleitet
Sie Schritt für Schritt durch die ganze Integration des Webser­
vices «PickPost und My Post 24» und ist bei Fragen gerne für Sie
da.
1.2 Wie ist dieses Handbuch aufgebaut?
Eine vollständige Integration des Webservices besteht aus drei
Komponenten:
– geografische Standortsuche mit Karte
– Abrufen der Kundendaten erfolgt über diesen Webservice
– Übermittlung der Sendungsdaten
Die Voraussetzungen für eine korrekte Integration bei Ihnen sind:
– Sie führen Ihre Stammdaten
– Mit den Daten aus der Standortsuche und dem Webservice
sowie Ihren Stammdaten drucken Sie korrekte physische
Adressetiketten aus
– Sie füllen die Datentransfer-Felder mit den oben erwähnten
Daten aus
– Vorzugsweise verfügen Sie nebst einem Produktivsystem über
ein Testsystem (Integration)
Kapitel 2
Informationen zur Anmeldung für die technischen Systeme und
zum Support
Kapitel 3
Beispiele von Websites mit PickPost / My Post 24-Integration
Kapitel 4
Technische Informationen, Programmieranleitungen inkl. Appli­
kation «georeferenzierte Standortsuche» mit Karte usw.
Kapitel 5
Alle Links des Dokuments auf einen Blick und Links auf weitere
nützliche Dokumente
Alles Wichtige für die Integration in elektronischer Form finden
Sie unter www.post.ch/pickpost-mypost24.
In jedem Fall werden Sie von Ihrer Kundenberaterin oder Ihrem
Kundenberater informiert, wenn Sie bei technischen Änderungen
betroffen sind und erhalten Unterstützung
1.4Kosten
Der Einsatz des Webservice PickPost und My Post 24 ist kostenlos.
An einen PickPost- oder My Post 24-Standort adressierte Sendungen kosten gleichviel wie an die Domiziladresse zugestellte
Sendungen (Pakete und Briefe mit Barcode).
1.5Nutzungsbedingungen
PickPost wird ausschliesslich von der Schweizerischen Post ange­
boten und darf nicht zweckentfremdet oder missbräuchlich ein­
gesetzt werden.
1.6Teilnahmebedingungen
Wenn Sie PickPost / My Post 24 in Ihren Bestellprozess integrieren,
stimmen Sie den unten aufgeführten Teilnahmebedingungen
der Schweizerischen Post zu. Bei Unsicherheiten steht Ihre
Kundenberaterin oder Ihr Kundenberater gerne zur Verfügung.
Teilnahmebedingungen PickPost / My Post 24
www.post.ch/pickpost-ts
(Klappmenü «Weitere Unterlagen»)
Teilnahmebedingungen Webservice «Barcode»
www.post.ch/barcode-ts
(Klappmenü «Technische Dokumentationen»)
Teilnahmebedingungen DataTransfer
www.post.ch/datatransfer-ts
(Klappmenü «Paket/Express/Vinolog» oder «Briefe mit Barcode»)
4
2 Ablauf der PickPost / My Post 24-Integration und Support
2.1 Anmeldung und Aufschaltung
Nachdem Sie mit Ihrer Kundenberaterin, Ihrem Kundenberater
definiert haben, welche technische Umsetzung Sie wählen, mel­
det er Sie für die nötigen technischen Systeme an und veranlasst
deren Aufschaltung. Kundenspezifische Daten (z. B. Login Kunden­
center, Rechnungsbeziehung, technische User (TU) usw.) werden
Ihnen per E-Mail zugestellt.
Sobald die Testphase erfolgreich abgeschlossen werden kann,
erfolgt die Freischaltung durch die Post.
1.Definition der
Umsetzungsvariante
2.Implementieren
Webservice-Client
4.Freigabe
durch Post
5.Liveschaltung
3.Testphase
Alle technischen Unterlagen für die Programmierung finden Sie
im Kapitel 4 dieses Handbuchs oder unter
www.post.ch/pickpost-mypost24.
2.1.1 Aktivieren des Webservices «PickPost und My Post 24»
Um die Integration des Webservices «PickPost und My Post 24» zu
starten, wenden Sie sich bitte direkt an Ihre Kundenberaterin, an
Ihren Kundenberater.
Wenn Sie eine Anmeldung für den Webservice wünschen, nimmt
Ihre Kundenberaterin, Ihr Kundenberater die nötigen Einstellungen
vor.
Die Kundenberaterin, der Kundenberater füllt mit Ihnen zusam­
men die Anmeldung zur Integration Webservice «PickPost und
My Post 24» und das Anmeldeformular für die Integration der
Standortsuche der Schweizerischen Post vor.
2.2 Support bei der Integration
und bei Problemen
2.2.1 Unterstützung bei der Integration
Bitte wenden Sie sich für die Anmeldung und bei Fragen rund um
die Integration an Ihre Kundenberaterin oder an Ihren Kunden­
berater der Post.
2.2.2 Systemunterbrüche und Fehlermeldungen
Installationsarbeiten oder andere geplante Unterbrüche der
Webservices «Barcode» sowie «PickPost und My Post 24» werden
nach Möglichkeit in Randzeiten verlegt. Sie werden über geplante
Ausfälle und Unterbrüche rechtzeitig via E-Mail informiert.
Die Post setzt höchste interne Anforderungen an einen stabilen
und einwandfreien Betrieb des Webservices «PickPost und My Post 24». Dennoch kann es aufgrund technischer Probleme
oder Störungen ausnahmsweise zu Ausfällen der Webservices
kommen.
In einem solchen Fall oder bei Fehlermeldungen nehmen Sie bitte
mit dem jeweiligen Kundendienst oder Support Webservice
Kontakt auf. Auch bei Problemen mit der Datenübermittlung
wenden Sie sich bitte an den entsprechenden Kundendienst oder
Support Webservice.
Kontakt Webservice «PickPost und My Post 24»
Kundendienst
Telefon 0848 888 888
Telefon 0848 888 899
[email protected]
Support Webservice
Telefon 0848 888 488
[email protected]
Diese Informationen leitet er an unseren Support Webservice
und die Verantwortlichen der Standortsuche weiter. So erhalten
Sie die benötigten Unterlagen für den Start der Integration in
Ihrer Testumgebung.
5
3 Beispiele von PickPost / My Post 24Integrationen
3.1 Die technischen Systeme kurz erklärt
3.1.1 Webservice «PickPost und My Post 24»
Der Webservice «PickPost und My Post 24» dient dazu, die
PickPost / My Post 24-Kundenidentifikation und den Kundenstatus abzurufen. Nach der Übermittlung der Kundendaten er­
halten Sie als Antwort bei bestehenden Kunden die aktuelle und
bei Neukunden eine frisch generierte User ID. In beiden Fällen
wird zusätzlich mitgeteilt, welchen Status (NONE, MAIL, REGIST­
RED_MAIL oder SUISSE-ID) der Kunde hat. Diese Information ist
vor allem für die Lieferung an My Post 24-Automaten wichtig.
Der Status zeigt an, ob die Post die Identität des Kunden schon
verifiziert hat. MAIL, REGISTRED_MAIL und SUISSE-ID können
dabei als gleichwertig betrachtet werden.
Damit die Sendung zuverlässig an den Kunden ausgelie­
fert werden kann, muss die PickPost / My Post 24-User ID
zwingend in die alternative PickPost- oder My Post 24-Standortadresse integriert und zusammen mit den Sendungsdaten elektronisch übermittelt werden (s. Handbuch Web­
service «Barcode» und Handbuch DataTransfer).
Beispiele von korrekten Adressen von Sendungen an einen
PickPost- oder My Post 24-Standort (vgl. 3.3 Bestellerfassung
und 4.2 Integration der Kartenapplikation «Standortsuche»):
Beispiel Adressierung PickPost
Aufbau der PickPost-/
My Post 24-Adressen
Beispiel mit Hans Muster
PickPost-User ID
Anrede, Vorname, Name
Herr Hans Muster
PickPost User ID
PickPost MU123456
Strasse, Nummer
Bahnhofstrasse 67
Postleitzahl, Ort
5000 Aarau
Im Onlinedienst «Standorte und Öffnungszeiten» finden Sie für
jede PickPost-Stelle einen detaillierten Hinweis zur Adressierung.
Beispiel Adressierung My Post 24
Aufbau der PickPost-/
My Post 24-Adressen
Beispiel mit Hans Muster
My Post 24-User ID
Anrede, Vorname, Name
Herr Hans Muster
MyPost24 User ID
MyPost24 MU123456
Strasse, Nummer oder
Gebäudebezeichnung
MP Shoppyland
Postleitzahl, Ort
3322 Urtenen-Schönbühl
Im Onlinedienst «Standorte und Öffnungszeiten» finden Sie für
jeden My Post 24-Automaten detaillierte Hinweise zur Adressie­
rung.
Webservice «PickPost und My Post 24» für PickPost /
My Post 24-Registrierung und/oder Anfrage User ID (Request):
z. B. Domiziladresse und E-Mail des Kunden, Benachrichtigungsmodus
Webanbindung
Logik / Verarbeitungsteil
Grafisches User Interface (GUI)
Kundensystem
Webservice «PickPost und My Post 24» (Response):
meldet PickPost / My Post 24-User ID und Status des Users
Vereinfachte Darstellung des Ablaufs des Webservices «PickPost und My Post 24»
6
Webservice
«PickPost und
My Post 24»
prüft Kundenanfrage, registriert
wenn Neukunde
und meldet
PickPost / My Post 24User ID
3.2 PickPost- oder My Post 24-Standorte
Es gibt verschiedene Möglichkeiten, wie Sie Ihren Kunden die
PickPost- / My Post 24-Standorte anzeigen können:
Suche via Karte
Schritt 3: Bestimmen Sie Ihre Lieferadresse
Lieferadresse
an Ihre Domiziladresse
1
Hans Muster
Musterstrasse 11
1234 Musterhausen
an eine andere Adresse
an eine PickPost-Stelle oder an einen My Post 24-Automaten
2
Beispiel PickPost-Stelle (zuletzt benutzt/selektiert):
Poststelle 3601 Thun 1 Bahnhofplatz
Panoramastrasse 1A – 3600 Thun
Öffnungszeiten: 08:30 – 19:00 Mo – Fr
09:00 – 12:00 Sa
Beispiel My Post 24-Automat (zuletzt benutzt/selektiert):
3322 Schönbühl Shoppyland My Post 24
MP Shoppyland – 3322 Urtenen-Schönbühl
Öffnungszeiten: 00:00 – 23:59 Mo – So
Wie wünschen Sie die Benachrichtigung bei Ankunft der Sendung in der Pick-Post-Stelle
oder an einem My Post 24-Automaten?
3
per E-Mail
E-Mail:
[email protected]
per SMS
Mobile-Nr.:
*
* obligatorische Felder
PickPost-Stelle oder My Post-24-Automaten suchen:
4
basel
Ergebnisse filtern
6 Ergebnisse
Beispiel einer Bestellseite mit PickPost / My Post 24-Integration und georeferenzierter Standortsuche
7
1 Wahl der Lieferadresse
Ihre Kunden können sich die Sendung an ihre Domiziladresse,
an eine andere Adresse oder an einen PickPost- oder
My Post 24-Standort liefern lassen. Wird die Option «an einen
PickPost- oder My Post 24-Standort» aktiviert, erscheinen in der
Bestellmaske die Frage zur Benachrichtigung 3 und die Karte
für die Stellensuche 4.
2 Vorgeschlagener PickPost- oder My Post 24-Standort
Sie haben die Möglichkeit, Ihren Kunden einen PickPost- oder
My Post 24-Standort vorzuschlagen. Dies kann zum Beispiel die
Stelle sein, die am nächsten zur Domiziladresse liegt. Falls der
Kunde bei Ihnen bereits einmal an einen PickPost- oder
My Post 24-Standort liefern liess, können Sie ihm den letztge­
wählten PickPost- oder My Post 24-Standort vorschlagen.
3 Angaben zur Benachrichtigung
Ihre Kunden können angeben, auf welche Weise sie benachrich­
tigt werden wollen, wenn die Sendung am PickPost- oder
My Post 24-Standort eingetroffen ist (E-Mail und/oder SMS/MMS).
Nebst der Standortsuche mittels der Karte (siehe Darstellung
Seite 7) können Sie die PickPost- oder My Post 24-Standorte
auch in einer ausführlichen Liste mit den Öffnungszeiten anzei­
gen.
4 Suchen und Auswählen eines PickPost- oder
My Post 24-Standorts
Die verschiedenen Standorte mit den entsprechenden Informati­
onen sind auf der Karte ersichtlich. Mit der georeferenzierten
Standortsuche ist es möglich, den nächstgelegenen PickPost- oder
My Post 24-Standort von einem definierten Ort anzeigen zu
lassen. Dieser Ort kann entweder mittels JavaScript-Parameter an
die Kartenapplikation übermittelt oder vom Benutzer manuell
eingegeben werden. Die Karte zentriert sich dynamisch an
diesem Ort und zeigt den nächsten PickPost- oder My Post 24Standort an. Wenn Ihre Kunden einen PickPost- oder
My Post 24- Standort auswählen, wird die korrekte Lieferadresse
direkt in das Bestellformular übernommen.
8
Suche nach dem nächstgelegenen Standort (Beispiel PickPost-Stelle)
-
-
Beispiel der Darstellung von PickPost- oder My Post 24-Standorten in einer Liste
Die PickPost- und / oder My Post 24-Standorte sind in einer
Liste aufgeführt und können durch Aktivierung des Buttons
ausgewählt werden. Vorteil dieser Darstellungsart:
Die Öffnungszeiten jeder Stelle lassen sich mit einem Mausklick
anzeigen. Auch hier bietet sich die Möglichkeit, die Stelle auf ei­
ner Karte anzeigen zu lassen.
9
Anzeige der Standorte via Drop-down-Menü (Beispiel PickPost-Stelle)
Darstellung der PickPost- oder My Post 24-Standorte in einem Drop-down-Menü
Der Kunde kann nach Kanton, Postleitzahl bzw. Ort oder Region
suchen. Die Auswahl der PickPost- oder My Post 24-Standorte
erscheint anschliessend im Drop-down-Menü. Dort kann der
Kunde die gewünschte Stelle bequem mit einem Klick auswählen.
10
Auswahl des zuletzt gewählten Standorts (Beispiel PickPost-Stelle)
-
-
Wenn Sie die Standortsuche selber aufbereiten wollen, stellen
wir Ihnen wöchentlich eine Standortliste mit allen benötigten
Informationen zur Verfügung. Wir empfehlen jedoch die Einbindung unserer Karte mit der Anzeige der unterschiedlichen
Standorte. Die Suche nach dem favorisierten Standort wird
dadurch für Ihre Kunden vereinfacht und für Sie entfällt das
wöchentliche Einbinden der Updates.
Im Kapitel 4.2 finden Sie die technischen Informationen zum
Einbinden der georeferenzierten Standortkarte in den Bestellpro­
zess.
Im Kapitel 4.3 finden Sie alle technischen Angaben zur Einbin­
dung unserer Standortlisten.
Bei einer korrekten Einbindung der Standortwahl werden die
dazugehörigen Adressdaten automatisch in die Bestellung über­
nommen. So ist sichergestellt, dass Ihre Kunden die Informatio­
nen nicht selber erfassen müssen und die Adressierung in jedem
Fall korrekt ist.
-
11
3.3Bestellerfassung
3.4 Bestellmaske online und Bestellschein
Um eine Bestellung anschliessend korrekt an einen PickPost- oder
My Post 24-Standort adressieren zu können, müssen bei der
Adresserfassung mindestens 4 Zeilen zur Verfügung stehen:
Es ist wichtig, dass die Bestellmaske so aufgebaut ist, dass eine
korrekte und vollständige Lieferadresse erstellt wird. Wir empfeh­
len Ihnen, online die PickPost- oder My Post 24-Standorte mittels
der georeferenzierten Suche Ihren Kunden anzuzeigen, damit
keine Fehler bei der Adressangabe entstehen. Auf dem Bestell­
schein muss es bei der Lieferadresse unbedingt genügend Platz
haben, um eine korrekte PickPost-Adresse angeben zu können.
Wir empfehlen folgende Zeilen:
Beispiel Adressierung PickPost
Aufbau der PickPost/
MyPost24-Adressen
Beispiel mit Hans Muster
PickPost-User ID
Anrede, Vorname, Name
Herr Hans Muster
PickPost User ID
PickPost MU123456
Strasse, Nummer
Bahnhofstrasse 67
Postleitzahl, Ort
5000 Aarau
Bitte beachten Sie, dass die Adressierung bei PickPost-Stellen
neu der Standortadresse entspricht. Es gibt keine Postfachadres­
sierung mehr.
Die Postfachadressierung an PickPost-Poststellen ist nicht mehr
gültig.
Beispiel Adressierung My Post 24
Aufbau der PickPost/
MyPost24-Adressen
Beispiel mit Hans Muster
PickPost-User ID
Anrede, Vorname, Name
Herr Hans Muster
MyPost24 User ID
MyPost24 MU123456
Strasse, Nummer oder
Gebäudebezeichnung
MP Shoppyland
Postleitzahl, Ort
3322 Urtenen-Schönbühl
Bitte beachten Sie, dass die Adressierung für My Post 24-Auto­
maten nicht in jedem Fall der Standortadresse entspricht.
Besonders zu beachten ist die Schreibweise der Keywords
PickPost / MyPost24 ohne Leerschlag gefolgt von einem
Leerschlag mit der 8-stelligen alphanumerischen User ID
(PickPost-/My Post 24-Kundennummer). Keyword MyPost24
ohne Leerschlag schreiben.
12
Vorname, Name (MUSS)
Zusatz Name
(MUSS = PickPost MU123456 oder
MyPost24 MU123456)
Strasse, Nr.,
Gebäudebezeichnung(MUSS)
PLZ, Ort
(MUSS)
Die Post prüft die eingelieferten Daten nicht auf deren Richtigkeit.
Die Verantwortung hierfür liegt bei Ihnen.
3.5 Gestaltungsvorgaben (Layout)
3.5.1Postlogo
Das Logo der Schweizerischen Post existiert in 4 Sprachen
(Deutsch, Französisch, Italienisch und Englisch) und kann sowohl
farbig als auch schwarz-weiss zur Verfügung gestellt werden.
Die von Ihnen benötigten Postlogos wird Ihnen Ihre Kundenbe­
raterin, Ihr Kundenberater zukommen lassen.
Gebrauch des Logos
Beachten Sie bei der Platzierung des Logos auf Ihrer Website
oder in Ihren Printunterlagen (Kataloge, Bestellschein, Flyer usw.)
folgende drei Punkte:
−Das Postlogo darf nicht geändert werden.
−Das Logo wird ohne Textzusätze
(wie z. B. «In Zusammenarbeit mit») eingesetzt.
−Um das Postlogo muss eine Schutzzone bestehen:
Diese garantiert einen Mindestabstand zu anderen Logos,
zu Bildern oder Texten. Die Grösse der Schutzzone entspricht
2 Mal der Höhe des «Fusses» des Schweizerkreuzes
(siehe Grafik).
Logo ohne definierte postgelbe Fläche
x
x
2x
2x
Wenn immer möglich, soll das dreifarbige Logo gebraucht wer­
den. Das schwarz-weiss-Logo kommt nur zum Einsatz, wenn das
farbige Logo aus technischen Gründen nicht eingesetzt werden
kann.
2x
Logo mit definierter postgelber Fläche
2x
Einsatz
3- und mehrfarbige Drucksachen
Farbe
3-farbig Sonderfarben, 4-farbig Euroskala,
5-farbig: 4-farbig Euroskala Postgelb (Sonderfarbe)
x
2x
2x
Einsatz
2x
1-farbige Drucksachen
FarbeSchwarz
Bemerkung Logo steht zwingend auf 25% Schwarz
Einsatz
1-farbige Drucksachen auf postgelbem oder weissem
Untergrund Schwarz
Farbe
Balken 25% Schwarz
13
Richtig
+
MusterGmbH
Um das Postlogo ist die erforderliche Schutzzone eingehalten.
Es ist vom Logo des Versandhändlers klar abgegrenzt.
Falsch
+
MusterGmbH
Um das Postlogo ist keine Schutzzone. Die beiden Logos ver­
schmelzen zu einem Bild, was nicht erlaubt ist.
3.5.2PickPost / My Post 24 Icons
Verwenden Sie die Icons für PickPost / My Post 24, um Ihre Kunden auf die praktischen alternativen Abholorte
aufmerksam zu machen. Wenden Sie sich für die Icons an Ihre Kundenberaterin, Ihren Kundenberater.
PickPost
My Post 24
Empfohlener Mouseover-Text
PickPost: Empfangen
und geben Sie Sendungen
auf, wo Sie wollen.
14
My Post 24: Sendungen
einfach rund um die Uhr
versenden und empfangen.
3.5.3Einbindung
Wie Sie die Icons auf Ihrer Homepage einbauen können, zeigen die folgenden Beispiele, die ebenfalls für Printumsetzungen möglich
sind.
Webshop
So einfach kommen Sie zu Ihrer Sendung.
PickPost
Wählen Sie für die Zustellung eine aus zahlreichen alternativen Abholstellen aus. Kostenlos.
Mehr dazu (Link in Box unten)
My Post 24
Empfangen Sie Ihre Pakete in einem Automaten. Kostenlos.
Mehr dazu (Link auf Folgeseite)
Mustertexte z. B. unter «Bestellung und Lieferung»
Diese Texte dürfen vom Onlineshop erst nach erfolgreicher Integration des Webservices «PickPost und My Post 24» auf der Webseite
oder in Kommunikationsmitteln verwendet werden.
Sind Sie viel unterwegs? So kommen Sie trotzdem schnell zu Ihrer Bestellung.
PickPost
Empfangen und geben Sie Sendungen auf, wo Sie wollen! Kostenlos. PickPost bietet Ihnen
über 2400 alternative Abhol- und Aufgabestellen in der ganzen Schweiz.
Geben Sie bei der Bestellung dem Versender Ihre persönliche User ID und die gewünschte PickPost-Stelle
als Lieferadresse an. Sie werden per SMS und/oder E-Mail informert, sobald die Sendung abholbereit
ist. Mit PickPost lassen sich auch einfach Pakete zurücksenden und vorfrankierte eingeschriebene
Briefe aufgeben. In der Regel innerhalb von 7 Tagen können Sie die Sendung dort abholen.
Infos und Anmeldung unter www.post.ch/pickpost
Wenn Sie noch nicht bei «PickPost und My Post 24» angemeldet sind, werden Sie im Bestellprozess
automatisch angemeldet. Anschliessend können Sie im «Kundencenter» der Post unter «Einstellungen»
unter «PickPost und My Post 24» Ihre Dauereinstellungen vornehmen.
15
My Post 24
Am My Post 24-Automaten können Sie Pakete und eingeschriebene Briefe rund um die Uhr abholen,
aufgeben oder zurücksenden..
Geben Sie bei Bestellungen als Lieferadresse den gewünschten My Post 24-Automaten und Ihre
persönliche User ID an. Sobald Ihre Sendung abholbereit ist, erhalten Sie per MMS oder E-Mail den
QR-Code zur Abholung. Scannen Sie diesen am Automaten ein und schon können Sie Ihre Sendung
entnehmen. In der Regel innerhalb von 10 Tagen können Sie die Sendung dort abholen.
Infos und Anmeldung unter www.post.ch/mypost24
Wenn Sie noch nicht bei «PickPost und My Post 24» angemeldet sind, werden Sie im Bestellprozess
automatisch angemeldet. Anschliessend können Sie im «Kundencenter» der Post unter «Einstellungen»
unter «PickPost und My Post 24» Ihre Dauereinstellungen vornehmen. Um den Dienst nutzen zu
können, muss Ihre Registration für den Dienst «PickPost und My Post 24» vollständig abgeschlossen
sein. Bitte beachten Sie: Um den Dienst My Post 24 vollständig nutzen zu können, müssen Sie Ihre
Adresse mittels eines zugesandten Briefcodes im «Kundencenter» Post bestätigen.
3.6Datenschutz
Da Sie Ihre Kundendaten für den PickPost / My Post 24-Service
zwecks Erbringung der Dienstleistung an die Schweizerische Post
weitergeben, muss dies dem Kunden auf Ihrer Bestellseite mitge­
teilt werden. Mit der Inanspruchnahme der Dienstleistung erteilt
Ihr Kunde sein Einverständnis, dass seine Daten an die Schweize­
rische Post weitergegeben werden dürfen.
Wir schlagen Ihnen dafür folgende Formulierung vor:
Übermittlung Ihrer Daten an die Schweizerische Post
Wenn Sie als Lieferadresse einen PickPost- oder My Post 24Standort gewählt haben, werden wir Ihre Daten (Name, Vor­
name, Adresse) der Schweizerischen Post übermitteln.
Diese Datenübermittlung ist nötig, damit die Post Sie für
PickPost / My Post 24 freischalten kann bzw. damit wir Ihre
persönliche PickPost / My Post 24-User ID von der Post erhalten.
Die Schweizerische Post verpflichtet sich, Ihre Daten vertraulich
zu behandeln (siehe dazu auch AGB «Login Kundencenter»
sowie Datenschutzerklärung auf www.post.ch).
16
4 Technische Informationen und Anleitungen
4.1 Webservice «PickPost und My Post 24»
Alles Wichtige für die PickPost-Integration in elektronischer Form
finden Sie unter www.post.ch/pickpost-mypost24 im Klappmenü
Technische Unterstützung Webservices «PickPost und My Post 24».
4.1.1Übertragungsprotokoll
Die Übertragung der Daten zum Webservice «PickPost und
My Post 24» erfolgt verschlüsselt mit HTTPS, Port 443.
4.1.2Authentifizierungsmechanismus
Basic Pre-Authentication über HTTPS
4.1.3 Endpunkt-Adresse des Webservices «PickPost und My Post 24» V3
SystemURL
Integration
https://webservices-int.post.ch/IN_PickPost/ssQueryCustomerPickPost/v3
Produktion
https://webservices.post.ch/IN_PickPost/ssQueryCustomerPickPost/v3
Für Testzwecke kann der Webservice «PickPost und My Post 24»
ebenfalls auf der Integrationsebene aufgerufen werden. Echtda­
ten sind vorhanden, es werden jedoch keine E-Mails oder SMS bei
der Registrierung eines neuen Kunden ausgelöst.
4.1.4Dienstleistungsbeschreibung
Die Dienstbeschreibung zum Webservice «PickPost und My Post 24» finden Sie im WSDL-File unter www.post.ch/
pickpost/mypost24 im Klappmenü Dokumentation.
Gewisse Webservice-Entwicklungswerkzeuge (z. B. Visual Stu­
dio) verstehen diese Notation nicht. Das WSDL muss in diesem
Fall manuell heruntergeladen und als lokale Kopie verwendet
werden.
Bei jedem Webservice-Aufruf müssen der Benutzername und
das Passwort übermittelt werden.
4.1.5Operation
«FindCustomerPickPostNumberRequest»
Der Webservice «PickPost und My Post 24» kennt nur eine Opera­
tion. Für die Nutzung der Operation wird SOAP über HTTPS ver­
wendet. Mittels der Operation «FindCustomerPickPostNumber­
Request» können Sie einen Kunden direkt für PickPost / My Post 24 anmelden. Als Antwort bekommen Sie die PickPost / My Post 24-User ID des angemeldeten Kunden. Diese ist ein obli­
gatorischer Bestandteil der Lieferadresse an einen PickPost- oder
My Post 24-Standort.
17
4.1.6 Antwort «FindCustomerPickPostNumberRequest»
ParameterWerte
PickPostNumber
Entspricht der PickPost / My Post 24-User ID des übermittelten Kunden.
Verified
Gibt den Zustand der Überprüfung des Kunden zurück.
– Wert MAIL
– Wert REGISTRED_MAIL
– Wert SUISSE_ID
– Wert NONE
4.1.7 Integrierte Fehlermeldung
Der Webservice «PickPost und My Post 24» kontrolliert die gelieferten Daten auf
ihre Richtigkeit. Bei fehlerhaften oder unvollständigen Daten
sendet er folgende Fehlermeldungen:
FehlermeldungenWerte
INVALID_TECHNICAL_USER
Die Identifikation der Anfrage ist fehlgeschlagen. Der technische Benutzer oder das Passwort sind nicht berechtigt. Nehmen Sie unmittelbar mit dem Kundendienst PickPost Kontakt auf,
um den technischen Benutzer für den Webservice «PickPost und My Post 24» nachzuprüfen.
INVALID_INPUT_PARAMETERS
Nicht alle erforderlichen Parameter wurden ausgefüllt, oder bei fest definierten Werten wurden nicht die richtigen Werte ausgefüllt.
INTERNAL_ERROR
Der Service hat ein Problem oder der Service steht nicht zur Verfügung. Nehmen Sie unmittelbar mit dem Kundendienst PickPost / My Post 24 Kontakt auf, um das Problem zu melden.
18
4.1.8 Struktur des Webservices «PickPost und My Post 24»
Operation «FindCustomerPickPostNumberRequest»
19
Die erforderlichen Parameter
ParameterWerte
Gender
Anrede des Kunden.
Dieser Parameter dient der Anrede des Kunden und ist sprachunabhängig.
Es sind nur fest definierte Werte mit vorgegebener Schreibweise akzeptiert:
– Wert „MAN“: Beispiel einer Anrede „Sehr geehrter Herr …“, „Cher Monsieur …“ usw.
– Wert „WOMAN“: Beispiel einer Anrede „Sehr geehrte Frau …“, „Chère Madame …“ usw.
– Wert „UNSPECIFIED“: Ist die Anrede des Kunden nicht bekannt, werden die Ansprachen möglichst
neutral gehalten „Sehr geehrte Damen und Herren“, „Chers clients PickPost / My Post 24“
usw.
LastName
Nachname des Kunden, der für PickPost registriert werden soll.
Maximum 50 Zeichen.
FirstName
Vorname des Kunden.
Maximum 50 Zeichen.
StreetAndNumber
Strasse und Strassennummer der Domiziladresse des Kunden.
Maximum 100 Zeichen.
PostalCode
PLZ der Domiziladresse des Kunden.
Mindestens 4 Ziffern, höchstens 5 Ziffern.
CityName
Wohnort der Domiziladresse des Kunden.
Maximum 50 Zeichen.
CountryCode
Ländercode der Domiziladresse. Es sind nur fest definierte Werte mit vorgegebener Schreibweise
akzeptiert:
– Wert „CH“ für die Schweiz. Dieser Wert ist auch der Defaultwert, falls keine Angaben für diesen Parameter übermittelt werden.
– Die Werte „LI“, „DE“, „FR“, „IT“, „AT“ werden ebenfalls akzeptiert.
LanguageCode
Sprachcode für die Sprache des Kunden. Es sind nur fest definierte Werte mit vorgegebener Schreib- weise akzeptiert:
– Wert „DE“ für Deutsch. Dieser Wert ist auch der Defaultwert, falls keine Angaben für diesen
Parameter übermittelt werden.
– Die Werte „FR“ und „IT“ werden ebenfalls akzeptiert.
Die Kommunikation bei der Dienstleistung PickPost ist auf die drei Hauptlandessprachen der Schweiz beschränkt.
EmailAddress
E-Mail-Adresse des Kunden. Die Adresse wird für die PickPost-Anmeldebestätigung und für die
Avisierung der Sendungen benötigt. Maximum 160 Zeichen.
Der Webservice kontrolliert die Formatierung der E-Mail-Adresse.
NotifyMode
Avisierungsmodus für PickPost-Sendungen, sobald sie bei einem PickPost- oder My Post 24-Standort
abholbereit sind.
In diesem Parameter sind nur fix definierte Werte mit vorgegebener Schreibweise akzeptiert:
–
Wert „SMS“: Ein SMS/MMS wird dem Kunden gesendet, sobald seine Sendung bei einem PickPost- oder
My Post 24-Standort abholbereit ist. Für diesen Modus ist die Mobile-Nummer des Kunden notwendig.
– Wert „EMAIL“: Ein E-Mail wird an die angegebene Kunden-E-Mail-Adresse gesendet, sobald seine Sendung bei einem PickPost- oder My Post 24-Standort abholbereit ist.
– Wert „SMS_EMAIL“: Ein SMS/MMS und ein E-Mail werden dem Kunden gesendet, sobald seine
Sendung bei einem PickPost- oder My Post 24-Standort abholbereit ist. Für diesen Modus ist die
Mobile-Nummer des Kunden notwendig.
Services
20
Dieser Parameter dient der Zuweisung der Dienstleistung. Der Kunde kann entweder für PickPost oder
My Post 24 angelegt werden.
– Wert PICKPOST
– Wert MYPOST24
Die optionalen Parameter
Die optionalen Parameter sind in der XML-Struktur zu kommentieren oder ggf. daraus zu löschen, falls sie nicht gebraucht
werden und keinen gültigen Wert enthalten.
ParameterWerte
AdditionalName1
Diese Felder dienen zusätzlichen Angaben über die Person oder die Adresse.
Maximum 50 Zeichen. Beispiele:
AdditionalName2
– c/o-Adressen: „C/O Peter Müller“
– Zusatzadresse: „Chalet Alpenblick“
– Und weitere Angaben
MobileNumber
Mobile-Nummer des Kunden für die SMS-Avisierungen.
Der Webservice kontrolliert das Format der Nummer und akzeptiert nur folgende Formate:
–0799999999
–+41799999999
–0041799999999
Antwort «FindCustomerPickPostNumberRequest»
Antwort «FindCustomerPickPostNumberRequest» bei Fehlermeldung
21
4.2 Integration der Kartenapplikation «Standortsuche»
Die Standortsuche der Schweizerischen Post ist eine Webapplika­
tion, welche einem Benutzer verschiedenste Informationen wie
Standorte, Öffnungszeiten oder angebotene Dienstleistungen
der verschiedenen Points of Interest (POI) der Post zugänglich
macht. Beispiele solcher POI’s sind Poststellen, My Post 24-Auto­
maten, Briefeinwürfe, Postomaten usw.
Ausserdem kann sich ein User mit der Standortsuche die kor­
rekte Anschrift eines bestimmten Standortes (z. B. einer PickPostStelle) anzeigen lassen und diese Adressierung sogleich überneh­
men (z. B. für einen Bestellprozess).
Die Kartenapplikation der Schweizerischen Post kann direkt in
den eigenen Webauftritt integriert werden. Die Einbindung er­
folgt mittels Javascript und verwendet die Komponenten der Ap­
plikation Standortsuche. Zusätzlich muss das Kartenmaterial von
Google Maps clientseitig eingebunden werden.
4.2.1 Aufbau und Design der neuen Standortsuche
Die neue Standortsuche wurde mit «responsive Design» umge­
setzt, das heisst, dass sich die Ansicht automatisch der zur Verfü­
gung stehenden Fenstergrösse anpasst. Durch diese Neuerung
entfällt für den Integrator bei der Einbindung der Standortsuche
die manuelle Konfiguration der Darstellungsgrösse. Es existieren
drei vordefinierte Anzeigegrössen (Desktop, Tablet und Mobile),
welche sich sowohl im Layout wie auch im Detailgrad der darge­
stellten Informationen unterscheiden.
In der Desktop-Ansicht (Darstellungsbreite von mindestens 1024
horizontalen Pixeln) werden die Standorte in der Kartenansicht
ausgegeben. In der Tablet-Ansicht (Darstellungsbreite von min­
destens 661 horizontalen Pixeln) und in der Mobile-Ansicht (Dar­
stellungsbreite von weniger als 661 horizontalen Pixeln) werden
die Standorte in der Listenansicht ausgegeben.
Abbildungen: Viewports der Standortsuche Responsive (im Beispiel eingebunden auf der Seite der Schweizerischen Post)
Aufruf der Standortsuche (Desktop)
22
Aufruf der Standortsuche (Tablet view)
Aufruf der Standortsuche (Mobile view)
23
Neben der Anzeige besteht zudem die Option zur Übernahme
der Adressierung eines bestimmten Standortes. Ist der ge­
wünschte Standort angewählt, liefert die Applikation Standort­
suche mit Klick auf den Button «Standort übernehmen» die kor­
rekte Adressierung per Javascript. Die Übernahme von Adressen
funktioniert mit den POI-Typen PickPost-Stelle, My Post 24-Stelle
und Poststelle. Um diese Funktion in Ihre Webseite einzubinden,
befolgen Sie bitte die Anweisungen im Abschnitt «Adressierung
übernehmen».
Funktion «Standort übernehmen»
24
4.2.2 Ablauf für die Einbindung der Standortsuche
Um die Standortsuche erfolgreich auf einer Webseite einzubin­
den, wird der folgende Prozess vorausgesetzt:
Der Integrator übermittelt das Formular „Anmeldeformular für
die Integration der Kartenapplikation Standortsuche“ vollständig
ausgefüllt via E-Mail an [email protected].
1. Zwingend anzugeben sind der Name der Firma und Name,
E-Mail und Telefonnummer der verantwortlichen Person, so­
wie die Domain der Webseite, auf der die Standortsuche
eingebettet werden soll.
2. Die Schweizerische Post prüft und erfasst Ihre Angaben und
übermittelt Ihnen anschliessend eine Anmeldebestätigung
mit einem API-Schlüssel. Dieser Schlüssel wird für die Einbin­
dung der Standortsuche im Quellcode (siehe Abschnitt
«Technische Einbindung im HTML-Code») benötigt.
3. Der Integrator ruft den Google Maps API-Schlüssel ab. Dazu
ist die Registrierung bei Google eine zwingende Vorausset­
zung. Unter folgendem Link finden Sie eine Wegleitung zum
Abruf des Google Maps API-Schlüssels:
https://developers.google.com/maps/documentation/ja­
vascript/tutorial
Es ist zu beachten, dass Google zwei unterschiedliche Lizen­
zen anbietet, die sich in den angebotenen Funktionalitäten
unterscheiden. Für die Standortsuche der Schweizerischen
Post ist die Art der Google Maps Lizenz allerdings nicht rele­
vant. Mehr Informationen zu den Google Maps Lizenzen er­
halten Sie unter dem folgenden Link:
https://developers.google.com/maps/documentation/ja­
vascript/tutorial
4.2.3 Technische Einbindung im HTML-Code
Die einzubindende URL ist mit dem Protokoll https zu hinterle­
gen. Für eine erfolgreiche Einbindung der Standortsuche müs­
sen folgende Code-Zeilen in den HTML-Code der Webseite ein­
gefügt werden:
1. Einbinden des Google Maps Kartenmaterials im Header der
Webseite. «GoogleApiKey» muss mit Ihrem von Google an­
geforderten API Key ersetzt werden.
2. Einbinden der Applikation Standortsuche der Schweizeri­
schen Post im Header der Webseite. «MyApiKey» muss mit
dem von der Schweizerischen Post gelieferten API-Key er­
setzt werden.
3. Das Div, in welches die Applikation geladen wird. Bitte an
der gewünschten Stelle im Body der Webseite einfügen.
Achtung: Alle ID’s der HTML Elemente, welche von der Post
Standortsuche RIA verwendet werden, beginnen mit «Post­
Stao». Das CSS ist auf die ID des obersten Divs mit der ID «Post­
Stao» gescoped.
Aus diesem Grund darf auf der Seite, auf welcher die Integra­
tion gemacht wird:
− kein HTML Element enthalten sein, dessen ID «PostStao»
heisst
− kein HTML Element enthalten sein, dessen ID mit «Post
Stao» beginnt
− kein CSS enthalten sein, welches den Scope «PostStao»
besitzt
Bitte beachten Sie, dass die Schweizerische Post keinen Sup­
port für die von Google angebotenen Produkte leistet. Für
Fragen und Probleme im Zusammenhang mit der Registrie­
rung oder dem Beziehen eines Google Maps API-Schlüssels
wenden Sie sich in jedem Fall direkt an den Support von
Google.
4. Der Integrator nimmt die notwendigen Änderungen im
HTML-Code vor, um die Standortsuche der Schweizerischen
Post in die Webseite zu integrieren. Dazu müssen der HTMLCode der Webseite und im Abschnitt «Technische Einbin­
dung im HTML-Code» die Code-Zeilen erweitert werden.
Hierzu sind der API-Schlüssel der Post sowie API-Schlüssel
von Google Maps notwendig.
5. Die Standortsuche der Schweizerischen Post ist nun erfolg­
reich eingebunden.
25
<!DOCTYPE html>
<html>
<head>
<meta http-equiv="content-type" content="text/html;charset=utf-8">
<!-- 1. -->
<script src="https://maps.googleapis.com/maps/api/js?
key=GoogleApiKey&sensor=false"></script>
<!-- 2. -->
<script type="text/javascript" src="https://places.post.ch/ria?
containerId=container&apiKey=myApiKey&lang=de/fr/it/en"></script>
</head>
<body>
<!-- 3. -->
<div id="container"></div>
</body>
</html>
Werden die Umlaute in der Applikation falsch encodiert (mit
Sonderzeichen dargestellt), muss das Encoding umgestellt
werden. Standardmässig unterstützt die Kartenapplikation
der Post-Standortsuche UTF-8 Encoding. Falls nötig, kann
das Encoding auf ISO-8859-1 umgestellt werden. Dazu muss
im Headbereich folgender Metatag definiert werden: <meta
http-equiv="content-type" content="text/html;
charset=ISO-8859-1" />
26
Die Kartenapplikation stellt folgende Parameter zur Verfügung:
„containerId“:
Die ID des Div-Elements, in welchem die Appli­
kation geladen werden soll. Diese kann frei ge­
wählt werden und dient der Identifikation des
Div-Elements der Kartenapplikation.
„apiKey“:
Der (Post-) API Key des Profiles, das verwendet
werden soll.
Der Referrer (d.h. die Domain der Website, auf
welcher die Standortsuche geladen werden soll)
muss derjenigen Domain entsprechen, welche
im Formular «Anmeldung zur Integration der
Standortsuche» angegeben wurde, und im ent­
sprechenden Nutzerprofil der Schweizerischen
Post hinterlegt sein.
„lang“:
Mit diesem Parameter wird die Ausgabesprache
der Standortsuche definiert. Es stehen Deutsch
(„de“), Französisch („fr“), Italienisch („it“) sowie
Englisch („en“) zur Verfügung. Wird dieser Para­
meter nicht angegeben, wird die Applikation in
der Sprache «de» (Deutsch) geladen.
4.2.4 Adressierung übernehmen
Die Standortsuche der Schweizerischen Post bietet die Mög­
lichkeit, die Adressierung eines bestimmten Standortes zu
übernehmen. Dafür muss im HTML-Code zusätzlich eine
Funktion definiert werden, welche beim Start der Applika­
tion Standortsuche ausgeführt wird. Bitte fügen Sie hierzu
folgende HTML-Codezeilen in den Header Ihrer Webseite
ein:
<script type="text/javascript">
// Die Funktion "ready" wird ausgeführt, sobald die Applikation Standortsuche
vollständig geladen wurde
Stao.ready = function () {
// Die Konfiguration wird überschrieben/angepasst, um die Funktionalität "Standort übernehmen" zu aktivieren.
Stao.Api.configuration.setConfiguration({
SelectAddressEnabled: true
});
// Ein Listener für das Event "addressSelected" wird hinzugefügt.
Stao.Api.events.addListener("addressSelected", handleAddressSelectedEvent);
}
function handleAddressSelectedEvent(address) {
console.debug("address selected", address);
}
</script>
Das Objekt, welches von dem Event-Listener empfangen
wird, verfügt über folgende Properties (auf dem POI nicht
vorhandene Properties haben den Wert "null"):
property-name
Beschreibung
Type
Poi-Type (PICKPOST, POSTSTELLE, MYPOST24)
PoiTypeName
Lesbarer Namen des PoiTypen: Poststelle, PickPost, MyPost24 für 001PST, 001AG-PICK oder 001MP24. Für die
anderen POI-Typen wird das desc-Attribut aus dem Types-Services von ESRI verwendet.
PoiId
Poi-ID (bspw. 001PST_25623)
PoiTypeId
ID des PoiTypen (bspw. 001PST)
AddressTypeId
Die ID (Standortsuche intern, nicht vom StaoCache) der selektierten/zurückgegebenen Adresse des POIs
(Poststelle: 1, PickPost oder My Post 24: 2), als integer.
Die Adresse eines POIs kann entweder die Adresse einer PickPost/My Post 24-Stelle oder einer Poststelle sein.
AddressTypeName
Der Name des entsprechenden AddressTypes (siehe AddressTypeId).
Poststelle: POSTSTELLE, PickPost / My Post 24: PICKPOST / MYPOST24
27
property-name
Beschreibung
Street
der Strassennamen
City
der Ortsnamen
Zip
die Postleitzahl
GemeindeId
die Gemeinde ID
KantonCode
der Kanton Code
CountryCode
der Land Code
CountryName
der Landname
TechnicalPlz6
die 6-stellige Postleitzahl
4.2.5 URL Parameter
Das Verhalten der Post Standortsuche kann über URL Para­
meter gesteuert werden. Die folgenden URL Parameter kön­
nen übergeben werden:
Parameter Name
Beschreibung
lang
Die Sprache, in der die Applikation geladen werden soll. Mögliche Werte sind: "de", "fr", "it" und "en".
Wird dieser Parameter nicht angegeben, wird die Applikation in der Sprache "de" (Deutsch) geladen.
preselectText
Text (Adresse, POI oder Tech PLZ), welcher beim Aufstarten der Standortsuche für die initiale Suche verwendet
werden soll.
− Falls der Text ein "_" enthält, so wird er als PoiId interpretiert.
− Ist der Text 6 Zeichen lang und eine Zahl, so wird er als TechPLZ interpretiert.
− Trifft keine der zwei Bedingungen zu, so wird der Text als Adresse interpretiert bzw. eine normale Suche
wird durchgeführt.
topic
Die ID des Themas, welches beim Start selektiert werden soll (ist auf dem Admin UI, im Thema zu sehen).
Diese Werte werden bei der Konfiguration erstellt und bekannt gegeben.
openat
Voreingestellter Öffnungszeitenfilter. Der Wert dieses Filters wird als Initialwert im Öffnungszeiten-Filterpanel
gesetzt. Zugleich wird der Öffnungszeiten-Filter aktiviert.
Der "openat"-Parameter muss im folgenden Format angegeben werden: "yyyy-MM-ddTHH:mm".
− "-": Konstante, welche die Teile der Datumsangabe trennt
− ":": Konstante, welche die Teile der Zeitangabe trennt
− "T": Konstante, welche den Datums- vom Zeit-Teil trennt
− "yyyy": das Jahr mit 4 Stellen (z. B. "2015" für das Jahr 2015)
− "MM": der des Jahres Monat mit 2 Stellen, wobei Januar = 1 (z. B. "02" für den Februar)
− "dd": der Tag des Monats mit 2 Stellen, wobei erster Tag = 1 (z. B. "05" für den fünften Tag im Monat)
− "HH": die Stunden des Tages mit 2 Stellen im 24h Modell (z. B. "08" für acht Uhr morgens)
− "mm": die Minuten der Stunde mit 2 Stellen (z. B. "55" für fünf Minuten vor der vollen Stunde)
− Ganzes Beispiel: "2015-02-05T08:55"
28
4.2.6 URL Encoding
Die übergebenen URL Parameter Werte müssen URL en­
coded sein. Das gilt insbesondere für die Sonderzeichen und
Umlaute, welche für den preselectText benützt werden (Bsp.
ö -> %C3%B6).
Ausführliches Beispiel:
<script type="text/javascript">
Stao.ready = function () {
// Die ursprüngliche Konfiguration wird geholt.
// Dadurch kann z. B. ein bestehender Wert überprüft werden.
// Alternativ kann (wie in den Beispielen für die zugelassenen Properties) ein neues Objekt erstellt und gesetzt werden
var config = Stao.Api.configuration.getConfiguration();
// Die Werte werden überschrieben
config.SelectAddressEnabled = true;
config.PreselectText = "Bern";
config.OpenAt = "2015-03-02T22:00";
config.Topics.forEach(function(t) {
config.OnStartActivatedTopicUniqueKey = "2"; // Diese Nummer ist dem Admin
UI zu entnehmen
Stao.Api.configuration.setConfiguration(config);
}
</script>
4.2.7 Abschliessende Bemerkungen
Bitte beachten Sie, dass die Schweizerische Post keine Haf­
tung für die von Google Maps gelieferten Daten übernimmt
und keine Gewähr für die Richtigkeit dieser Informationen
leistet.
Für Fragen oder Anmerkungen zur Einbindung der Standort­
suche der Schweizerischen Post wenden Sie sich bitte an
[email protected].
29
4.2.8 Anmeldeformular für die Integration der Karten
applikation «Standortsuche»
Um Ihre Webseite für die Integration der Standortsuche der
Schweizerischen Post zu berechtigen, benötigen wir einige Anga­
ben. Bitte füllen Sie alle Felder des Anmeldeformulars sorgfältig
aus und senden Sie dieses im Anschluss an Ihre Kontaktperson
oder [email protected] (Anmeldeformular). Wir werden
Ihre Angaben überprüfen und Ihnen den für die Einbindung
benötigten API-Key schnellstmöglich zukommen lassen.
Ihre Angaben:
Name der
Firma/Organisation
Firma XY (Beispiel: Die Schweizerische Post)
Kurzbeschrieb der Website
Name des Profils
(Bei mehreren Profilen
bitte jeweils ein eigenes
Formular je Profil ausfüllen)
Name der Website der Firma XY als URL (Beispiel: www.post.ch)
Kontaktdaten der
Ansprechperson
Name:
E-Mail:
Telefon:
Domain/Domains, auf der/
denen die Standortsuche
eingebunden wird
Domain 1: Beispiel-URL wie www.post.ch
Domain 2: Beispiel-URL wie postshop.ch
Domain 3: https://places.post.ch
Domain 4:
Domain 5:
30
4.3 PickPost- oder My Post 24-StandorteDatei
4.3.1 Allgemeine Beschreibung
Die Post liefert die Übermittlungsdatei für PickPost- oder
My Post 24-Standorte im XML-Format, welches im Kapitel 4.3.8
definiert wird.
– Die Identifikationsnummer des PickPost- oder My Post 24Standorts
– Die Lokalisationsadresse des PickPost- oder My Post 24-Stand­
orts, die zur geografischen Veranschaulichung der Abholstelle
dient
– Die Lieferadresse des PickPost- oder My Post 24-Standorts,
die als Adresse für die Sendungen für den PickPost- oder
My Post 24-Standort dient
– Die geografischen Koordinaten des PickPost- oder My Post 24Standorts
– Eine 6-stellige PLZ zu diesem PickPost- oder My Post 24Standort
– Ein Link zu den Detailangaben des PickPost- oder My Post 24Standorts
– Information, ob der PickPost- oder My Post 24-Standort auch
eine Annahmestelle ist
– Die Öffnungszeiten mit Angabe der Wochentage
4.3.2Aktualisierungen
Die Datei mit den PickPost- oder My Post 24-Standorten wird
durch die Post jeweils Anfang Woche aktualisiert und auf dem
FTP-Server bereitgestellt oder per E-Mail versendet. Diese muss
wöchentlich in Ihrem System aktualisiert werden.
4.3.3Dateiname
Der Name der PickPost- oder My Post 24-Standorte-Datei lautet
«pickpost-points.xml». Die Dateiversion ist in den Einstellungsin­
formationen der Datei angegeben.
4.3.4 PickPost- oder My Post 24-Standorte-Liste
im XML-Format
Die Beispieldatei finden Sie unter www.post.ch/pickpostmypost24 im Klappmenü Dokumentation.
4.3.5 Prüfschema zum XML-File der PickPost- oder
My Post 24-Standorte-Liste
Die Beispieldatei finden Sie unter www.post.ch/pickpostmypost24 im Klappmenü Dokumentation.
4.3.6Übermittlungseinstellungen
−Sie sind bei DataTransfer registriert:
Die Übermittlungseinstellungen für den FTP-Server sind die
gleichen Einstellungen, die Sie für DataTransfer benutzen.
Ein Verzeichnis «PickPost» befindet sich im Ausgangsbereich
des Servers. In diesem Verzeichnis finden Sie die PickPostoder My Post 24-Standorte-Datei.
−Sie sind nicht bei DataTransfer registriert:
Die Post kann Ihnen diese Datei per E-Mail zusenden.
Bitte geben Sie Ihrem Kundenberater bei der Anmeldung die
E-Mail-Adresse an.
4.3.7 Aktualisierungen der PickPost- oder
My Post 24-Standorte-Datei
Neue PickPost- oder My Post 24-Standorte werden jeweils un­
verzüglich mit den oben aufgeführten Informationen in die
PickPost- oder My Post 24-Standorte-Datei aufgenommen. Bie­
ten Standorte den PickPost-Service nicht mehr an, werden diese
von der Datei gestrichen. Sollten Sie diese gespeichert haben,
müssen Sie sicherstellen, dass sie auf Ihrer Ablage gelöscht wer­
den.
Bei bestehenden PickPost- oder My Post 24-Standorten werden
allfällige Adressänderungen oder Änderungen der Öffnungszei­
ten in der Datei aktualisiert. Die Identifikationsnummer des
PickPost- oder My Post 24-Standorts bleibt jeweils gleich, alle
anderen Informationen können aber geändert werden.
4.3.8 Dateistruktur PickPost- oder My Post 24-StandorteDatei
Die untenstehende Tabelle beschreibt die Struktur und den In­
halt der Datei der PickPost- oder My Post 24-Standorte gemäss
den Feldbezeichnungen und den Regeln der Kapitel 4.3.9 und
Kapitel 4.3.10.
31
<Element> Beschreibung
Eigen- Datentyp
Attribut
schaft
Format
(Max.Länge)
Standardwert
2
02
<Envelope>
Version
xmlns
<FileInfos>
Versionsnummer des Speicherformats
M
Numerisch
Versionsnummer des Speicherformats; dient als Identifikationsmarke für die Datei
M
Alphanum.
Allgemeine Angaben zur Datei
FileID
Eindeutige Nummer der Datei
M
Numerisch
8
FileDate
Publikationsdatum der Datei
M
YYYYMMDD 8
FileTime
Publikationszeit der Datei
M
HH:MM:SS
6
</FileInfos>
<Data>
<Item>
Datenteil
Daten des PickPost- oder My Post 24-Standorts
PP_Number
Nummer des PickPost- oder My Post M
24-Standorts
Numerisch
8
Art der Stelle PickPost oder My Post 24
M
Alphanum.
10
PP_Name
Beschreibung des PickPost- oder My Post
24-Standorts
M
Alphanum.
120
PP_Street
Strasse, Hausnummer M
Alphanum.
35
PP_ZIP
Postleitzahl
M
Numerisch
4
PP_City
Ort
M
Alphanum.
35
PP_KT
Kantonskürzel
M
Alphanum.
2
PP_Area
Region
M
Alphanum.
35
PP_ZIP6
6-stellige PLZ M
Numerisch
6
PP_WebLink
Link zu den Detail-Informationen des
PickPost- oder My Post 24-Standorts
M
Alphanum.
250
<Delivery>
Adresse, die als Lieferadresse für die
Sendungen verwendet wird
PP_DelStreet
Strasse, Nr. oder Gebäudebezeichnung
M
Alphanum.
35
PP_DelZIP
Postleitzahl
M
Numerisch
4
PP_DelCity
Ort
M
Alphanum.
35
PP_Service
</Delivery>
<GeoPositiony>
Koordinaten des PickPost- oder My Post
24-Standorts im Format WGS84 PP_ Latitude
Breitengrad
M
Numerisch
12
Bsp. 47.46559273
PP_ Longitude
Längengrad
M
Numerisch
12
Bsp. 7.85353810
</ GeoPositiony >
< DepositOffice>
Bezeichnet den PickPost- oder My Post
24-Standort als Annahmestelle
Annahme-Stelle Ja=1/Nein=0
32
PP_Deposit
M
Numerisch
1
<Element> Beschreibung
Eigen- Datentyp
Attribut
schaft
Format
(Max.Länge)
Standardwert
</DepositOffice>
<OpenTime>
Öffnungszeiten
<Period (1à7)>
Öffnungszeiten für höchstens
7 verschiedene Perioden
PER_VON
Periode vom
M
DD.MM
PER_BIS
Periode bis
M
DD.MM
OEFF_VON
Geöffnet ab
M
HH:MM
OEFF_BIS
Geöffnet bis
M
HH:MM
MO
Montag
K
X
„X“ oder „“
DI
Dienstag
K
X
„X“ oder „“
MI
Mittwoch
K
X
„X“ oder „“
DO
Donnerstag
K
X
„X“ oder „“
FR
Freitag
K
X
„X“ oder „“
SA
Samstag
K
X
„X“ oder „“
SO
Sonntag
K
X
„X“ oder „“
</OpenTime>
</Items>
</Data>
</Envelope>
Für jede Dienstleistungsgruppe wird das Attribut mit einem obligatorischen Wert („M“) ausgefüllt.
33
4.3.9 Download der Daten der PickPost- oder
My Post 24-Standorte-Datei
Die Daten der PickPost- oder My Post 24-Standorte können wie
folgt geladen werden:
1. Die Identifizierung der Abholstellen muss mittels Feld PP_
Number erfolgen.
2. Die Identifikationsnummer entspricht der Nummer aus der
Datei der PickPost- oder My Post 24-Standorte.
Es handelt sich dabei um:
– eine Abholstelle, die gleich geblieben ist (es gab keine Än­
derungen)
oder
– eine Änderung des Inhalts eines PickPost- oder My Post 24Standorts
3. Die Identifikationsnummer der Abholstelle existiert in der ge­
lieferten Datei nicht mehr:
– Es handelt sich um eine Abholstelle, die aufgehoben wurde.
Diese Stelle muss von der Liste der gültigen PickPost- oder
My Post 24-Standorte gestrichen werden! Es werden keine
PickPost-Sendungen mehr an diesen Standort geliefert.
4. Die Identifikationsnummer der Abholstelle ist eine neue Num­
mer:
– Es handelt sich um eine neue Abholstelle, die zur Liste der
gültigen PickPost- oder My Post 24-Standorte hinzugefügt
werden muss.
4.3.10Verwendung der Daten der PickPost- oder
My Post 24-Standorte-Datei
Die Daten der PickPost- oder My Post 24-Standorte werden wie
folgt verwendet:
1. Suche nach der Adresse eines PickPost /
My Post 24-Standorts
– PP_Name,
Name des PickPost- oder
My Post 24-Standorts
– PP_Service,
Typ der Stelle PickPost oder
My Post 24
– PP_Street, Strassenname des PickPost- oder
My Post 24-Standorts
– PP_ZIP und PP_City PLZ und Ort des PickPost- oder
My Post 24-Standorts
2. PP_WebLink
Link zu allen Detailangaben über
diese PickPost- oder
My Postb24-Standorte auf der Inter
netseite der Post CH AG
34
3. Für die Adressierung der Sendung an eine PickPostoder My Post 24-Standort (Empfängeradresse)
– Name und Vorname des Kunden
– PickPost und MyPost24, wenn bekannt, PickPost / My Post
24-User ID (mit dem Webservice «PickPost und My Post 24»
ist die PickPost / My Post 24-User ID vorhanden)
– PP_DelStreet
Strassenname/Postfach für die
Lieferung an den ausgewählten
PickPost- oder My Post 24-Standort
– PP_DelZIP, PP_DelCity PLZ und Ort für die Lieferung an den
ausgewählten PickPost- oder
My Post 24-Standort
Die Adresse in PP_Street, PP_ZIP und PP_City ermöglicht die
Lokalisierung des PickPost- oder My Post 24-Standorts auf ei­
nem Plan. Sie darf auf gar keinen Fall für die Adressierung der
Sendung verwendet werden. Nur die Lieferadresse darf auf
der Sendung aufgeführt sein.
4. Für die Kommunikation via DataTransfer müssen die
Felder der Datei mit den PickPost- oder My Post 24-Standorten in die folgenden Felder der DataTransfer-Datei
eingefügt werden:
– PP_Number in das folgende Feld einfügen PKP_PointNbr
– PP_DelStreet
REC_Street
–PP_DelZIP
REC_ZIP
–PP_DelCity
REC_City
5. Für die Darstellung des PickPost- oder My Post 24-Standorts
auf einer Karte (z. B. Google Maps):
– PP_Latitude Breitengrad im Format WGS84
(z. B: 47.39061655)
– PP_Longitude Längengrad im Format WGS84
(z. B: 8.04545931)
6. Die Einzelheiten zu den Perioden müssen wie folgt dargestellt
werden:
– Jede Periode beschreibt andere Öffnungszeiten.
– Die Anzahl Perioden ist nicht festgelegt (min. 1 max. 7).
4.3.11Beispiele
4.3.11.1 Beispiel XML-Datei
<?xml version="1.0" encoding="UTF-8"?>
<Envelope xmlns="http://www.post.ch/pickpost/schemas/points/2013/03" version="03">
<FileInfos FileID="247" FileDate="20131216" FileTime="04:00:07"/>
<Data>
<Item PP_Number="3574" PP_Service="MyPost24" PP_Name="My Post 24 Bern Schönburg"
PP_Street="Viktoriastrasse 21" PP_ZIP="3030" PP_City="Bern" PP_KT="BE"
PP_Area="Berner Mittelland"
PP_WebLink="http://standorteint.post.ch/AllAccess/Detail/de?poi=001MP24_0012529">
<Delivery PP_DelStreet="Viktoriastrasse 21" PP_DelZIP="3030" PP_DelCity="Bern"/>
<GeoPosition PP_Latitude="46.95329326" PP_Longitude="7.45760122"/>
<DepositOffice PP_Deposit="1"/>
<OpenTime>
<Period PER_VON="1.01" PER_BIS="31.12" OEFF_VON="00:00" OEFF_BIS="23:59"
MO="X" DI="X" MI="X" DO="X" FR="X" SA="X" SO="X"/>
</OpenTime>
</Item>
<Item PP_Number="2688" PP_Service="PickPost" PP_Name="Office de poste Le Sentier"
PP_Street="Grande-Rue 36B" PP_ZIP="1347" PP_City="Le Sentier" PP_KT="VD" PP_Area="Vaud"
PP_WebLink="http://standorteint.post.ch/AllAccess/Detail/fr?poi=001PST_001114640">
<Delivery PP_DelStreet="Case postale 1000" PP_DelZIP="1347" PP_DelCity="Le Sentier"/>
<GeoPosition PP_Latitude="46.60773720" PP_Longitude="6.23125970"/>
<DepositOffice PP_Deposit="1"/>
<OpenTime>
<Period PER_VON="1.01" PER_BIS="31.12" OEFF_VON="08:00" OEFF_BIS="12:30"
MO="X" DI="X" MI="X" DO="X" FR="X" SA="" SO=""/>
<Period PER_VON="1.01" PER_BIS="31.12" OEFF_VON="13:45" OEFF_BIS="18:00"
MO="X" DI="X" MI="X" DO="X" FR="X" SA="" SO=""/>
<Period PER_VON="1.01" PER_BIS="31.12" OEFF_VON="08:00" OEFF_BIS="11:00"
MO="" DI="" MI="" DO="" FR="" SA="X" SO=""/>
</OpenTime>
</Item>
<Item PP_Number="5808" PP_Service="PickPost" PP_Name="Bern Wankdorf Shell"
PP_Street="Winkelriedstrasse 7A" PP_ZIP="3014" PP_City="Bern" PP_KT="BE"
PP_Area="Berner Mittelland"
PP_WebLink="http://standorteint.post.ch/AllAccess/Detail/de?poi=001AG-PICK_001194197">
<Delivery PP_DelStreet="Winkelriedstrasse 7A" PP_DelZIP="3014" PP_DelCity="Bern"/>
<GeoPosition PP_Latitude="46.96507125" PP_Longitude="7.46385714"/>
<DepositOffice PP_Deposit="0"/>
<OpenTime>
<Period PER_VON="1.01" PER_BIS="31.12" OEFF_VON="06:00" OEFF_BIS="22:00"
MO="X" DI="X" MI="X" DO="X" FR="X" SA="" SO=""/>
<Period PER_VON="1.01" PER_BIS="31.12" OEFF_VON="07:00" OEFF_BIS="21:00"
MO="" DI="" MI="" DO="" FR="" SA="X" SO=""/>
<Period PER_VON="1.01" PER_BIS="31.12" OEFF_VON="08:00" OEFF_BIS="18:00"
MO="" DI="" MI="" DO="" FR="" SA="" SO="X"/>
</OpenTime>
</Item>
</Data>
</Envelope>
35
4.3.11.2 Darstellung der Adresse und der Öffnungszeiten (Beispiel PickPost-Adressierung)
Langenthal Bahnhof SBB
Öffnungszeiten MODI MI DO FR SA SO
Eisenbahnstrasse 8
4900 Langenthal
06:10 –19:20 XXXXX
BE
06:30 –18:45X
X
Bern
Office de poste Lausanne 1 Dépôt
Avenue de la Gare 43 B
1003 Lausanne
VD
Waadt
Öffnungszeiten
MODI MI DO FR SA SO
08:00 –20:00 XXXXX
08:00 –16:00X
16:00 –19:00X
4.3.11.3 Darstellung der Adressierung der Sendungen
Name und Vorname des Empfängers
PickPost User ID
Eisenbahnstrasse 8
4900 Langenthal
Name und Vorname des Empfängers
MyPost24 User ID
MP EPFL
1015 Lausanne
36
(User ID ist mit dem Webservice «PickPost und My Post 24» bekannt)
(User ID ist mit dem Webservice «PickPost und My Post 24» bekannt)
5 Links
Alle Links auf einen Blick
PickPost
WasLink
Hauptseite für die Integration
www.post.ch/pickpost-mypost24 und
www.post.ch/pickpost-ts
Handbuch für die Integration Webservice «PickPost und My Post 24» inkl. Kartenapplikation«Standortsuche»
www.post.ch/pickpost-ts
(Klappmenü «Unterlagen für die Umsetzung»)
Teilnahmebedingungen PickPost / My Post 24
www.post.ch/pickpost-ts
(Klappmenü «Weitere Unterlagen»)
Webservice «Barcode»
WasLink
Hauptseite für die Integration
www.post.ch/barcode-ts
Handbuch Webservice «Barcode»
www.post.ch/barcode-ts
(Klappmenü «Dokumentation/Handbücher»)
Teilnahmebedingungen Webservice «Barcode»
www.post.ch/barcode-ts
(Klappmenü «Technische Dokumentationen»)
DataTransfer
WasLink
Hauptseite für die Integration
www.post.ch/datatransfer-ts
Handbuch DataTransfer und dazugehörige Anhänge (vor allem Anhang 1)
www.post.ch/datatransfer-ts
(Klappmenü «Paket/Express/Vinolog»
oder «Briefe mit Barcode»)
Teilnahmebedingungen DataTransfer
www.post.ch/datatransfer-ts
(Klappmenü «Paket/Express/Vinolog»
oder «Briefe mit Barcode»)
37
Post CH AG
PickPost / My Post 24
Wankdorfallee 4
3030 Bern
2623D
[email protected]
www.post.ch/pickpost
www.post.ch/mypost24
38