Transsmart heeft één actieve API-versie: APIv2. Dit artikel legt uit hoe u hiermee integreert.

Transsmart heeft ook 3 publiek beschikbare omgevingen. Deze kunt u hier vinden.

De voorbeelden in de onderstaande documentatie verwijzen altijd naar de user acceptance-omgeving.

Secties in dit artikel:

1. Authenticatie
   - 1.1 Token ophalen
   - 1.2 Token gebruiken
   - 1.3 Token-levensduur
2. Een zending boeken
   - 2.1 Inhoud van de request
   - 2.2 Request-voorbeeld
3. Het label afdrukken
   - 3.1 De printactie triggeren
   - 3.2 SmartPrint

1. Authenticatie

APIv2 gebruikt tokengebaseerde authenticatie. Dit betekent dat, voordat een request kan worden verstuurd, eerst een nieuw token moet worden opgehaald en gebruikt voor het versturen van de daaropvolgende requests.

1.1 Token ophalen

Voordat een token opgehaald kan worden, heeft u een geldig username en password nodig. Neem contact op met uw Transsmart-contactpersoon als u deze nog niet hebt ontvangen. Maak verbinding met https://accept-api.transsmart.com/login met basic authentication. De response is JSON-geformatteerde tekst met één name/value-pair.

ue-paar.

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

1.2 Token usage

Elke andere request die u naar de APIv2 verstuurt, moet een specifiek HTTP-headerveld bevatten: Authorization. De waarde van dit veld moet de tokenwaarde zijn, voorafgegaan door Bearer.

1.3 Token lifetime

Tokens hebben een beperkte levensduur van 24 uur.
Voor applicaties die met ons platform integreren, is dit niet relevant, omdat tokens doorgaans aan het begin van een applicatieproces worden opgehaald (bijv. een zending boeken en afdrukken), gebruikt worden voor de daaropvolgende calls (bijv. zending boeken, status controleren, labelafdruk aanmaken) en weer worden verwijderd zodra het proces is voltooid.

2 Booking a shipment

Door een zending te boeken stuurt uw systeem alle relevante informatie naar onze APIv2, het Transsmart-platform doet vervolgens zijn werk en er gebeuren een aantal dingen, afhankelijk van de daadwerkelijke configuratie van uw account. Hieronder staan enkele voorbeelden van daadwerkelijke use-cases:

1. Informatie wordt doorgestuurd naar de vervoerder, de vervoerder reageert met labelinformatie en die labelinformatie wordt als onderdeel van de response teruggestuurd naar uw systeem.
    
2. Informatie wordt opgeslagen in Transsmart en alleen doorgestuurd naar de vervoerder in een Manifest op een vast moment gedurende de dag, maar de response bevat desondanks een label dat moet worden afgedrukt.
    
3. Informatie wordt opgeslagen in Transsmart en gebruikt om een label te maken. Alle relevante informatie die de vervoerder nodig heeft, wordt eruit gefilterd en in een barcode geplaatst die een label genereert. Het afdrukken van de barcode draagt de informatie over aan de vervoerder.
    
4. Informatie wordt opgeslagen in Transsmart en er wordt geen informatie naar een vervoerder gestuurd; er wordt alleen een label gegenereerd. Dit wordt gebruikt voor postlabels of eigen transport

2.1 Inhoud van de request

Een boeking bestaat uit meerdere informatieblokken. Het grootste deel van de informatie in die blokken komt uit uw applicatie; de andere onderdelen zijn meestal Transsmart-codes voor vervoerders, servicelevels, enzovoort.

Er is één uitzonderingsveld: de zendingreferentie. De inhoud van dit veld moet uniek zijn voor alle zendingen die u aanmaakt. In de meeste gevallen is dit een autonummerwaarde uit uw applicatie. Naast de basisinformatie van de zending (adressen, ophaaldatum en -tijd, pakketinformatie, enzovoort) moeten meerdere optionele velden een waarde bevatten, afhankelijk van de geselecteerde carrier/service level/service option.

In de volgende paragrafen lichten we de belangrijkste onderdelen van de zendingsinformatie toe. Aan het einde is een volledig voorbeeld van een request opgenomen.

2.1.1 Zendingdetails

Dit is het eerste deel van de request.

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

Vervolgens komen de adressen. In de basis moet de vervoerder weten waar de zending moet worden opgehaald en waar deze moet worden afgeleverd. Deze adressegmenten worden respectievelijk de SEND- en RECV-adressen genoemd, van afzender en ontvanger.

Er zijn 2 extra adrestypen: INV voor de factuur en 3PTY voor de factureringsgegevens van een derde partij.

Ongeacht het type kan elk adres dezelfde gegevensvelden bevatten.

"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

Het volgende blok is voor de pakketdetails en bevat één regel voor elk type pakket. Een pakket kan verschillende types hebben, bijvoorbeeld een pallet of een doos.

Een enkel pakket wordt ook aangeduid als een zendingregel. U kunt uw eigen identificatie aan het pakket toekennen in het veld shipmentLineId.

De quantity is het aantal unieke pakketten dat u verzendt. Als u bijvoorbeeld 2 identieke dozen met dezelfde afmetingen verzendt, kunt u quantity instellen op 2. Dit genereert 2 labels met 2 verschillende airwaybills. Houd er rekening mee dat een response altijd één shipmentline per pakket teruggeeft, ook als u quantity 2 hebt opgegeven. Dit komt doordat elk pakket zijn eigen unieke airway bill (of barcode) heeft.

"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

Elk pakket kan informatie voor een pakbon bevatten. Deze informatie is niet verplicht, maar kan in bepaalde situaties nodig zijn, bijvoorbeeld bij grensoverschrijdende zendingen of wanneer Transsmart aanvullende documentatie moet opmaken, zoals facturen of paklijsten.

2.2 Voorbeeld van een request

Hieronder staat een volledig voorbeeld van hoe een enkele boekingsrequest eruit kan zien.

{
"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 Het label afdrukken

De onderstaande description is geldig voor zowel labels als alle andere transportdocumenten die aan uw zendingen zijn gerelateerd.

3.1 De printactie triggeren

Er zijn drie manieren om de documenten af te drukken:

1. Voor een bestaande zending: haal de daadwerkelijke documenten op en stuur deze naar de printer van uw applicatie.
    
2. Voor een bestaande zending: stuur een aparte printaanvraag en print via SmartPrint.
    
3. Voor een nieuwe zending: stuur een boekingsaanvraag inclusief een printactie en print via SmartPrint

Hieronder vindt u een gedetailleerde uitleg van elke optie. Aan het einde van dit hoofdstuk staat extra informatie over SmartPrint, de Transsmart printing tool.

3.1.1 Documenten ophalen

Het ophalen van de documenten voor een specifieke zending is eenvoudig. Stuur een aanvraag naar v2/prints zoals beschreven in de ontwikkelaarsdocumentatie en stel de parameter rawJob in op true.

De response bevat een base64-gecodeerde string. De werkelijke inhoud kan zpl-code of een pdf-document zijn, afhankelijk van de configuratie van uw account.

3.1.2 Printaanvraag versturen

Dit werkt exact zoals in de vorige paragraaf, behalve dat de parameter rawJob moet worden ingesteld op false.

Op deze manier worden de af te drukken documenten in de wachtrij geplaatst binnen Transsmart, opgehaald door SmartPrint dat in uw netwerk is geïnstalleerd en vervolgens naar uw printers verstuurd.

3.1.3 Een printactie meegeven samen met de boeking en afdrukken via de Transsmart tools.

Bekijk de details van de boekingsaanvraag zoals beschreven in de ontwikkelaarsdocumentatie. Om automatisch een printactie te triggeren op het moment dat u de boekingsaanvraag verstuurt, moet u het pad v2/shipments/BOOK wijzigen in v2/shipments/PRINT.

3.2 SmartPrint

SmartPrint is de Transsmart printing tool die wij in ons platform hebben geïntegreerd.

U kunt de nieuwste versie downloaden via MyTranssmart. Zodra u bent ingelogd, klikt u op het Printer-pictogram en selecteert u de gewenste download. 

Meer informatie over SmartPrint is te vinden here.