Transsmart har én aktiv API-version: APIv2. Denne artikel forklarer, hvordan du integrerer med den.

Transsmart har også 3 offentligt tilgængelige miljøer. Disse kan findes her.

Eksemplerne i dokumentationen nedenfor vil altid referere til user acceptance-miljøet.

Afsnit i denne 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

APIv2 bruger token-baseret authentication. Det betyder, at før nogen request kan sendes, skal der først hentes et nyt token, som derefter bruges til at sende de efterfølgende requests.

1.1 Token retrieval

Før en token kan hentes, skal du have et gyldigt brugernavn og en gyldig adgangskode. Tal med din Transsmart-kontakt, hvis du endnu ikke har modtaget disse. Opret forbindelse til https://accept-api.transsmart.com/login med basic authentication. Svaret vil være en JSON-formateret tekst, der indeholder ét enkelt name/value-par.

ue pair.

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

1.2 Brug af token

Alle øvrige forespørgsler, som du sender til APIv2, skal indeholde et specifikt HTTP-headerfelt: Authorization. Værdien af dette felt skal være token-værdien med præfikset Bearer.

1.3 Tokenets levetid

Tokens har en begrænset levetid på 24 timer.
For applikationer, der integrerer med vores platform, er dette uden praktisk betydning, fordi tokens typisk hentes i begyndelsen af en applikationsproces (f.eks. bestille og udskrive en forsendelse), bruges til de efterfølgende kald (f.eks. bestille forsendelse, kontrollere status, udstede labeludskrift) og kasseres, når processen er afsluttet.

2 Bestilling af en forsendelse

Når du bestiller en forsendelse, sender dit system alle relevante oplysninger til vores APIv2, hvorefter Transsmart-platformen gør sit arbejde, og en række ting sker, alt afhængigt af den konkrete konfiguration af din konto. Nedenfor er nogle eksempler på faktiske anvendelsesscenarier:

1. Information videresendes til carrier, carrier svarer med labeloplysninger, og labeloplysninger returneres til dit system som en del af svaret.
    
2. Information gemmes i Transsmart og videresendes kun til carrier i et Manifest på et fast tidspunkt i løbet af dagen, men svaret vil alligevel indeholde en label, der skal udskrives.
    
3. Information gemmes i Transsmart og bruges til at oprette en label. Al relevant information, som carrier har brug for, filtreres ud og placeres i en stregkode, som genererer en label. Udskrivning af stregkoden overfører informationen til carrier.
    
4. Information gemmes i Transsmart, der sendes ingen information til en carrier, og der genereres kun en label. Dette bruges til postlabels eller egen transport

2.1 Indhold af request

En booking består af flere informationsblokke. Det meste af informationen i disse blokke kommer fra din applikation, de øvrige dele er typisk Transsmart-koder for carriers, service levels osv.

Der er ét undtagelsesfelt: shipment reference. Indholdet af dette felt skal være unikt på tværs af alle de forsendelser, du opretter. I de fleste tilfælde vil dette være en autonummer-værdi fra din applikation. Ud over den grundlæggende forsendelsesinformation (adresser, afhentningsdato og -tid, pakkeinformation osv.) skal flere valgfrie felter indeholde værdier afhængigt af den valgte carrier/service level/service option.

I de næste afsnit fremhæver vi de vigtigste dele af forsendelsesinformationen. Til sidst er der inkluderet et fuldt eksempel på en request.

2.1.1 Forsendelsesdetaljer

Dette er den første del af 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 Address information

Næste er adresserne. Grundlæggende skal transportøren vide, hvor forsendelsen skal afhentes, og hvor den skal leveres. Disse adresseafsnit kaldes SEND- og RECV-adresserne, fra afsender og modtager henholdsvis.

Der er 2 yderligere adressetyper: INV til fakturaen og 3PTY til 3.-parts faktureringsoplysninger.

Uanset typen kan hver adresse indeholde de samme datafelter.

"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

Det næste blokafsnit er til pakkedetaljerne og indeholder én linje for hver type pakke. En pakke kan være af flere typer, for eksempel en palle eller en kasse.

En enkelt pakke omtales også som en shipment line. Du kan angive din egen identifikator for pakken i feltet shipmentLineId.

Mængden er antallet af unikke pakker, du sender. For eksempel, hvis du sender 2 identiske kasser med de samme mål, kan du sætte quantity til 2. Dette vil generere 2 labels med 2 forskellige airwaybills. Bemærk venligst, at et svar altid vil give en shipmentline pr. pakke, selvom du har angivet quantity 2. Dette skyldes, at hver pakke vil have sin egen unikke airway bill (eller stregkode).

"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 note information

Hver pakke kan indeholde følgeseddeloplysninger. Disse oplysninger er ikke obligatoriske, men kan være nødvendige i særlige situationer ved grænseoverskridende forsendelser eller når Transsmart skal udarbejde yderligere dokumentation som fakturaer eller pakkesedler.

2.2 Eksempel på request

Nedenfor vises et komplet eksempel på, hvordan en enkelt booking-request kan se ud.

{
"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 Udskrivning af label

description nedenfor er gyldig for både labels og alle andre transportdokumenter, der vedrører dine forsendelser.

3.1 Udløs udskrivningshandlingen

Der er tre måder at udskrive dokumenterne på:

1. For en eksisterende forsendelse skal du hente de faktiske dokumenter og sende dem til printeren via din applikation.
    
2. For en eksisterende forsendelse skal du sende en separat udskrivningsanmodning og udskrive via SmartPrint.
    
3. For en ny forsendelse skal du sende en bookinganmodning, der inkluderer en udskrivningshandling, og udskrive via SmartPrint

Nedenfor finder du en detaljeret forklaring af hver mulighed. I slutningen af kapitlet er der ekstra information om SmartPrint, Transsmart-udskrivningsværktøjet.

3.1.1 Dokumenthentning

Det er nemt at hente dokumenterne for en bestemt forsendelse. Send blot en anmodning til v2/prints som beskrevet i udviklerdokumentationen, og sæt parameteren rawJob til true.

Svaret vil indeholde en base64-kodet streng. Det faktiske indhold kan være zpl-kode eller et pdf-dokument, afhængigt af din konto-konfiguration.

3.1.2 Send udskrivningsanmodning

Dette fungerer præcis som i det foregående afsnit, bortset fra at parameteren rawJob skal sættes til false.

På denne måde sættes de dokumenter, der skal udskrives, i kø i Transsmart, hentes af SmartPrint installeret i dit netværk og sendes til dine printere den vej.

3.1.3 Giv en udskrivningshandling sammen med bookingen og udskriv via Transsmart-værktøjerne.

Se på detaljerne for bookinganmodningen som beskrevet i udviklerdokumentationen. For automatisk at udløse en udskrivningshandling i det øjeblik, du sender bookinganmodningen, skal du ændre stien v2/shipments/BOOK til v2/shipments/PRINT.

3.2 SmartPrint

SmartPrint er Transsmart-udskrivningsværktøjet, som vi har integreret i vores platform.

Du kan downloade den seneste version via MyTranssmart. Når du er logget ind, skal du klikke på Printer-ikonet og vælge det ønskede download. 

Mere information om SmartPrint kan findes her.