Viimeisin päivitys: 2025-08-25

Opter ja EDI-integraatio

Tässä Artikkeli

Opter on reaaliaikainen kuljetustenhallintajärjestelmä.

Jos sinulla ei ole Opteria ja jos yhteistyökumppanillasi on Opter, voit yhdistää kuljetustenhallintajärjestelmänne EDI-integraatiolla (EDI), joka tarjoaa seuraavat toiminnot:

  • Voitte helposti lähettää kuljetuksia toisillenne.

  • Saat tilausvahvistuksen, josta näet, onko alihankkija vastaanottanut kuljetuksen.

  • Kun tilauksen status muuttuu yhdessä järjestelmässä, se muuttuu myös toisessa järjestelmässä.

  • Toimitusvahvistukset lähetetään automaattisesti järjestelmien välillä.

Integraatiot tehdään Opterin asiakkaiden omissa Opter-asennuksissa. Opterin asiakkaille ei ole keskitettyä latausta.

Tässä artikkelissa kuvataan, mitä tietoja Opter voi lähettää ja vastaanottaa sekä mitä kuljetus- ja tiedostomuotoja tuetaan. Saat myös tietoa tilauspalvelusta eli verkkopalvelusta, jossa kumppani voi luoda tilauksia Opterin asiakkaan järjestelmässä. Jos et löydä etsimääsi tietoa tästä artikkelista, ota yhteyttä osoitteeseen , niin voimme miettiä ratkaisua yhdessä.

Käsitteitä:

  • EDI (Electronic Data Interchange): EDI on strukturoidun tiedon siirtoa sovitussa muodossa. EDI-integraatio on räätälöitävä toteutettavan viennin tai tuonnin mukaan, ja vietävien tai tuotavien tietojen on oltava oikeassa muodossa.

  • Opter-asiakkaat: Yhteistyökumppani, jolla on Opterin kuljetustenhallintajärjestelmä.

  • POD (Proof of Delivery): Toimitusvahvistus. Opterissa käytetään esimerkiksi toimitusvahvistustyyppejä Toimitettu, Uusi osoite ja Ei kotona.

  • Status: Statuksen päivityksen yhteydessä statukset, kuten Lastattu ja Purettu, lähetetään järjestelmien välillä.

Tietojen lähettäminen Opteriin

Muoto

Jotta Opterin asiakas voisi lähettää ja vastaanottaa tietoja EDI:n kautta, on päätettävä, miltä tilausasiakirjan siirron tulee näyttää. Opter voi lukea tilausasiakirjat, jotka ovat muodoissa XML, EDIFACT, JSON, CSV tai muissa tekstitiedostoissa, joissa käytetään staattisia erottimia. Opter pystyy käsittelemään erilaisia ​​merkistöjä. Ota yhteyttä osoitteeseen , jos sinulla on kysyttävää muodoista.

Jotta Opter voisi lukea tiedot, Opterin EDI-tiimin on muodostettava EDI-yhteys, joka tulkitsee tiedot kumppanin järjestelmästä. Tätä varten EDI-tiimin on saatava esimerkkitiedosto jossakin yllä olevista muodoista ja mieluiten erittely kumppanin käyttämästä muodosta.

Jos omaa muotoa ei ole, valitse jokin seuraavista:

  • Käytä Opterin REST API:a. Lisätietoa: Kutsu REST API:n kautta alla.

  • Lähetä XML-tiedostot Opterin vakiomuodossa. XML-mallin löydät täältä: https://download.opter.com/xsd/. Käytä aina viimeisintä saatavilla olevaa order.xsd-versiota.

    Jos käytetään Opterin XML-muotoa, tiedoston laatijan tulee mukautua siihen, miltä Opterin asiakas haluaa tilauksen näyttävän.

    Vaikka käytössä olisi sama XML-standardi, integraatiossa useiden eri Opter-asiakkaiden kanssa voi esiintyä merkittäviä eroja siinä, miten Opterin asiakas haluaa esittää tiedot, sillä jokaisella on omat työtapansa. Tällöin on tehtävä mukautuksia. Jos käytössä on oma muoto, Opter huolehtii mukautuksista. Ota yhteyttä osoitteeseen ja pyydä esimerkkejä ja lisätietoja.

Tiedonsiirto

Yleisin tapa on jakaa internetissä tallennuspaikka, jossa molemmat osapuolet voivat käyttää toistensa tilauksia ja statustiedostoja. Tätä varten voi käyttää esimerkiksi FTP-palvelinta. FTP-palvelimen asentaa Opterin asiakkaan IT-päällikkö tai EDI-kumppanin vastaava työntekijä. FTP-tiedot lähetetään sitten Opterin EDI-tiimille osoitteeseen . Kun Opter on hakenut tiedoston FTP-palvelimelta, se poistetaan, mutta tiedosto voidaan myös arkistoida tai siirtää toiseen kansioon.

FTP-palvelun määrittämisestä on olemassa tarkempi kuvaus, ja se voidaan lähettää määrittämisestä vastaavalle henkilölle. Ota yhteyttä -järjestelmän ylläpitäjään.

Opterissa on tuki tiedostojen lataamiseen FTP:n, SFTP:n ja FTPS:n kautta:

  • FTP: Viestintä tapahtuu salaamattomana internetin kautta.

  • SFTP: Opter voi muodostaa yhteyden SFTP-palveluihin käyttäjätunnuksen/salasanan avulla tai SSH-todennuksella yksityisellä avaimella (joko salasanalla suojatulla avaimella että ilman sitä). Voit myös käyttää todennusta suojatulla avaimella ja salasanasuojausta samanaikaisesti.

  • FTPS: Opter voi muodostaa yhteyden FTPS:ään vain eksplisiittisesti oletusporteissa (21), ei implisiittisesti.

EDI-kumppanin järjestelmän on tuettava käytettäviä protokollia, mikä ei aina toteudu. Jotkut vaativat, että viestintä salataan, kun taas toisilla on vanhempia järjestelmiä, joissa FTP on ainoa käytettävissä oleva ratkaisu.

Opter-asiakkaille voidaan lähettää tilaus- ja statustietoja REST API:n kautta.

Edellytykset

Lähetä viesti osoitteeseen :

  • pyydä heitä perustamaan integraatio

  • saada API-avain. (Henkilö, joka käyttää API:tä, tarvitsee API-avainta.)

Siirry Swagger-dokumentaatioon

  1. API:n Swagger-dokumentaatio on muuten samassa URL-osoitteessa kuin asiakasverkko, mutta sen lopussa on ”/api”:

    • Jos käytössä on Opter Cloud:

      https://<yrityksen nimi><maa>.opter.cloud/api/index.html

      Esimerkki: Jos yrityksen nimi Opterissa on ”lähettiyritys” ja se sijaitsee Suomessa, osoite on ”https://lähettiyritysfi.opter.cloud/api/index.html”

    • Jos käytössä on oma palvelin:

      https://<yrityksen nimi tai IP-osoite>.<maa>/api/index.html

      Esimerkki: Jos yrityksen nimi Opterissa on ”lähettiyritys” ja se sijaitsee Suomessa, osoite on

      ”https://lähettiyritys.fi/api/index.html” tai ”https://123.45.678.901/api/index.html”

    Jos et löydä API:n Swagger-dokumentaatiota, ota yhteyttä EDI-tiimiin: .

  2. Sivun oikeassa yläkulmassa on pudotusvalikko Select a definition. Valitse ”Opter EDI API v1”.

Tietomallin käyttäminen

Jos haluat tuoda API:n työkaluun, esimerkiksi Postmaniin, tarvittava tietomalli on Swagger-sivun yläosassa.

Esimerkkejä ja parametrien kuvaus

Osoitteessa https://download.opter.com/json/ on esimerkkejä siitä, miltä tilausvarauksen JSON-rakenne voi näyttää. Voit käyttää esimerkkiä lähtökohtana ja mukauttaa sen toimintaanne sopivaksi.

Osoitteessa https://download.opter.com/json/opterOrderBookingJsonSchema1.0.json on kuvaus kaikkien parametrien toiminnasta ja muodosta.

API-kutsu voi näyttää tältä:

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

Kokeile API:n käyttöä

Jos haluat testata API:n käyttöä, voit käyttää testiohjelmaa, esimerkiksi Postmania.

Tilauksen varaus

Kun tiedosto on tuotu jollakin yllä mainituista siirtotavoista, Opterissa luodaan uusi tilaus. Tilaus sisältää tiedot, jotka Opterin asiakas meidän ohjeistuksellamme katsoo tarpeellisiksi voidakseen suorittaa kuljetuksen.

Suosittelemme sisällyttämään seuraavat tiedot Opterissa luotavaan tilaukseen:

  • Osoitteet (pakollinen)

    Nouto- ja toimitusosoite ovat pakollisia tietoja. Niiden on oltava fyysisiä osoitteita, ei koordinaatteja, GLN-numeroita tai YK/LOCODE-sijaintikoodeja, koska Opter ei tue tämäntyyppisiä osoitteita. Osoitteen on sisällettävä katuosoite (eli kadun nimi ja numero, postilokero), postinumero ja kaupunki. Usein mukaan liitetään myös nimi (henkilön tai yrityksen), maakoodi (ISO 3166) ja mahdolliset yhteystiedot.

    Joissakin poikkeustapauksissa osoitetta ei tarvitse syöttää, mutta silloin Opterin asiakkaan kanssa on sovittava, miten asia hoidetaan. Yksi esimerkki tällaisista ovat tilanteet, joissa tilauksilla on aina kiinteät osoitteet.

  • Asiakasnumero (valinnainen/pakollinen)

    Asiakkaalla tarkoitetaan Opterin maksavaa asiakasta. Integraatiossa asiakasnumero voidaan määrittää kiinteäksi, jolloin sitä ei tarvitse lähettää. Jos integraatio käsittää useita asiakkaita, asiakasnumero on pakko lähettää. Suosittelemme aina sisällyttämään asiakasnumeron Opterin asiakkaalle lähetettävään dokumentaatioon.

  • Palvelu (valinnainen)

    Usein kuljetuksen suorittajan kanssa on sovittu jonkinlaisen palvelun (esimerkiksi ”erälasti” tai ”kappaletavaralasti”) varaamisesta. Se on sisällytettävä tietoihin, jotta tilauksessa on oikea palvelu Opterissa. On mahdollista myös määrittää oletuspalvelu, jota käytetään kaikissa tilauksissa. Tällöin palvelua ei tarvitse sisällyttää tietoihin.

    Palvelu voidaan määrittää tilaukseen Opterissa myös muiden muuttujien perusteella. Tällöin EDI-osaston on tehtävä asiakirjan mukainen mukautus.

  • Mitat/kolli (valinnainen)

    Monet Opterin asiakkaat hinnoittelevat kuljetukset asiakirjaan sisältyvän painon ja tilavuuden mukaan. Opterin asiakkaan kanssa on sovittava, työskennelläänkö tilaus- vai kollitasolla. Jos työskennellään tilaustasolla, kokonaispaino ja tilavuus tulee määrittää koko tilaukselle. Jos työskennellään kollitasolla, kunkin yksittäisen kollin mitat tulee määrittää, jotta ne näkyvät oikein Opterissa.

    Jos tilaus sisältää vaarallisia aineita, niiden luokka ja mitat on määritettävä.

    Opter voi lukea seuraavat mitat sekä tilaus- että kollitasolla:

    • paino

    • tilavuus

    • lavametri

    • lavapohja.

    Seuraavat mitat voidaan lukea vain kollitasolla:

    • pituus

    • leveys

    • korkeus.

Edellä kuvattujen lisäksi on mahdollista sisällyttää muitakin tietoja. Tällöin asiasta on sovittava ennen integraation toteuttamista.

Asiakirjaa koskevat vaatimukset voivat vaihdella Opterin asiakkaista riippuen, koska kaikki eivät toimi samalla tavalla. Kuitenkin niin kauan kuin tiedot ovat asiakirjassa, voimme tehdä mukautukset jokaiselle Opterin asiakkaalle. Jos olet valinnut Opterin XML-muodon, sinun on tehtävä nämä mukautukset itse.

Olemassa olevan tilauksen muutos

Opterin asiakkaan vastaanottamaan olemassa olevaan tilaukseen on mahdollista tehdä muutoksia. Tämä edellyttää sitä, että asiakirja, jonka on määrä muuttaa olemassa olevaa tilausta, sisältää yhden yksilöllisistä tunnisteista, jotka identifioivat tilauksen ja joita on käytetty sen luonnin aikana (esimerkiksi rahtikirjanumero tai tilausnumero). Opterin asiakkaan työn helpottamiseksi asiakirjassa on myös mainittava, että kyseessä on muutos eikä uusi tilaus.

Opterin asiakkaan kanssa on sovittava, sallitaanko olemassa olevien tilausten muuttaminen ja jos sallitaan, mitä asiakirjan kenttiä on voitava muuttaa.

Jos käytät Opterin XML-muotoa, kuvailemme sinulle, miltä olemassa olevan tilauksen muutoksen tulisi näyttää. Opterin EDI-tiimin on hyväksyttävä asiakirja ennen kuin sen automaattinen lähettäminen voidaan aloittaa.

Tietojen vienti Opterista toiseen järjestelmään

Jotta Opter voi lähettää tietoja toiseen järjestelmään, on määritettävä integraatio. Integraation edellytykset ovat samankaltaiset kuin Opteriin tietoja lähetettäessä, katso yllä oleva kohtaTietojen lähettäminen Opteriin yllä.

Lähetä määrittely vastapuolen käyttämästä muodosta tai mallitiedostot osoitteeseen , jotta voimme tutkia mahdollisuutta integrointiin.

Todennusta varten tuetaan otsikkona lähetettyä perustodennustunnusta tai staattista todennustunnusta. Esimerkiksi JWT-tunnuksia ei tueta, ellei niillä ole loputonta käyttöikää. Tämä tarkoittaa sitä, että Opter ei voi noutaa uutta tunnusta jokaiselle lähetettävälle pyynnölle/kutsulle, sillä niitä ei tueta.

Vahvistukset

Kun tilaus on luotu Opterissa, voidaan lähettää vahvistus siitä, että tilaus on luotu oikein ja/tai Opterin asiakas on hyväksynyt tilauksen.

Vahvistukseen voi sisältyä myös asiakirjoja, esimerkiksi kollietikettejä. Ne voidaan sisällyttää vahvistuksen yhteydessä luotuun (Base64-koodattuun) metadatatiedostoon tai lähettää erikseen liitetiedostoina esimerkiksi sähköpostiosoitteeseen. Jos tilaus on tehty verkkopalvelun kautta, asiakirjat voidaan sisällyttää Base64-koodattuun vastaukseen, jonka saa numerolla 200 OK. Tässä tapauksessa on ensin purettava palautettava muoto ja sitten asiakirjat.

Kuljetuksen hylkääminen/peruutus

Jos Opterin asiakas hylkää kuljetuksen, tieto siitä voidaan lähettää EDI:n kautta. Jos olet lähettänyt kuljetuksen alihankkijalle etkä enää halua tämän suorittavan sitä, voit lähettää peruutuksen EDI:n kautta. Meidän on tiedettävä, miltä hylättyjen kuljetusten ja peruutusten asiakirjan tulee näyttää ja miten sitä tulee käsitellä. Monet haluavat käsitellä peruutukset manuaalisesti.

Statukset

Oletuksena lähetetään statukset Lastattu ja Toimitettu sekä toimitusvahvistus. Kaikki statukset lähetetään integraation luomisen yhteydessä sovitussa muodossa. Suosittelemme lähettämään dokumentaatiota ja esimerkkejä siitä, miltä tiedostojen tulisi näyttää, Opterin EDI-ryhmälle osoitteeseen . Yleisimmät statukset ovat Lastattu ja Purettu, mutta voitte sopia Opter-asiakkaan ja Opterin EDI-ryhmän kanssa useamman statuksen lähettämisestä.

Päivitys statuksiin Lastattu ja Purettu voidaan tehdä sekä terminaalissa että lähettäjällä/vastaanottajalla. Terminaalissa lastattaessa ja purettaessa käytetään termejä saapuminen/lähtö termien purettu/lastattu sijasta.

Usein statuksille käytetään koodeja. Lähetä dokumentaatiota tai yleiskatsaus siirrettävien statusten koodeista osoitteeseen ja liitä mukaan esimerkkitiedostoja.

Opter voi lähettää takaisin erilaisia ​​statuksia Opterin asiakkaan järjestelmässä varatuille kuljetuksille missä tahansa aiemmin mainitussa muodossa.

Opter voi lähettää vain statuksia. Tällä hetkellä on vain rajoitetusti mahdollisuuksia noutaa statuksia Opterista tilauksiinne (katso Track & Trace -osio alla).

Status lähetetään automaattisesti, kun kuljetuksen suorittava kuljettaja muuttaa sitä. Statusmuutokset lähetetään yksittäisinä tiedostoina kunkin tapahtuman yhteydessä tai tapahtumaa kohden suoritetaan jotain muuta riippuen siitä, mikä siirtotapa on sovittu.

Joissakin tapauksissa on mahdollista lähettää useita statuksia samassa tiedostossa tai tapahtumassa, jotta voidaan vähentää tiedostojen/lähetystapahtumien määrää. Lähettämiseen voidaan käyttää yllä olevassa kohdassa Tiedonsiirto kuvattuja tapoja. Statukset voidaan myös lähettää ohjelmointirajapintoihin (API), joilla on staattinen päätepiste.

URL-osoite ei saa sisältää dynaamisia arvoja, kuten erilaisia ​​tilausnumeroita. Päätepisteen on hyväksyttävä menetelmäksi POST. PUT ei ole tuettu.

Kolliskannaukset

Kolliskannausten statuspäivitykset voidaan lähettää lähettäjällä lastattaessa, vastaanottajalla purettaessa sekä terminaaliin saapumisen ja terminaalista lähdön yhteydessä. Tämä edellyttää sitä, että Opterin asiakas skannaa kollin ja että kullekin kollille on yksilöllinen tunnus. Tunnuksen on sisällyttävä tietoihin, kun tilaus luodaan, jotta Opterin asiakas voi skannata sen. Jos tunnusnumeroa ei ole mukana, Opter voi luoda sen, mutta tällöin kollien etiketeissä on oltava tunnusnumeroon täsmäävät viivakoodit (yllä olevassa kohdassa Vahvistukset on tietoa niiden palauttamisesta). Tämä tarkoittaa myös sitä, että jokaista yksittäistä kollia voidaan seurata.

Rahtikirjojen skannaukset

Rahtikirjaskannaukset toimivat samalla tavalla kuin kolliskannaukset sillä poikkeuksella, että yksittäisten kollien seuranta ei ole mahdollista, koska rahtikirja edustaa koko tilausta. Edellytyksenä on, että luotavassa tilauksessa on rahtikirjanumero tai että Opter luo rahtikirjanumeron ja palauttaa sen teille, jolloin se on mukana rahtikirjassa.

Toimitusvahvistus (POD)

Toimitusvahvistus voi sisältää allekirjoituksen, kuvan ja nimenselvennöksen.

Jos allekirjoitus tai kuva lähetetään toimitusvahvistuksen metatiedot sisältävässä tiedostossa, allekirjoitus tai kuva Base64-koodataan. Se on purettava, jotta se voidaan näyttää. Loput tiedostosta säilyttää muotonsa.

Allekirjoitus tai kuva voidaan myös lähettää erillisenä PDF-, PNG-, GIF- tai JPG-tiedostona. Tämä tiedosto on täysin erillinen toimitusvahvistuksen metatiedot sisältävästä tiedostosta. Tästä voi olla hyötyä esimerkiksi silloin, jos halutaan lähettää allekirjoitetut rahtikirjat. Tiedoston nimeen sisältyy tällöin yleensä rahtikirjanumero tai tilausnumero.

Poikkeamat

Poikkeamat voivat tarkoittaa esimerkiksi vahingoittuneita tavaroita tai viivästyksiä. Poikkeamat voidaan viedä Opterista, mutta koska Opterin asiakkaat käyttävät poikkeamia eri tavoin, niiden käsittelystä on keskusteltava Opterin EDI-tiimin ja Opterin asiakkaan kanssa ennen viennin määrittämistä.

Ilmoitukset

Opterin asiakkaat voivat lähettää ilmoituksia toimitusvahvistuksen rekisteröinnin ja statusmuutosten yhteydessä, esimerkiksi vastaanottajalle, kun tavaraa lastataan. Ilmoitukset voidaan lähettää sähköpostitse tai tekstiviestillä. Tämä edellyttää sitä, että tilausta tehtäessä mukana on sähköpostiosoite tai matkapuhelinnumero, johon ilmoitukset voidaan lähettää. Myös kiinteitä sähköpostiosoitteita tai matkapuhelinnumeroita voidaan käyttää.

Ilmoitusten ulkonäkö ja sisältö voidaan räätälöidä yrityksellesi sopiviksi.

Toiminto edellyttää tietynlaista määritystä. Ota yhteyttä osoitteeseen yhdessä Opterin asiakkaan kanssa, niin autamme kehittämään ratkaisun.

Hintapyynnöt

Hintapyynnöt kannattaa aina lähettää tilauspalvelun kautta, sillä se takaa nopeimman vastauksen.

Opterin asiakkaan hinnaston on tuettava hinnan ilmoittamista suoraan pyynnöstä. Hinnoittelu vaihtelee eri Opterin asiakkaiden välillä. Kysy Opterin EDI-tiimiltä, onko yritykselläsi mahdollisuutta hintapyyntöjen lähettämiseen.

Jos hintapyynnön muoto on sama kuin tilausten muoto ja sekä hintapyynnöt että tilaukset lähetetään tilauspalvelun kautta, tiedostoissa on oltava tunniste, joka erottaa hintapyynnöt tilauksista. Jos tilaukset lähetetään FTP:n kautta ja hintapyynnöt tilauspalvelun kautta, tiedostossa ei tarvitse olla tunnistetta.

Track & Trace

Jos integrointia ei haluta tai ole mahdollista tehdä, voit käyttää Opterin asiakkaan Track & Trace -palvelua nähdäksesi tilausten statuksen.

Track & Trace -toiminnon avulla sinä ja vastaanottajat voitte hakea kuljetuksia ja nähdä niiden statuksen ja muita tietoja. Track & Trace -toiminnon käyttöön ei tarvita kirjautumistietoja, vaan haku tehdään suoraan esimerkiksi tilausnumerolla tai rahtikirjanumerolla. Pyydä Opterin asiakkaalta sen Track & Tracen verkko-osoitetta.