Transsmart har en aktiv API-version: APIv2. Den här artikeln förklarar hur du integrerar med den.

Transsmart har också 3 publikt tillgängliga miljöer. Dessa finns beskrivna här.

Exemplen i dokumentationen nedan kommer alltid att referera till user acceptance-miljön.

Avsnitt i denna artikel:

1. Authentication
   - 1.1 Hämtning av token
   - 1.2 Användning av token
   - 1.3 Token-livslängd
2. Boka en försändelse
   - 2.1 Innehåll i request
   - 2.2 Exempel på request
3. Skriva ut etiketten
   - 3.1 Trigga utskriftsåtgärden
   - 3.2 SmartPrint

1. Authentication

APIv2 använder token-baserad Authentication. Detta innebär att innan någon request kan skickas måste en ny token hämtas och användas för att skicka efterföljande requests.

1.1 Hämtning av token

Innan en token kan hämtas behöver du ett giltigt username och password. Kontakta din Transsmart-kontakt om du inte har fått dessa ännu. Anslut till https://accept-api.transsmart.com/login med basic authentication. Svaret kommer att vara en JSON-formaterad text som innehåller ett enda name/val

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

1.2 Tokenanvändning

Varje annan request som du skickar till APIv2 måste innehålla ett specifikt HTTP header-fält: Authorization. Värdet i detta fält måste vara token-värdet, prefixat med Bearer.

1.3 Tokenlivslängd

Tokens har en begränsad livslängd på 24 timmar.
För applikationer som integrerar med vår plattform är detta irrelevant, eftersom tokens normalt hämtas i början av en applikationsprocess (t.ex. boka och skriva ut en sändning), används för de efterföljande calls (t.ex. boka sändning, kontrollera status, skriva ut etikett) och släpps när processen är slutförd.

2 Boka en sändning

När du bokar en sändning skickar ditt system all relevant information till vår APIv2, Transsmart-plattformen gör sedan sitt jobb och ett antal saker händer, allt beroende på den faktiska konfigurationen av ditt konto. Nedan följer några exempel på faktiska användningsfall:

1. Informationen vidarebefordras till transportören, transportören svarar med etikettsinformation och etikettsinformationen returneras till ditt system som en del av svaret.
    
2. Informationen lagras i Transsmart och vidarebefordras endast till transportören i ett Manifest vid en fast tidpunkt under dagen, men svaret kommer ändå att innehålla en etikett som ska skrivas ut.
    
3. Informationen lagras i Transsmart och används för att skapa en etikett. All relevant information som transportören behöver filtreras ut och läggs i en streckkod som genererar en etikett. Utskrift av streckkoden överför informationen till transportören.
    
4. Informationen lagras i Transsmart och ingen information skickas till en transportör utan endast en etikett genereras. Detta används för postetiketter eller egen transport

2.1 Innehåll i Request

En bokning består av flera informationsblock. Merparten av informationen i dessa block kommer från din applikation, de andra delarna är typiskt Transsmart-koder för transportörer, servicenivåer osv.

Det finns ett undantagsfält: sändningsreferensen. Innehållet i detta fält måste vara unikt för alla sändningar du gör. I de flesta fall kommer detta att vara ett autonummer-värde från din applikation. Förutom den grundläggande sändningsinformationen (adresser, hämtningstid och datum, paketinformation osv.) måste flera valfria fält innehålla värden beroende på vald transportör/servicenivå/servicealternativ.

I nästa avsnitt lyfter vi fram de viktigaste delarna av sändningsinformationen. I slutet finns ett komplett exempel på en request.

2.1.1 Sändningsdetaljer

Detta är den första delen av requesten.

"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 Adressinformation

Näst följer adresserna. I grunden behöver transportören veta var sändningen ska hämtas upp och var den ska levereras. Dessa adresssegment kallas SEND- och RECV-adresser, från avsändare respektive mottagare.

Det finns 2 ytterligare adresstyper: INV för fakturan och 3PTY för faktureringsuppgifter till tredje part.

Oavsett typ kan varje adress innehålla samma datafält.

"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 Paketdetaljer

Nästa block är för paketdetaljer och innehåller en rad för varje typ av paket. Ett paket kan vara av flera typer, till exempel en pall eller en låda.

Ett enskilt paket kallas även en shipment line. Du kan ange din egen identifierare för paketet i fältet shipmentLineId.

Kvantiteten är antalet unika kollin du skickar. Till exempel, om du skickar 2 identiska lådor med samma mått kan du ange kvantitet som 2. Detta kommer att generera 2 etiketter med 2 olika airwaybills. Observera att ett svar alltid kommer att ge en shipmentline per kolli även om du har angett kvantitet 2. Detta beror på att varje kolli kommer att ha sin egen unika airway bill (eller streckkod).

"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 anteckningsinformation

Varje kolli kan innehålla följesedelsinformation. Denna information är inte obligatorisk, men kan behövas i särskilda situationer för gränsöverskridande försändelser eller när Transsmart måste ta fram ytterligare dokumentation, till exempel fakturor eller packsedlar.

2.2 Exempel på request

Nedan visas ett komplett exempel på hur en enskild bokningsrequest kan se ut.

{
"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 Utskrift av etiketten

description nedan gäller både etiketter och alla andra transportdokument som är kopplade till dina försändelser.

3.1 Utlösa utskriftsåtgärden

Det finns tre sätt att skriva ut dokumenten:

1. För en befintlig försändelse, hämta de faktiska dokumenten och skicka dem till skrivaren som används av din applikation.
    
2. För en befintlig försändelse, skicka en separat utskriftsbegäran och skriv ut via SmartPrint.
    
3. För en ny försändelse, skicka en bokningsbegäran som inkluderar en utskriftsåtgärd och skriv ut via SmartPrint

Nedan hittar du en detaljerad förklaring av varje alternativ. I slutet av kapitlet finns extra information om SmartPrint, Transsmart-utskriftsverktyget.

3.1.1 Dokumenthämtning

Att hämta dokumenten för en specifik försändelse är enkelt. Skicka helt enkelt en begäran till v2/prints enligt beskrivningen i utvecklardokumentationen och sätt parametern rawJob till true.

Svaret kommer att innehålla en base64-kodad sträng. Det faktiska innehållet kan vara zpl-kod eller ett pdf-dokument, beroende på din kontokonfiguration.

3.1.2 Skicka utskriftsbegäran

Detta fungerar exakt som i föregående avsnitt, med undantag för parametern rawJob som måste sättas till false.

På detta sätt köas dokumenten som ska skrivas ut i Transsmart, hämtas av SmartPrint som är installerat i ditt nätverk och skickas till dina skrivare på det sättet.

3.1.3 Ge en utskriftsåtgärd tillsammans med bokningen och skriv ut via Transsmart-verktygen.

Titta på detaljerna för bokningsbegäran enligt beskrivningen i utvecklardokumentationen. För att automatiskt utlösa en utskriftsåtgärd i samma ögonblick som du skickar bokningsbegäran behöver du ändra sökvägen v2/shipments/BOOK till v2/shipments/PRINT.

3.2 SmartPrint

SmartPrint är Transsmart-utskriftsverktyget som vi har integrerat i vår plattform.

Du kan ladda ner den senaste versionen via MyTranssmart. När du är inloggad klickar du på Printer-ikonen och väljer önskad nedladdning.

Mer information om SmartPrint finns här.