Senast uppdaterad: 2024-10-29

EDI-integration med Opter

I den här artikeln

Opter är ett system för transportledning i realtid. Om din samarbetspartner har Opter kan ni koppla ihop era transportledningssystem med hjälp av en EDI-integration, som ger följande funktioner:

  • Ni kan enkelt skicka uppdrag till varandra.

  • Du får en orderbekräftelse så att du ser om underleverantören har tagit emot uppdraget.

  • När en order byter status i det ena systemet byter den även status i det andra systemet.

  • Leveransbevis (POD) skickas automatiskt mellan systemen.

Integrationer sätts upp i Opter-kundernas egna installationer av Opter. Det finns inte någon central inläsning för alla Opter-kunder.

Den här artikeln beskriver vilka data Opter kan skicka och ta emot, samt vilka transportsätt och filformat som stöds. Här finns även information om orderservice, en webbtjänst där en samarbetspartner kan skapa ordrar i Opter-kundens system. Om du inte hittar det du söker i den här artikeln, kontakta gärna , så hittar vi en lösning tillsammans.

Begrepp:

  • EDI (Electronic Data Interchange): EDI är en överföring av strukturerad information enligt överenskommet format. En EDI-integration måste skräddarsys för den export eller import som ska göras, och den information som ska exporteras eller importeras måste vara i rätt format.

  • Opter-kund: Den samarbetspart som har Opters transportledningssystem.

  • POD (Proof of Delivery): Leveransbevis. I Opter används till exempel leveransbevistyperna Levererad, Ny adress och Ingen hemma.

  • Status: Vid en statusuppdatering skickas statusar på ordrar, till exempel Lastad och Lossad, mellan systemen.

Skicka data till Opter

Format

För att Opter-kunden ska kunna skicka och ta emot data via EDI behöver man bestämma hur överföringen av orderunderlaget ska se ut. Opter kan läsa in orderunderlag i formaten XML, EDIFACT, JSON, CSV och andra textfiler med statiska separatorer/avgränsare. Opter kan hantera olika teckenkodningar. Kontakta om du har frågor om format.

För att data ska kunna läsas in i Opter behöver Opters EDI-team sätta upp en EDI-koppling som tolkar informationen från samarbetspartnerns system. För att kunna göra det behöver EDI-teamet få en exempelfil i något av formaten ovan, och gärna en specifikation på det format som samarbetspartnern använder.

Om ni inte har något eget format kan ni göra något av följande:

  • Använda Opters REST API. Mer information finns i Anrop via REST API nedan.

  • Skicka XML-filer i Opters standardformat. XML-schema hittar du här: https://download.opter.com/xsd/. Använd alltid den senaste versionen av order.xsd.

    Om ni använder Opters XML-format måste den som skapar filen rätta sig efter hur Opter-kunden vill att ordern ska se ut.

    Även om ni använder samma XML-standard för integration med flera olika Opter-kunder kan det skilja sig markant hur de olika Opter-kunderna vill att underlaget ska presenteras då alla har olika arbetssätt. Ni behöver då göra de anpassningarna. Om ni använder ett eget format tar Opter hand om anpassningarna. Kontakta och be om exempel och dokumentation för mer information.

Dataöverföring

Vanligast är att man delar en lagringsplats på internet där båda parter kan komma åt varandras ordrar och statusfiler. För det kan man till exempel använda en FTP-server. FTP-servern sätts upp av Opter-kundens IT-ansvariga, eller motsvarande person hos EDI-samarbetsparten. FTP-uppgifterna skickas sedan till Opters EDI-team på . När Opter har hämtat filen från FTP-servern tas den bort, men det går även att arkivera filen eller flytta den till en annan mapp efter att den har lästs in.

Det finns en mer utförlig beskrivning av hur FTP-tjänsten kan sättas upp som vi kan skicka till den som ansvarar för konfigureringen. Kontakta .

Opter har stöd för att läsa in filer via FTP, SFTP och FTPS:

  • FTP: Kommunikationen sker okrypterad över internet.

  • SFTP: Opter kan ansluta till SFTP-tjänster med användarnamn/lösenord, eller med SSH-autentisering med privat nyckel (både med och utan lösenordsskyddad nyckel). Det går även att kombinera autentisering med privat nyckel med lösenordsautentisering.

  • FTPS: Opter kan bara ansluta till FTPS explicit på standardportar (21), inte implicit.

EDI-samarbetspartens system måste ha stöd för de protokoll som används, vilket inte alltid är fallet. Vissa har som krav att kommunikationen ska vara krypterad, medan andra har äldre system där FTP är det enda som kan användas.

Det går också att skicka order- och statusunderlag till Opter-kunder via ett REST API.

Förutsättningar

Kontakta för att:

  • be dem sätta upp integrationen

  • få en API-nyckel. (Den som ska använda API:et behöver en API-nyckel.)

Gå till swagger-dokumentationen

  1. Swagger-dokumentationen för API:et hittar du på samma webbadress som kundwebben, men med ”/api” på slutet:

    • Om ni kör Opter Cloud:

      https://<ert företagsnamn><land>.opter.cloud/api/index.html

      Exempel: Om ert företagsnamn i Opter är ”budfirman” och landet Sverige använder du ”https://budfirmanse.opter.cloud/api/index.html”

    • Om ni har egen server:

      https://<ert företagsnamn eller IP-adress>.<land>/api/index.html

      Exempel: Om ert företagsnamn i Opter är ”budfirman” och landet Sverige använder du

      ”https://budfirman.se/api/index.html” eller ”https://123.45.678.901/api/index.html”

    Om du inte hittar swagger-dokumentationen för API:et, kontakta EDI-teamet på .

  2. Högst upp i högra hörnet på webbsidan finns listrutan Select a definition. Välj ”Opter EDI API v1”.

Använda datamodellen

Om du vill importera API:et till ett verktyg som till exempel Postman så hittar du datamodellen för API:et högt upp på swagger-webbsidan.

Exempel och beskrivning av parametrarna

På https://download.opter.com/json/ hittar du exempel på hur JSON-strukturen för en orderbokning kan se ut. Du kan utgå från ett exempel, men sedan göra om det så att det passar er verksamhet.

I https://download.opter.com/json/opterOrderBookingJsonSchema1.0.json beskrivs alla parametrarnas funktion och format.

API-anropet kan se ut så här:

Exempel på API-anrop
curl --location 'https://opterkunden.opter.cloud/api/textedi' \
--header 'Content-Type: application/json' \
--header 'x-api-key: placeholder' \
--data-raw '{jsonhere}'

Testa att använda API:et

Om du vill testa att använda API:et kan du använda något testprogram som till exempel Postman.

Orderbokning

När filen importerats med någon av transportmetoderna ovan skapas en ny order i Opter. Ordern innehåller den information som Opter-kunden i samråd med oss bedömt som relevant för att kunna utföra transporten.

Vi rekommenderar att inkludera följande information i ordern som skapas i Opter:

  • Adresser (krav)

    En upphämtningsadress och en leveransadress måste anges. Det ska vara fysiska adresser och inte koordinater, GLN-nummer eller UN/LOCODE-koder då Opter inte har någon uppslagning av dessa typer av adresser. Adressen ska innehålla gatuadress (det vill säga gatunamn och nummer, postbox går bra att skicka), postnummer och stad. Ofta inkluderas även ett namn (på en person eller ett företag), en landskod (ISO 3166) och eventuella kontaktuppgifter.

    I speciella undantagsfall behöver man inte ange någon adress, men då måste det vara överenskommet med Opter-kunden hur det ska hanteras. Ett exempel kan vara om ordrarna alltid har fasta adresser.

  • Kundnummer (frivilligt/krav)

    Med kund avses den betalande kunden i Opter. Det går att sätta ett fast kundnummer på integrationen så att det inte behöver skickas med. Men om flera kunder hanteras i samma integration måste kundnumret skickas med. Vi rekommenderar att alltid inkludera kundnummer i underlaget som skickas till Opter-kunden.

  • Tjänst (frivilligt)

    Ofta har man kommit överens med den som utför transporten att ha någon form av tjänst (till exempel ”partigods” eller ”styckegods”) som man bokar. Den behöver då inkluderas i underlaget för att det ska bli rätt tjänst på ordern i Opter. Det går även att ange en standardtjänst som sätts på alla ordrar. Då behöver inte tjänsten inkluderas i underlaget.

    Det går även att sätta tjänsten på ordern i Opter baserat på andra parametrar. Det är i så fall en anpassning som EDI-avdelningen gör baserat på underlaget.

  • Dimensioner/kolli (frivilligt)

    Många Opter-kunder prissätter sina transporter baserat på den vikt och volym som inkluderas i underlaget. Ni behöver komma överens med Opter-kunden om ni ska arbeta på ordernivå eller kollinivå. Om ni arbetar på ordernivå bör den totala vikten och volymen specificeras för hela ordern. Om ni arbetar på kollinivå bör dimensionerna för varje enskilt kolli specificeras så att de kan visas korrekt i Opter.

    Om ordern omfattar farligt gods bör det specificeras med klass och dimensioner.

    Opter kan läsa in följande dimensioner på både order- och kollinivå:

    • vikt

    • volym

    • flakmeter

    • pallplats.

    Följande dimensioner kan endast läsas in på kollinivå:

    • längd

    • bredd

    • höjd.

Det är möjligt att inkludera ytterligare information utöver den som beskrivs ovan. I så fall kommer vi överens om det innan vi sätter upp integrationen.

Kraven på underlaget kan skilja sig från Opter-kund till Opter-kund eftersom alla inte arbetar på samma sätt, men så länge datan inkluderas i underlaget kan vi göra anpassningar för var och en av Opter-kunderna. Om ni har valt att använda Opters XML-format måste ni göra dessa anpassningar själva.

Ändring av befintlig order

Det är möjligt att göra ändringar i en befintlig order som Opter-kunden har tagit emot. Det förutsätter att underlaget som ska ändra den befintliga ordern innehåller något av de unika ID:n som identifierar ordern och som användes när den skapades (till exempel fraktsedelsnummer eller ordernummer). I underlaget bör även en indikator på att det är en ändring, och inte en ny order, finnas med för att underlätta för Opter-kunden.

Ni måste komma överens med Opter-kunden om huruvida det ska vara tillåtet att ändra i befintliga ordrar, och i så fall vilka fält i underlaget som ska kunna ändras.

Om ni använder Opters XML-format kommer vi att beskriva för er hur en ändring av befintlig order ska se ut. Opters EDI-team måste godkänna underlaget innan ni kan börja skicka det automatiskt.

Exportera data från Opter till annat system

För att Opter skall kunna skicka data till ett annat system måste en integration sättas upp. Integrationen har liknande förutsättningar som när ni skickar data till Opter, se Skicka data till Opter ovan.

Skicka en specifikation på motpartens format eller exempelfiler till så undersöker vi om det går att skapa en integration.

För autentisering stöds basic auth eller statiska tokens som skickas som headers. Det innebär att till exempel JWT-tokens inte stöds såvida de inte har oändlig livslängd. Det innebär att Opter inte kan hämta en ny token för varje förfrågan/anrop som ska skickas eftersom det inte finns stöd för det.

Bekräftelser

När en order har skapats i Opter kan ni få en bekräftelse på att den har skapats korrekt och/eller accepterats av Opter-kunden.

Bekräftelsen kan också inkludera dokument, till exempel kollietiketter. Dokumenten kan inkluderas i den metadatafil som skapades vid bekräftelsen (Base64-kodade), eller skickas separat som bifogade filer till exempelvis en e-postadress. Om ordern har skapats genom webservicen kan dokumenten inkluderas i det Base64-kodade svaret som man får vid 200 OK. I så fall måste ni först avkoda det format som returneras och sedan avkoda dokumenten.

Neka uppdrag/avbokning

Om Opter-kunden nekar uppdraget går det att skicka det via EDI. Om ni har skickat ett uppdrag till en underleverantör och inte längre vill att den ska utföra uppdraget går det att skicka en avbokning via EDI. Vi behöver veta hur underlaget för nekade uppdrag och avbokningar ska se ut, och hur de ska hanteras. Många vill till exempel hantera avbokningar manuellt.

Statusar

Som standard brukar statusarna Lastad och Levererad samt leveransbevis (POD) skickas. Alla statusar skickas i det format som ni kom överens om när integrationen skapades. Skicka gärna dokumentation och exempel på hur filerna ska se ut till Opters EDI-team på . Lastad och Lossad är de två vanligaste statusarna, men ni kan komma överens med Opter-kunden och Opters EDI-team om att skicka fler än de två.

Statusuppdateringar till Lastad och Lossad kan ske både på en terminal och hos avsändare/mottagare. Vid lastning och lossning på terminal används begreppen ankomst/avgång istället för lossad/lastad.

Ofta används koder för olika statusar. Skicka gärna dokumentation eller en översikt över koderna för de statusar ni vill överföra till , och inkludera gärna exempelfiler.

Opter kan skicka tillbaka statusar på transporter som bokats i Opter-kundens system i något av tidigare nämnda format.

Opter kan endast skicka ut statusar, och det finns endast begränsade möjligheter att hämta ut status på dina ordrar från Opter (se även avsnittet Track & Trace nedan).

Statusen skickas automatiskt direkt när den ändras av chauffören som utför transporten. Statusändringarna skickas som enskilda filer vid varje händelse, eller så sker en transaktion per händelse beroende på vilken transportmetod ni har kommit överens om.

Det går i vissa fall att skicka flera statusar i samma fil eller transaktion för att minska antalet filer/transaktioner. De kan skickas med de metoder som beskrivs i avsnittet Dataöverföring ovan. Det går även att skicka statusarna till API:er som har en statisk endpoint.

URL:en får inte innehålla dynamiska värden, till exempel olika ordernummer. Endpointen måste acceptera metoden POST. PUT stöds inte.

Kolliskanningar

Statusuppdateringar vid kolliskanningar kan skickas vid lastning hos avsändare, lossning hos mottagare samt vid ankomst till och avgång från terminal. Det förutsätter att Opter-kunden skannar kollin och att det finns ett unikt ID för varje kolli. ID:na måste finnas med när ordern skapas för att Opter-kunden ska kunna skanna dem. Om ID-numren inte finns med kan Opter generera dem, men då måste etiketterna på kollina ha streckkoder som matchar ID-numren (se avsnittet Bekräftelser ovan för information om hur de kan returneras). Det här innebär också att det går att spåra varje enskilt kolli.

Fraktsedelsskanningar

Fraktsedelsskanningar fungerar på samma sätt som kolliskanningar, med undantaget att det inte går att spåra enskilda kollin eftersom fraktsedeln representerar hela ordern. Det förutsätter att det finns ett fraktsedelsnummer på ordern när den skapas, eller att Opter genererar ett fraktsedelsnummer och returnerar det till er så att det finns på fraktsedeln.

Leveransbevis (POD)

Ett leveransbevis kan innehålla signatur, bild och namnförtydligande.

Om signaturen eller bilden skickas i filen som innehåller metadata för leveransbeviset kommer signaturen/bilden att vara Base64-kodad och måste därför avkodas för att kunna visas. Resten av filen behåller sitt format.

Signaturen eller bilden kan även skickas som en separat fil i PDF-, PNG-, GIF- eller JPG-format. Den filen är helt skild från den som innehåller eventuella metadata för POD:en. Det kan vara användbart om ni till exempel vill skicka signerade fraktsedlar. Namnet på filen brukar i så fall innehålla fraktsedelsnumret eller ordernumret.

Avvikelser

Avvikelser kan bland annat syfta på skadat gods och förseningar. Det går att exportera avvikelser från Opter, men eftersom Opter-kunderna använder avvikelser på olika sätt bör ni diskutera hur de ska hanteras med Opters EDI-team och Opter-kunden innan en sådan export sätts upp.

Aviseringar

Opter-kunden kan skicka aviseringar när leveransbevis registreras och vid olika statusändringar, till exempel till mottagaren när godset lastas. Aviseringarna kan skickas via e-post eller SMS. Det förutsätter att det följer med en e-postadress eller ett korrekt mobilnummer som aviseringarna kan skickas till när ordern skapas. Det går även att sätta fasta e-postadresser eller mobilnummer.

Både utseendet och innehållet i aviseringarna kan skräddarsys för att passa just er verksamhet.

Den här funktionen kräver en viss konfiguration. Kontakta Opter på i samråd med Opter-kunden så hjälper vi er vidare.

Prisförfrågningar

Vi rekommenderar att prisförfrågningar alltid skickas via orderservice eftersom det ger snabbast svar.

Opter-kundens prislista måste ha stöd för att rapportera tillbaka ett pris direkt vid förfrågan. Prissättningen skiljer sig mellan olika Opter-kunder. Fråga Opters EDI-team om ni har möjlighet att skicka prisförfrågningar.

Om formatet för prisförfrågningar är samma som formatet för ordrar, och både prisförfrågningar och ordrar skickas via orderservice, måste prisförfrågningarna skiljas från ordrarna med en flagga i filen. Om ordern skickas via FTP och prisförfrågningen via orderservice behövs ingen flagga i filen.

Track & Trace

Om ni inte vill eller inte har möjlighet att göra en integration kan ni använda er av Opter-kundens Track & Trace för att se statusen på ordrar.

På Track & Trace kan ni och mottagarna söka efter transporter, se vilken status de har och annan information. Det behövs inga inloggningsuppgifter för att använda Track & Trace utan man söker direkt på till exempel ordernummer eller fraktsedelsnummer. Fråga Opter-kunden om webbadressen till deras Track & Trace.