Transsmart har én aktiv API-versjon: APIv2. Denne artikkelen forklarer hvordan du integrerer med den.

Transsmart har også 3 offentlig tilgjengelige miljøer. Disse finnes her.

Eksemplene i dokumentasjonen nedenfor vil alltid referere til user acceptance-miljøet.

Seksjoner i denne artikkelen:

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 bruker token-basert Authentication. Dette betyr at før noen forespørsel kan sendes, må et nytt token hentes og brukes til å sende de påfølgende forespørslene.

1.1 Token retrieval

Før et token kan hentes, trenger du et gyldig username og password. Snakk med din Transsmart-kontakt hvis du ennå ikke har mottatt dette. Koble til https://accept-api.transsmart.com/login med basic authentication. Responsen vil være en JSON-formatert tekst som inneholder et enkelt name/val

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

1.2 Token-bruk

Alle andre forespørsler som du sender til APIv2 må inneholde et spesifikt HTTP header-felt: Authorization. Verdien i dette feltet må være token-verdien, med prefikset Bearer.

1.3 Token-levetid

Tokens har en begrenset levetid på 24 timer.
For applikasjoner som integrerer med vår plattform er dette irrelevant, fordi tokens typisk hentes i starten av en applikasjonsprosess (f.eks. booke og skrive ut en forsendelse), brukes for de påfølgende kallene (f.eks. booke forsendelse, sjekke status, opprette etikettutskrift) og forkastes etter at prosessen er fullført.

2 Booke en forsendelse

Ved å booke en forsendelse sender systemet ditt all relevant informasjon til vår APIv2, Transsmart-plattformen gjør deretter sitt og en rekke ting skjer, alt avhengig av den faktiske konfigurasjonen av kontoen din. Nedenfor er noen eksempler på faktiske brukstilfeller:

1. Informasjon sendes videre til transportøren, transportøren svarer med label‑informasjon, og label‑informasjonen returneres til systemet ditt som en del av responsen.
    
2. Informasjon lagres i Transsmart og sendes kun videre til transportøren i et Manifest på et fast tidspunkt i løpet av dagen, men responsen vil likevel inneholde en label som skal skrives ut.
    
3. Informasjon lagres i Transsmart og brukes til å lage en label. All relevant informasjon transportøren trenger, filtreres ut og legges i en strekkode som genererer en label. Utskrift av strekkoden vil overføre informasjonen til transportøren.
    
4. Informasjon lagres i Transsmart og ingen informasjon sendes til en transportør, det genereres kun en label. Dette brukes for postetiketter eller egen transport

2.1 Innhold i forespørsel

En booking består av flere informasjonsblokker. Mesteparten av informasjonen i disse blokkene kommer fra applikasjonen din, de andre delene er typisk Transsmart‑koder for transportører, servicenivåer osv.

Det finnes ett unntaksfelt: sendingreferansen. Innholdet i dette feltet må være unikt for alle sendingene du oppretter. I de fleste tilfeller vil dette være en autonummer‑verdi fra applikasjonen din. I tillegg til grunnleggende informasjon om sendingen (adresser, hente­dato og ‑tid, pakkeinformasjon osv.) må flere valgfrie felt inneholde verdier avhengig av valgt transportør/servicenivå/servicealternativ.

I de neste avsnittene vil vi fremheve de viktigste delene av informasjonen om sendingen. Til slutt er det tatt med et fullstendig eksempel på en forespørsel.

2.1.1 Sendingdetaljer

Dette er den første delen av forespørselen.

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

Deretter kommer adressene. I bunn og grunn må transportøren vite hvor forsendelsen skal hentes, og hvor den skal leveres. Disse adresse-delene kalles SEND- og RECV-adresser, fra avsender og mottaker henholdsvis.

Det finnes 2 ekstra adressetyper: INV for fakturaen og 3PTY for faktureringsdetaljer til tredjepart.

Uavhengig av type kan alle adresser inneholde de samme datafeltene.

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

Den neste blokken er for pakkedetaljer og inneholder én linje for hver type pakke. En pakke kan være av flere typer, for eksempel en pall eller en eske.

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

Kvantitet er antall unike kolli du sender. For eksempel, hvis du sender 2 identiske esker med samme mål, kan du sette kvantitet til 2. Dette vil generere 2 etiketter med 2 forskjellige airwaybills. Vennligst merk at et svar alltid vil gi én shipmentline per kolli selv om du har oppgitt kvantitet 2. Dette er fordi hvert kolli vil ha sin egen unike airway bill (eller strekkode).

"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 notat­informasjon

Hver pakke kan inneholde følgeseddelinformasjon. Denne informasjonen er ikke obligatorisk, men kan være nødvendig i bestemte situasjoner for grensekryssende forsendelser eller når Transsmart må lage tilleggsdokumentasjon som fakturaer eller pakksedler.

2.2 Forespørselseksempel

Nedenfor er et komplett eksempel på hvordan en enkelt booking-forespørsel 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 Skrive ut etiketten

description nedenfor er gyldig for både etiketter og alle andre transportdokumenter som er knyttet til forsendelsene dine.

3.1 Utløs utskriftsaksjonen

Det finnes tre måter å skrive ut dokumentene på:

1. For en eksisterende forsendelse, hent de faktiske dokumentene og send dem til skriveren som er koblet til applikasjonen din.
    
2. For en eksisterende forsendelse, send en egen utskriftsforespørsel og skriv ut via SmartPrint.
    
3. For en ny forsendelse, send en bookingforespørsel som inkluderer en utskriftsaksjon og skriv ut via SmartPrint

Nedenfor finner du en detaljert forklaring av hvert alternativ. På slutten av kapitlet finnes det tilleggsinformasjon om SmartPrint, Transsmart utskriftsverktøyet.

3.1.1 Henting av dokumenter

Å hente dokumentene for en bestemt forsendelse er enkelt. Send bare en forespørsel til v2/prints som beskrevet i utviklerdokumentasjonen, og sett parameteren rawJob til true.

Svaret vil inneholde en base64-kodet streng. Det faktiske innholdet kan være zpl-kode eller et pdf-dokument, avhengig av kontokonfigurasjonen din.

3.1.2 Send utskriftsforespørsel

Dette fungerer nøyaktig som i forrige avsnitt, bortsett fra at rawJob-parameteren må settes til false.

På denne måten blir dokumentene som skal skrives ut satt i kø i Transsmart, hentet av SmartPrint installert i nettverket ditt, og sendt videre til skriverne dine.

3.1.3 Gi en utskriftsaksjon sammen med bookingen og skriv ut via Transsmart-verktøyene.

Se på detaljene for bookingforespørselen som beskrevet i utviklerdokumentasjonen. For automatisk å utløse en utskriftsaksjon i det øyeblikket du sender bookingforespørselen, må du endre stien v2/shipments/BOOK til v2/shipments/PRINT.

3.2 SmartPrint

SmartPrint er Transsmart utskriftsverktøyet som vi har integrert i plattformen vår.

Du kan laste ned den nyeste versjonen via MyTranssmart. Når du er logget inn, klikker du på Printer-ikonet og velger ønsket nedlasting.

Mer informasjon om SmartPrint finner du her.