API-Dokumentation

Kurz und knapp

Die REST-API von Shipper verbindet Ihren Onlineshop, Ihr ERP oder Ihre Logistiksoftware mit Ihrem Shipper-Konto. Damit können Sie:

• mit einer Anfrage die Angebote mehrerer Transporteure einholen;
• die Sendung zum gewählten Angebot bestellen;
• Etiketten, Rechnung und Zolldokumente herunterladen;
• eine Sendung verfolgen und stornieren.

Sie geben die Zugänge in Ihrem Shipper-Konto frei. Ihr Entwickler baut die Anbindung in einer Testumgebung, der Sandbox, danach wechseln Sie in die Produktion.

Start in 4 Schritten

1. Laden Sie Ihren Entwickler in die Sandbox ein

   Geben Sie unter Kontodaten › API, Bereich «Zugang zur Entwicklungsumgebung», die E-Mail-Adresse Ihres Entwicklers ein. Er erhält eine Einladung, wählt sein Passwort und meldet sich mit dieser Adresse in der Sandbox an.

   Die Sandbox ist vollständig fiktiv: Ihr Entwickler hat weder Zugriff auf Ihr Konto noch auf Ihre Daten. Um ihm den Zugang zu entziehen, löschen Sie seine Adresse; um die Sandbox jemand anderem zu geben, ersetzen Sie sie. Die entfernte Person wird per E-Mail informiert.

2. Entwickeln und testen

   In der Sandbox erfasst Ihr Entwickler eine Rechnungsadresse, lädt Guthaben auf (fiktive Zahlungen) und erstellt dann seinen Schlüssel unter Kontodaten › API. Danach kann er Offerten anfragen und Testsendungen bestellen, ohne dass etwas verschickt wird.

3. Beantragen Sie die Produktion

   Ist die Anbindung bereit, öffnen Sie Kontodaten › API in Ihrem Shipper-Konto und klicken auf «Antrag auf Produktionsfreigabe». Ein Ticket begleitet den Antrag; rechnen Sie mit 48 bis 72 Stunden. Sie werden benachrichtigt, sobald der Zugang aktiv ist.

4. Erstellen Sie Ihre Produktionsschlüssel

   Sobald der Zugang aktiv ist, erzeugt «Einen Schlüssel hinzufügen» einen Schlüssel mit Passwort. Das Passwort wird nur einmal angezeigt: Notieren Sie es, sonst müssen Sie einen neuen Schlüssel erstellen.

   Jeder Schlüssel lässt sich auf eine Liste von IP-Adressen beschränken, die später änderbar ist. Sie können beliebig viele Schlüssel erstellen, zum Beispiel einen pro System.

Server

Die Schlüssel gelten nur in ihrer Umgebung: Ein Sandbox-Schlüssel funktioniert nicht in der Produktion.

Authentifizierung

Jede Anfrage authentifiziert sich per HTTP Basic mit Schlüssel und Passwort: Header Authorization: Basic, gefolgt von Schlüssel:Passwort in Base64. HTTP-Werkzeuge erledigen das für Sie:

curl -u "IHR_SCHLUESSEL:IHR_PASSWORT" \
     -H "Accept: application/json" \
     https://api.sandbox.shipper.ch/quotation/12345

Ein auf IP-Adressen beschränkter Schlüssel lehnt Anfragen von anderswo ab. Bewahren Sie das Passwort auf Ihrem Server auf: nie im JavaScript einer Webseite und nie in einer Anwendung, die bei Ihren Kunden installiert ist.

Ablauf einer Sendung

1. Offerte: Senden Sie Absender, Empfänger und Pakete an POST /quotation. Die Antwort enthält eine quotationId und die Angebote der Transporteure.
2. Auswahl: Wählen Sie das passende Angebot (seine quoteId).
3. Bestellung: POST /order mit der quoteId, dem Abholdatum und, wenn die Sendung verzollt wird, den Zollartikeln.
4. Dokumente: GET /order/{orderId}/document/{type} liefert die Datei: labels (Etiketten), invoice (Rechnung) oder customs (Zoll).
5. Tracking: GET /order/{orderId}/tracking.

Routen

• POST /quotation Offerte erstellen (Angebote mehrerer Transporteure)
• GET /quotation/{quotationId} Offerte abrufen
• POST /order Sendung zu einem Angebot bestellen
• GET /order/{orderId} Bestellung abrufen
• GET /order/{orderId}/tracking Sendung verfolgen
• GET /order/{orderId}/document/{type} Dokument herunterladen
• GET /order/{orderId}/cancel Bestellung stornieren

Felder, erlaubte Werte und vollständige Beispiele: API-Referenz.

Anfragen und Antworten

POST-Anfragen senden einen JSON-Body (Content-Type: application/json); GET-Anfragen übergeben ihre Parameter in der Adresse. Fordern Sie JSON als Antwort mit Accept: application/json an.

Ausser bei einem heruntergeladenen Dokument (der Body ist dann die Datei) ist die Antwort ein JSON-Objekt, das immer header enthält: error und endpoint, bei einem Fehler zusätzlich errorCode, errorMessage und errorField. Der HTTP-Code zeigt das Ergebnis:

Produktangaben für die EU

Für eine Sendung aus der Schweiz (oder einem anderen Land ausserhalb der EU) an eine Privatperson in der EU verlangt die EU zwei Angaben pro Zollartikel:

• merchantProductId: Ihre Artikelnummer (SKU);
• manufacturerProductId: die Herstellernummer (Modell- oder Teilenummer). Stellen Sie das Produkt selbst her, geben Sie Ihre Artikelnummer an.

standardProductId (GTIN- oder EAN-Code) ist freiwillig. Der Empfänger ist eine Privatperson, wenn quotation.to.isCompany den Wert false hat.

In Ihrem Kundenbereich

Über die API angefragte Offerten erscheinen unter Ihren Offerten, mit Absender, Empfänger und angebotenen Tarifen. Über die API bestellte Sendungen erscheinen unter Ihren Sendungen, mit «API» markiert; ein Filter trennt sie von den Sendungen auf der Website.

Hilfe

Eine Frage zur Anbindung? Eröffnen Sie in Ihrem Konto ein Ticket oder schreiben Sie uns an E-Mail: Unser technisches Team antwortet Ihnen.