Transsmart hat eine aktive API-Version: APIv2. Dieser Artikel erklärt, wie diese integriert werden kann.

Transsmart verfügt außerdem über 3 öffentlich verfügbare Umgebungen. Diese finden Sie hier.

Die Beispiele in der nachfolgenden Dokumentation beziehen sich stets auf die User-Acceptance-Umgebung.

Abschnitte in diesem Artikel:

1. Authentication
   - 1.1 Token retrieval
   - 1.2 Token usage
   - 1.3 Token lifetime
2. Booking a shipment
   - 2.1 Request content
   - 2.2 Request example
3. Printing the label
   - 3.1 Trigger the print action
   - 3.2 SmartPrint

1. Authentication

Die APIv2 verwendet eine tokenbasierte Authentifizierung. Das bedeutet, dass vor dem Senden einer beliebigen Request zunächst ein neues Token abgerufen und anschließend für das Senden der folgenden Requests verwendet werden muss.

1.1 Token retrieval

Bevor ein Token abgerufen werden kann, benötigen Sie einen gültigen Benutzernamen und ein gültiges Passwort. Sprechen Sie mit Ihrem Transsmart-Kontakt, falls Sie diese noch nicht erhalten haben. Verbinden Sie sich über Basic Authentication mit https://accept-api.transsmart.com/login. Die Response ist ein JSON-formatierter Text, der ein einziges Name/Wert‑Paar enthält.

ue pair.

{"token": "eyJhbGciOiJIUzUxM...FHPrZw"}

1.2 Token usage

Jede weitere Anfrage, die Sie an die APIv2 senden, muss ein bestimmtes HTTP-Header-Feld enthalten: Authorization. Der Wert dieses Feldes muss der Token-Wert sein mit dem Präfix Bearer.

1.3 Token lifetime

Tokens haben eine begrenzte Lebensdauer von 24 Stunden.
Für Anwendungen, die in unsere Plattform integriert sind, ist dies unerheblich, da Tokens in der Regel zu Beginn eines Anwendungsprozesses abgerufen werden (z. B. eine Sendung buchen und drucken), für die nachfolgenden Aufrufe verwendet werden (z. B. Sendung buchen, Status prüfen, Etikettendruck auslösen) und nach Abschluss des Prozesses verworfen werden.

2 Booking a shipment

Durch das Buchen einer Sendung übermittelt Ihr System alle relevanten Informationen an unsere APIv2, die Transsmart-Plattform erledigt dann ihre Aufgaben und es passieren verschiedene Dinge, je nach der tatsächlichen Konfiguration Ihres Kontos. Im Folgenden finden Sie einige Beispiele für reale Anwendungsfälle:

1. Informationen werden an den Carrier weitergeleitet, der Carrier antwortet mit Labelinformationen, und die Labelinformationen werden als Teil der Response an Ihr System zurückgegeben.
    
2. Informationen werden in Transsmart gespeichert und nur in einem Manifest zu einem festen Zeitpunkt am Tag an den Carrier übermittelt, aber die Response enthält dennoch ein zu druckendes Label.
    
3. Informationen werden in Transsmart gespeichert und zur Erstellung eines Labels verwendet. Alle relevanten Informationen, die der Carrier benötigt, werden herausgefiltert und in einen Barcode übertragen, aus dem ein Label erzeugt wird. Durch das Drucken des Barcodes werden die Informationen an den Carrier übermittelt.
    
4. Informationen werden in Transsmart gespeichert, es werden keine Informationen an einen Carrier gesendet, und es wird lediglich ein Label erzeugt. Dies wird für Postlabels oder eigenen Transport verwendet

2.1 Request content

Eine Buchung besteht aus mehreren Informationsblöcken. Die meisten Informationen in diesen Blöcken stammen aus Ihrer Anwendung, die anderen Teile sind typischerweise Transsmart-Codes für Carrier, Service Levels usw.

Es gibt ein Ausnahmefeld: die Versandreferenz. Der Inhalt dieses Feldes muss für alle Sendungen, die Sie erstellen, eindeutig sein. In den meisten Fällen wird dies ein Autonummernwert aus Ihrer Anwendung sein. Neben den grundlegenden Versandinformationen (Adressen, Abholdatum und -uhrzeit, Paketinformationen usw.) müssen mehrere optionale Felder Werte enthalten, abhängig vom gewählten Carrier/Service Level/Service Option.

In den nächsten Abschnitten heben wir die wichtigsten Teile der Versandinformationen hervor. Am Ende ist ein vollständiges Beispiel für eine Request enthalten.

2.1.1 Shipment details

Dies ist der erste Teil der Request.

"reference": "TESTv2",
"carrier": "EEX",
"value": 25,
"valueCurrency": "EUR", 
"pickupDate": "2024-03-14", 
"service": "NON-DOCS", 
"serviceLevelTime": "EUROPLUS", 
"serviceLevelOther": "", 
"incoterms": "CPT", 
"numberOfPackages": 1, 
"measurements": { 
   "length": 30.0, 
   "width": 20.0, 
   "height": 10.0, 
   "weight": 1.0, 
   "linearUom": "CM", 
   "massUom": "KG" 
   } 

2.1.2 Address information

Als Nächstes folgen die Adressen. Grundsätzlich muss der Carrier wissen, wo die Sendung abgeholt werden soll und wohin sie geliefert werden muss. Diese Adresssegmente werden als SEND- und RECV-Adressen bezeichnet, entsprechend für Absender und Empfänger.

Es gibt 2 zusätzliche Adresstypen: INV für die Rechnung und 3PTY für die Abrechnungsdetails einer dritten Partei.

Unabhängig vom Typ kann jede Adresse dieselben Datenfelder enthalten.

"addresses": [ 
   { 
   "type": "RECV", 
   "name": "Transsmart",
   "addressLine1": "Ellen Pankhurststraat", 
   "addressLine2": "2de etage", 
   "houseNo": "1c", "city": "Tilburg", 
   "zipCode": "5032MD", 
   "country": "NL", 
   "contact": "Jan Voorbeeld", 
   "email": "jan@test.com" 
   }, { 
   "type": "SEND", 
   "name": "Transsmart B.V.", 
   "addressLine1": "Ellen Pankhurststraat", 
   "addressLine2": "1e verdieping Entrada", 
   "houseNo": "1A", 
   "city": "Tilburg", 
   "zipCode": "5032 MD", 
   "country": "NL", 
   "contact": "Piet Voorbeeld", 
   "email": piet@voorbeeld.NL 
   } 
]

2.1.3 Package details

Der nächste Block ist für die Paketdetails und enthält eine Zeile für jede Art von Paket. Ein Paket kann verschiedene Typen haben, zum Beispiel eine Palette oder eine Box.

Ein einzelnes Paket wird auch als Versandzeile bezeichnet. Sie können im Feld shipmentLineId eine eigene Kennung für das Paket vergeben.

Die quantity ist die Anzahl der einzelnen Pakete, die Sie versenden. Wenn Sie zum Beispiel 2 identische Kartons mit denselben Maßen versenden, können Sie quantity auf 2 setzen. Dadurch werden 2 Labels mit 2 unterschiedlichen Airwaybills erzeugt. Bitte beachten Sie, dass eine Response immer eine shipmentline pro Paket zurückgibt, auch wenn Sie quantity 2 angegeben haben. Dies liegt daran, dass jedes Paket seine eigene eindeutige Airwaybill (oder seinen eigenen Barcode) erhält.

"packages": [
   {
   "lineNo": 1,
   "packageType": "BOX", 
   "description": "Doos", 
   "shipmentLineId": "4567", 
   "quantity": 1, 
   "measurements": {
   "length": 30.00, 
   "width": 20.00, 
   "height": 10.00, 
   "weight": 1.00, 
   "linearUom": "CM", 
   "massUom": "KG" 
   } ] 

2.1.4 Delivery Hinweisinformationen

Jedes Paket kann Lieferscheininformationen enthalten. Diese Informationen sind nicht zwingend erforderlich, können jedoch in bestimmten Situationen für grenzüberschreitende Sendungen oder wenn Transsmart zusätzliche Dokumente wie Rechnungen oder Packzettel erstellen muss, benötigt werden.

2.2 Anfragebeispiel

Nachfolgend finden Sie ein vollständiges Beispiel dafür, wie eine einzelne Buchungsanfrage aussehen könnte.

{
"reference": "TESTv2",
"carrier": "EEX",
"value": 25,
"valueCurrency": "EUR",
"pickupDate": "2024-03-14",
"service": "NON-DOCS",
"serviceLevelTime": "EUROPLUS",
"serviceLevelOther": "",
"incoterms": "CPT",
"numberOfPackages": 1,
"measurements": {
   "length": 30.0,
   "width": 20.0,
   "height": 10.0,
   "weight": 1.0,
   "linearUom": "CM",
   "massUom": "KG"
   },
"addresses": [
   {
   "type": "RECV",
   "name": "Transsmart",
   "addressLine1": "Ellen Pankhurststraat",
   "addressLine2": "2de etage",
   "houseNo": "1c",
   "city": "Tilburg",
   "zipCode": "5032MD",
   "country": "NL",
   "contact": "Jan Example",
   "email": "jan@example.com"
   }, {
   "type": "SEND",
   "name": "Transsmart B.V.",
   "addressLine1": "Ellen Pankhurststraat",
   "addressLine2": "1e verdieping Entrada",
   "houseNo": "1A",
   "city": "Tilburg",
   "zipCode": "5032 MD",
   "country": "NL",
   "contact": "Piet Example",
   "email": "piet@example.NL"
   }
   ],
"packages": [
   {
   "lineNo": 1,
   "packageType": "BOX",
   "description": "Doos",
   "shipmentLineId": "4567",
   "quantity": 1,
   "measurements": {
      "length": 30.00,
      "width": 20.00,
      "height": 10.00,
      "weight": 1.00,
      "linearUom": "CM",
      "massUom": "KG"
      }
   }
   ]
}

3 Drucken des Labels

Die nachfolgende description gilt sowohl für Labels als auch für alle anderen Transportdokumente, die mit Ihren Sendungen verbunden sind.

3.1 Druckaktion auslösen

Es gibt drei Möglichkeiten, die Dokumente zu drucken:

1. Für eine bestehende Sendung die eigentlichen Dokumente abrufen und an den Drucker Ihrer Anwendung senden.
    
2. Für eine bestehende Sendung eine separate Druckanforderung senden und über SmartPrint drucken.
    
3. Für eine neue Sendung eine Booking-Anfrage einschließlich einer Druckaktion senden und über SmartPrint drucken

Nachfolgend finden Sie eine detaillierte Erläuterung jeder Option. Am Ende des Kapitels finden Sie zusätzliche Informationen zu SmartPrint, dem Transsmart-Drucktool.

3.1.1 Dokumentenabruf

Das Abrufen der Dokumente für eine bestimmte Sendung ist einfach. Senden Sie einfach eine Anfrage an v2/prints, wie in der Entwicklerdokumentation beschrieben, und setzen Sie den Parameter rawJob auf true.

Die Antwort enthält einen base64-codierten String. Der eigentliche Inhalt kann ZPL-Code oder ein PDF-Dokument sein, abhängig von Ihrer Kontokonfiguration.

3.1.2 Druckanforderung senden

Dies funktioniert genauso wie im vorherigen Abschnitt, mit der Ausnahme, dass der Parameter rawJob auf false gesetzt werden muss.

Auf diese Weise werden die zu druckenden Dokumente innerhalb von Transsmart in eine Queue gestellt, von SmartPrint, das in Ihrem Netzwerk installiert ist, abgeholt und so an Ihre Drucker gesendet.

3.1.3 Eine Druckaktion zusammen mit der Booking-Anfrage ausführen und über die Transsmart-Tools drucken.

Sehen Sie sich die Details der Booking-Anfrage an, wie in der Entwicklerdokumentation beschrieben. Um automatisch eine Druckaktion zum Zeitpunkt des Sendens der Booking-Anfrage auszulösen, müssen Sie den Pfad v2/shipments/BOOK in v2/shipments/PRINT ändern.

3.2 SmartPrint

SmartPrint ist das Transsmart Drucktool, das wir in unsere Plattform integriert haben.

Sie können die neueste Version über MyTranssmart herunterladen. Sobald Sie eingeloggt sind, klicken Sie auf das Printer-Symbol und wählen Sie den gewünschten Download aus. 

Weitere Informationen zu SmartPrint finden Sie hier.