Transsmart:lla on yksi aktiivinen API-versio: APIv2. Tämä artikkeli selittää, miten siihen integroidaan.

Transsmart:lla on myös 3 julkisesti saatavilla olevaa environmentia. Nämä löytyvät täältä.

Alla olevan dokumentaation esimerkit viittaavat aina user acceptance -environmentiin.

Tämän artikkelin osiot:

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 käyttää token-pohjaista autentikointia. Tämä tarkoittaa, että ennen minkä tahansa pyynnön lähettämistä on haettava uusi token, jota käytetään myöhempien pyyntöjen lähettämiseen.

1.1 Token retrieval

Ennen kuin tunniste voidaan hakea, tarvitset voimassa olevan käyttäjätunnuksen ja salasanan. Ota yhteyttä Transsmart-yhteyshenkilöösi, jos et ole vielä saanut näitä. Yhdistä osoitteeseen https://accept-api.transsmart.com/login käyttäen basic authenticationia. Vastaus on JSON-muotoista tekstiä, joka sisältää yhden name/value-parin.

ue pair.

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

1.2 Tokenin käyttö

Jokaisessa muussa APIv2:lle lähettämässäsi pyynnössä on oltava mukana tietty HTTP-header-kenttä: Authorization. Tämän kentän arvon tulee olla token-arvo, jonka edessä on etuliite Bearer.

1.3 Tokenin elinkaari

Tokeneilla on rajallinen, 24 tunnin elinkaari.
Alustaamme integroituville sovelluksille tämä on merkityksetöntä, koska tyypillisesti token haetaan sovellusprosessin alussa (esim. lähetyksen varaaminen ja tulostaminen), sitä käytetään myöhemmissä kutsuissa (esim. lähetyksen varaaminen, tilan tarkistaminen, osoitelapun tulostuksen käynnistäminen) ja se poistetaan prosessin valmistuttua.

2 Lähetyksen varaaminen

Lähetyksen varaamalla järjestelmäsi lähettää kaikki olennaiset tiedot APIv2:lle, minkä jälkeen Transsmart-alusta hoitaa loput, ja useita asioita tapahtuu tilisi varsinaisesta konfiguraatiosta riippuen. Alla on joitakin esimerkkejä todellisista käyttötapauksista:

1. Tiedot välitetään rahdinkuljettajalle, rahdinkuljettaja vastaa osoitelapputiedoilla ja osoitelapputiedot palautetaan järjestelmääsi osana vastausta.
    
2. Tiedot tallennetaan Transsmart-ympäristöön ja välitetään rahdinkuljettajalle vasta Manifestin mukana ennalta määritettyyn kellonaikaan päivän aikana, mutta vastaus sisältää silti tulostettavan osoitelapun.
    
3. Tiedot tallennetaan Transsmart-ympäristöön ja niitä käytetään osoitelapun luomiseen. Kaikki rahdinkuljettajan tarvitsemat oleelliset tiedot suodatetaan ja sijoitetaan viivakoodiin, josta osoitelappu muodostetaan. Viivakoodin tulostus siirtää tiedot rahdinkuljettajalle.
    
4. Tiedot tallennetaan Transsmart-ympäristöön, eikä tietoja lähetetä rahdinkuljettajalle, vaan luodaan ainoastaan osoitelappu. Tätä käytetään postilappuihin tai omaan kuljetukseen

2.1 Pyynnön sisältö

Varaus koostuu useista tietolohkoista. Suurin osa näiden lohkojen tiedoista tulee sovelluksestasi, ja muut osat ovat tyypillisesti rahdinkuljettajien, palvelutasojen jne. Transsmart-koodeja.

On yksi poikkeuskenttä: lähetysviite. Tämän kentän sisällön on oltava yksilöllinen kaikissa tekemissäsi lähetyksissä. Useimmissa tapauksissa tämä on sovelluksesi automaattisesti kasvava tunnus. Peruslähetystietojen (osoitteet, noutopäivä ja -aika, pakettitiedot jne.) lisäksi useissa valinnaisissa kentissä on oltava arvoja valitusta rahdinkuljettajasta/palvelutasosta/palveluvalinnasta riippuen.

Seuraavissa osioissa korostamme tärkeimpiä osia lähetystiedoista. Lopussa on mukana täydellinen esimerkkipyyntö.

2.1.1 Lähetyksen tiedot

Tämä on pyynnön ensimmäinen osa.

"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

Seuraavaksi tulevat osoitteet. Käytännössä rahdinkuljettajan on tiedettävä, mistä lähetys on noudettava ja minne se on toimitettava. Näitä osoitejaksoja kutsutaan SEND- ja RECV-osoitteiksi, vastaavasti lähettäjän ja vastaanottajan mukaan.

Lisäksi on 2 muuta osoitetyyppiä: INV laskutusta varten ja 3PTY kolmannen osapuolen laskutustietoja varten.

Tyypistä riippumatta jokainen osoite voi sisältää samat tietokentät.

"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

Seuraava lohko on paketin tietoja varten ja sisältää yhden rivin kutakin pakettityyppiä kohti. Paketti voi olla useaa tyyppiä, esimerkiksi lava tai laatikko.

Yksittäisestä paketista käytetään myös nimitystä lähetysrivi. Voit asettaa oman tunnisteesi paketille kenttään shipmentLineId.

Määrä on niiden yksittäisten pakettien lukumäärä, jotka olet lähettämässä. Esimerkiksi, jos lähetät 2 identtistä laatikkoa samoilla mitoilla, voit asettaa määräksi 2. Tämä luo 2 osoitelappua kahdella eri airwaybill-numerolla. Huomaa, että vastaus palauttaa aina yhden shipmentline-tietueen pakettia kohden, vaikka olisit antanut määräksi 2. Tämä johtuu siitä, että jokaisella paketilla on oma yksilöllinen airwaybill (tai viivakoodi).

"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

Jokainen pakkaus voi sisältää lähetyslistatietoja. Nämä tiedot eivät ole pakollisia, mutta niitä voidaan tarvita erityistilanteissa rajat ylittävissä lähetyksissä tai silloin, kun Transsmart joutuu laatimaan lisädokumentteja, kuten laskuja tai pakkausluetteloita.

2.2 Pyyntöesimerkki

Alla on täydellinen esimerkki siitä, miltä yksi varauspyyntö voi näyttää.

{
"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 Osoitelapun tulostaminen

Alla oleva description koskee sekä osoitelappuja että kaikkia muita lähetyksiisi liittyviä kuljetusasiakirjoja.

3.1 Käynnistä tulostustoiminto

Asiakirjat voidaan tulostaa kolmella tavalla:

1. Hae olemassa olevalle lähetykselle kuuluvat varsinaiset asiakirjat ja lähetä ne sovelluksesi tulostimelle.
    
2. Lähetä olemassa olevalle lähetykselle erillinen tulostuspyyntö ja tulosta SmartPrintin kautta.
    
3. Lähetä uudelle lähetykselle varauspyyntö, joka sisältää tulostustoiminnon, ja tulosta SmartPrintin kautta

Alta löydät yksityiskohtaisen selityksen jokaisesta vaihtoehdosta. Kappaleen lopusta löytyy lisätietoja SmartPrintistä, Transsmart-tulostustyökalusta.

3.1.1 Asiakirjojen haku

Tietyn lähetyksen asiakirjojen hakeminen on helppoa. Lähetä vain pyyntö resurssiin v2/prints kehittäjädokumentaatiossa kuvatulla tavalla ja aseta rawJob-parametrin arvoksi true.

Vastaus sisältää base64-koodatun merkkijonon. Varsinainen sisältö voi olla zpl-koodia tai pdf-asiakirja tilisi asetuksista riippuen.

3.1.2 Tulostuspyynnön lähettäminen

Tämä toimii täsmälleen samalla tavalla kuin edellisessä kappaleessa, mutta rawJob-parametri tulee asettaa arvoon false.

Tällä tavalla tulostettavat asiakirjat jonotetaan Transsmart-ympäristössä, ne noudetaan verkkoosi asennetun SmartPrintin toimesta ja lähetetään sitä kautta tulostimillesi.

3.1.3 Anna tulostustoiminto yhdessä varauksen kanssa ja tulosta Transsmart-työkalujen avulla.

Tutustu varauspyynnön yksityiskohtiin kehittäjädokumentaatiossa. Jos haluat käynnistää tulostustoiminnon automaattisesti varauspyynnön lähettämisen yhteydessä, sinun on muutettava polku v2/shipments/BOOK arvoon v2/shipments/PRINT.

3.2 SmartPrint

SmartPrint on Transsmart-tulostustyökalu, jonka olemme integroineet alustallemme.

Voit ladata uusimman version MyTranssmartin kautta. Kirjauduttuasi sisään napsauta Printer-kuvaketta ja valitse haluamasi lataus.

Lisätietoja SmartPrintistä löytyy täältä.