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:
-
Authentication
- 1.1 Token retrieval
- 1.2 Token usage
- 1.3 Token lifetime -
Booking a shipment
- 2.1 Request content
- 2.2 Request example -
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:
- Tiedot välitetään rahdinkuljettajalle, rahdinkuljettaja vastaa osoitelapputiedoilla ja osoitelapputiedot palautetaan järjestelmääsi osana vastausta.
- 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.
- 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.
- 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"
}
| Kenttä | Description |
| reference | Lähetyksesi yksilöllinen viite. |
| carrier | Valittu kuljetusliike. |
| value | Lähetyksen arvo. |
| valueCurrency | Lähetyksen arvon valuutta. |
| pickupDate | Kuljetusliikkeelle pyydetty noutopäivä. |
| service | Ilmaisee, koostuuko lähetys asiakirjoista vai muista kuin asiakirjoista. Sallittuja arvoja ovat DOCS ja NON-DOCS. |
| serviceLevelTime | Valitun kuljetusliikkeen palvelutaso. |
| serviceLevelOther | Valitun kuljetusliikkeen palvelutasoasetus. |
| incoterms | Incoterms-ehto, jonka mukaisesti lähetys lähetetään. |
| numberOfPackages | Lähetykseen sisältyvien pakkausten lukumäärä. |
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
}
]
| Field | Description |
| type | Osoitteen tyyppi. Sallittuja arvoja ovat SEND, RECV, INV tai 3PTY. |
| Name | Osoitteen nimi. |
| addressLine1 | Ensimmäinen osoiterivi, yleensä kadunnimi. |
| addressLine2 | Toinen osoiterivi, jota käytetään lisäosoitetietoihin, esim. rakennuksen nimi, kerros jne. |
| houseNo | Talonnumeron tieto. |
| city | Kaupunki. |
| zipCode | Postinumero. |
| country | Maa ISO 2 -muodossa, lisätietoja: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2 |
| contact | Yhteyshenkilön nimi. |
| Sähköpostiosoite. |
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"
} ]
| Kenttä | Description |
| lineNo | Paketin rivinumero. Arvon on oltava kokonaisluku, ja sen tulee kasvaa ilman aukkoja kaikilla seuraavilla riveillä. |
| packageType | Paketin tyyppi. Perusarvot ovat BOX, PARCEL, PALLET. |
| description | Paketin tyypin description omaa tarkoitustasi varten. |
| shipmentLineId | Oma tunnisteesi tälle lähetysriville. |
| quantity | Sellaisten pakettien lukumäärä, joilla on täsmälleen samat ominaisuudet. |
| length | Paketin pituus. |
| width | Paketin leveys. |
| height | Paketin korkeus. |
| weight | Paketin paino. |
| linearUom | Pituuden, leveyden ja korkeuden mittayksikkö. Sallittuja arvoja ovat: CM, FT, IN, YD |
| massUom | Painon mittayksikkö. Sallittuja arvoja ovat: KG, LB, OZ |
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:
- Hae olemassa olevalle lähetykselle kuuluvat varsinaiset asiakirjat ja lähetä ne sovelluksesi tulostimelle.
- Lähetä olemassa olevalle lähetykselle erillinen tulostuspyyntö ja tulosta SmartPrintin kautta.
- 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ä.