Merirahtien seuranta-API: konttitapahtumat, ETA-tiedot ja valintaperusteet

Merirahtien seurantaan tarkoitetun API:n tulisi yhdistää konttien liikkeet, kuljetuksen välitavoitteet ja ETA-päivitykset lähetykseen, jota tiimisi hallinnoi. Huolitsijoille, maahantuojille ja integraatiotiimeille valintakriteerinä on se, pystyykö ratkaisu luotettavasti tunnistamaan oikean kontin kulun, erottamaan toteutuneet tapahtumat ennusteista ja tarjoamaan riittävästi kontekstia operatiivisten päätösten tueksi. Yleinen lähetyksen tila tai selittämätön saapumispäivä ei riitä merirahdin hallintaan.

Tässä oppaassa selitetään, mitä tietoja kannattaa pyytää, miten konttitapahtumia ja saapumisarvioita tulkitaan sekä miten integraatio arvioidaan ennen tuotantoliikenteeseen tai hankintabudjettiin sitoutumista.

Aloita lähetysmallista, älä seurantanäkymästä

Merirahdin seuranta käsittää useita toisiinsa liittyviä objekteja: kaupallisen lähetyksen, sen kuljetusasiakirjat, yhden tai useamman kontin sekä niitä kuljettavat kuljetusosuudet. Näillä suhteilla on merkitystä, koska yksi varaus voi sisältää useita kontteja, ja kontti voi kulkea useiden alusten, terminaalien ja maakuljetusosuuksien kautta.

Hyödyllisen integraation on säilytettävä nämä suhteet sen sijaan, että kaikki litistetään yhdeksi tilaksi. Jos saman lähetyksen kaksi konttia liikkuu eri tavalla, järjestelmän tulisi antaa käyttäjälle mahdollisuus nähdä ero sen sijaan, että se esittäisi näennäisesti täydellisen lähetyskohtaisen välitavoitteen.

Ennen API:n arviointia selvitä, mitä viitteitä yrityksesi tosiasiassa vastaanottaa:

• Konttinumero: Tunnistaa kaluston, mutta se tulee yhdistää asiaankuuluvaan lähetykseen tai kulkuun, koska kontteja käytetään uudelleen.
• Rahdinkuljettajan varausviite: Voi yhdistää seurantapyynnön varaukseen lähdejärjestelmän hakuvälineistä riippuen.
• Kuljetusasiakirjan viite: Saattaa tunnistaa lähetyksen merirahdinkuljettajan tasolla. Varmista, hyväksyykö API tiimisi hallussa olevat asiakirjaviitteet.
• Sisäinen lähetys-ID: Yhdistää ulkoiset seurantatiedot kuljetustenhallintajärjestelmään, ERP-järjestelmään tai huolintaohjelmistoon.

Älä oleta, että huolitsijan myöntämää house bill -viitettä voidaan käyttää kaikkialla, missä edellytetään merirahdinkuljettajan asiakirjaviitettä. Testaa tarkat tunnisteet, jotka ovat käytettävissä varaus- ja asiakirjatyönkuluissasi.

Mitä konttitapahtumia API:n tulisi näyttää?

Digital Container Shipping Associationin Track & Trace -standardit tarjoavat hyödyllisen viitekehyksen merilähetystietojen käsittelyyn. DCSA erottaa lähetys-, kuljetus- ja kalustotapahtumat. Näiden luokkien avulla voidaan erottaa hallinnollinen eteneminen, kuljetuksen liikkuminen ja fyysisen kontin käsittely.

Toimittajan ei tarvitse käyttää suosimiasi kenttänimiä ollakseen hyödyllinen, mutta sen tulisi selittää, miten tapahtumamalli vastaa tarvitsemiasi operatiivisia välitavoitteita.

Kalustotapahtumat: mitä kontille tapahtui

Merkityksellisiä kaluston välitavoitteita voivat olla portille saapuminen, lastaus, purkaus, portilta poistuminen ja tyhjien konttien liikkeet. Saatavuus riippuu matkasta, lähteestä ja tuotteesta. Pyydä esimerkkitietueita sen sijaan, että olettaisit jokaisen tapahtuman olevan saatavilla jokaisessa terminaalissa.

Näillä eroilla on käytännön seurauksia. Aluksen saapuminen ei todista, että tietty kontti on purettu. Purkaus ei todista, että kontti on luovutettu tai valmis noudettavaksi. Myös portilta poistumista koskeva tietue tarvitsee sijainnin ja kontekstin: jälleenlaivausterminaalista poistuminen ei ole sama liiketoiminnallinen tulos kuin nouto lopullisesta tuontiterminaalista.

Kuljetustapahtumat: missä alus tai kuljetusosuus on

Saapumis- ja lähtötapahtumat kuvaavat kuljetustoimintaa. Niiden tulkitsemiseksi järjestelmäsi tarvitsee niihin liittyvän sijainnin, kuljetusmuodon ja kuljetusosuuden. Kun saatavilla, aluksen ja matkan tunnisteet auttavat erottamaan suunnitellun lähdön toisesta samaa satamaparia palvelevasta liikkeestä.

Jälleenlaivattavan rahdin osalta säilytä välietapit. Reitin pelkistäminen lähtöpaikkaan ja määränpäähän voi peittää väliin jääneen yhteyden tai reittimuutoksen. Operatiivisesta aikajanasta tulisi voida nähdä, mikä osuus on valmis ja mikä on yhä arvio.

Lähetystapahtumat: hallinnollinen eteneminen ei ole fyysistä liikettä

Asiakirja- ja lähetyskäsittelyn tapahtumat voivat olla hyödyllisiä huolintatyönkuluissa, mutta ne on pidettävä erotettavissa kontin liikkeestä. Asiakirjoihin liittyvä välitavoite ei osoita, että rahti olisi fyysisesti liikkunut, eikä liike osoita kaikkien kaupallisten tai sääntelyyn liittyvien vaatimusten täyttyneen.

Pyydä jokaisesta tapahtumasta tapahtumatyyppi, asiaankuuluva objekti, sijainti, tapahtuman aikaleima, aikavyöhyketiedot, lähde sekä tieto siitä, onko tapahtuma suunniteltu, arvioitu vai toteutunut. Pyydä myös pysyvä tapahtumatunniste ja tieto korjauskäytännöstä, jotta toistuvat päivitykset eivät luo päällekkäisiä välitavoitteita.

ETA-tieto tarvitsee määränpään, merkityksen ja historian

ETA on arvioitu saapumisaika määritettyyn pisteeseen. Se ei itsessään ole lupaus siitä, että rahti on noudettavissa. Merirahdin seuranta-API:n tulisi ilmaista määränpään välitavoite selkeästi sen sijaan, että se palauttaa epäselvän kentän, jonka nimi on vain eta.

Saapumisarvio voi esimerkiksi viitata satamakäyntiin, terminaaliin, sisämaan laitokseen tai muuhun määriteltyyn määränpäähän. Ennen kuin käytät sitä kuorma-autojen aikatauluttamiseen tai varaston saatavuuden lupaamiseen, selvitä tarkasti, mitä aikaleima edustaa.

Erota arvion lähde sen tilasta

Rahdinkuljettajan tarjoama arvio ja palveluntarjoajan tuottama ennuste ovat eri tietotuotteita. Kumpaakaan ei tulisi esittää toteutuneena saapumisena. Kysy, ilmoittaako vastaus arvion alkuperän, laskenta- tai julkaisuajan sekä sijainnin tai tapahtuman, jota se ennustaa.

Jos palveluntarjoaja tarjoaa ennustavan ETA:n, pyydä tietoja sen menetelmästä ja validointitavasta. Hyödyllisiä kysymyksiä ovat esimerkiksi se, mitä välitavoitetta ennustetaan, kuinka paljon ennen saapumista suorituskykyä mitataan ja vaihtelevatko tulokset käyttämilläsi reiteillä. Laajaa tarkkuusväitettä on vaikea soveltaa, jos sen kohdetapahtumaa ja mittausikkunaa ei ole määritelty.

Säilytä ETA-muutokset sen sijaan, että korvaisit ne

Uusin ETA tukee tämän päivän suunnittelua; muutoshistoria selittää, mitä muuttui. Tallenna aiempi arvio, uusi arvio, siihen liittyvä välitavoite, lähde ja aika, jolloin järjestelmäsi vastaanotti muutoksen.

Tämän historian avulla operatiivinen tiimi voi erottaa merkittävän viivästyksen muotoilukorjauksesta tai asiaan liittymättömän satamakäynnin muutoksesta. Se tukee myös jälkikäteistä arviointia ilman oletusta, että lopullinen arvio olisi tunnettu jo aiemmin matkalla.

Aikavyöhykkeet on testattava erikseen. Säilytä lähteen aikaleima ja sen poikkeama, jos ne toimitetaan, normalisoi aikaleimat laskentaa varten ja näytä paikallinen operatiivinen aika tarvittaessa. Jos lähde tarjoaa vain päivämäärän, älä muuta sitä hiljaisesti täsmälliseksi keskiyön saapumislupaukseksi.

Arvioi kattavuutta tapahtumatasolla

Se, että rahdinkuljettaja esiintyy kattavuusluettelossa, ei yksin osoita, että jokainen kontin välitavoite on saatavilla. Kattavuus on testattava niiden rahdinkuljettajien, reittien, lähetysviitteiden ja operatiivisten tapahtumien perusteella, joilla on yrityksellesi merkitystä.

Laadi arviointimatriisi todellisten vaatimustesi perusteella. Tarkista jokaisen edustavan lähetyksen kohdalla, pystyykö API ratkaisemaan viitteen, palauttamaan oikean reitin, näyttämään tarvitsemasi välitavoitteet ja ylläpitämään päivityksiä hallinnoimasi matkan osan ajan.

• Suorat merikuljetukset: Voitko tunnistaa lähtösatamasta lähdön, määränpään saapumisen ja asiaankuuluvat kontin käsittelytapahtumat?
• Jälleenlaivauskuljetukset: Ovatko väliosat näkyvissä ja voidaanko erikseen liikkuvat kontit pitää eroteltuina?
• Maakuljetusosuudet: Jos palvelusi sisältää niitä, tarjoaako API asiaankuuluvat rautatie-, proomu- tai kuorma-autovälitavoitteet, vai päättyykö näkyvyys satamaan?
• Poikkeukset: Miten puuttuvat tapahtumat, muuttuneet reitit, täsmäämättömät viitteet ja lähdekatkokset esitetään?
• Päättyneet lähetykset: Voiko tiimisi hakea riittävästi historiatietoja asiakasriidan tutkimiseen tai operatiivisen tietueen täsmäyttämiseen?

Pidä puuttuvat tiedot erillään kielteisistä tapahtumista. Purkaustietueen puuttuminen ei todista, ettei purkausta ole tapahtunut. Hyödyllinen integraatio erottaa nimenomaisen operatiivisen tilan näkyvyyden puutteesta.

API:n toiminta on yhtä tärkeää kuin tapahtumaluettelo

Rikas tapahtumasyötekin voi olla vaikea ylläpitää, jos toimituskäytännöt ovat epäselvät. Arvioi, miten sovelluksesi vastaanottaa päivitykset, käsittelee korjaukset ja palautuu käyttökatkon jälkeen.

Kyselyt, webhookit ja palautuminen

Kyselyiden avulla sovelluksesi voi pyytää päivityksiä oman aikataulunsa mukaan. Webhookien avulla palveluntarjoaja voi lähettää päivityksiä hallinnoimaasi päätepisteeseen. Kumpikaan mekanismi ei yksin takaa tietojen tuoreutta: välittömästi toimitettu webhook voi silti sisältää myöhässä vastaanotetun lähdetapahtuman.

Pyydä mahdollisuuksien mukaan erilliset määritelmät lähdetapahtuman ajalle, palveluntarjoajan vastaanottoajalle ja ilmoitusajalle. Varmista webhookien osalta todennus tai allekirjoituksen vahvistus, uudelleenyritykset, päällekkäisten toimitusten käsittely ja se, voidaanko epäonnistuneet ilmoitukset toistaa. Tarkista kyselyiden osalta sivutus, nopeusrajoitukset, inkrementaalinen haku ja historiakorjausten käsittely.

Normalisointi ilman todisteiden menettämistä

Normalisoidut tilat helpottavat eri rahdinkuljettajien välisiä työnkulkuja, mutta liiallinen yksinkertaistaminen poistaa hyödyllisen kontekstin. Suosi mallia, jossa voit säilyttää normalisoidun tapahtuman rinnalla alkuperäisen lähdekuvauksen tai koodin, jos se on saatavilla.

Tallenna saapuvat raakatietueet erillään liiketoimintasäännöistä, jotka muuttavat ne koontinäytön tiloiksi. Näin voit muuttaa määritystä menettämättä alkuperäisiä todisteita. Se helpottaa myös asiakasnäytössä näkyvän tilan tutkimista, jos se poikkeaa operatiivisen tiimin tulkinnasta.

Kaupalliset ja hallinnolliset tarkistukset

Pyydä kirjallinen selvitys laskutusyksiköstä. Tilaus, seurattu lähetys, kontti, API-pyyntö ja ilmoitus eivät ole keskenään vaihtokelpoisia mittareita. Selvitä, miten uudelleenyritykset, päällekkäiset rekisteröinnit, historiakyselyt ja uudelleenaktivoidut lähetykset vaikuttavat veloituksiin sen sijaan, että olettaisit tietyn hinnoittelumallin.

Tarkista myös tietojen säilytys, käyttöoikeudet, tunnistetietojen kierto, sallittu jatkokäyttö, tuen eskalointi ja palvelusitoumukset. Käsittele sopimustakuut erillään tuote-esittelyistä ja markkinointiväitteistä.

Älä oleta yleisen seuranta-API:n täyttävän merirahdin vaatimuksia

Seuranta-API tulisi valita varmennetun tietomallin, ei luokkansa nimen perusteella. Pakettien toimituspäivitykset ja merikonttien näkyvyys voivat palvella eri työnkulkuja, vaikka molempia kutsuttaisiin lähetysseurannaksi.

Jos 17TRACK on jo integraatiolistallasi, käytä sen virallista Tracking API -sivua ja API-dokumentaatiota lähtökohtina vaatimusmäärittelyssä. Vahvista sovelluksesi tarvitsemat tarkat merirahdin viitteet, konttitapahtumat, kuljetusosuudet ja ETA-kentät ennen kuin käsittelet yleistä seuranta-integraatiota merirahtiratkaisuna. Tämä opas ei vahvista näitä merirahtiin liittyviä ominaisuuksia 17TRACKille.

Samaa hyväksymisstandardia tulisi soveltaa jokaiseen ehdokkaaseen: vaaditut tiedot on osoitettava edustavilla lähetyksillä ja rajoitukset selitettävä. Laajempi rahdinkuljettajien seurantatyönkulku voi olla hyödyllinen muualla toimitusketjussa ilman, että se korvaa erikoistuneen konttitapahtumasyötteen.

Toteuta konseptitodistus operatiivisten päätösten ympärille

Vahvin konseptitodistus alkaa päätöksistä, joita tiimisi tarvitsee tehdä, ei koontinäytön esittelystä. Valitse omasta toiminnastasi edustavia lähetyksiä, mukaan lukien suoraviivaiset matkat ja vaikeat tapaukset, jotka aiheuttavat manuaalista työtä.

1. Määritä hyväksymiskriteerit. Määritä vaaditut viitteet, tapahtumat, sijainnit, aikaleimojen merkitykset ja puuttuvien tietojen hyväksyttävä käsittely ennen testausta.
2. Vahvista identiteetti. Varmista, että jokainen tulos kuuluu tarkoitettuun lähetykseen ja kontin kulkuun. Sisällytä tarvittaessa uudelleenkäytetty kalusto ja usean kontin varaukset.
3. Vertaa lähdetietueisiin. Tarkista palautetut välitavoitteet saatavilla olevia rahdinkuljettajan tai terminaalin tietueita vasten ja huomioi päivitysajoitusten erot.
4. Testaa muutokset ja virheet. Testaa päällekkäiset ilmoitukset, väärässä järjestyksessä saapuvat tapahtumat, korjatut aikaleimat, puuttuvat lähteet ja päätepisteiden käyttökatkot.
5. Toista liiketoimintatyönkulku. Varmista, tukeeko tieto suunniteltua toimintaa, kuten viivästyneen yhteyden tarkistamista tai saapuvan varastoarvion päivittämistä.
6. Tarkista ratkaisemattomat puutteet. Kirjaa, johtuuko kukin puute taustalla olevasta lähteestä, palveluntarjoajan käsittelystä vai integraatiostasi. Sovi korjaavista toimista ennen käytön laajentamista.

ETA-testauksessa säilytä jokainen ennuste sen saapuessa ja vertaa sitä saman välitavoitteen lopulliseen toteutuneeseen tapahtumaan. Älä arvioi satamaan saapumisen ennustetta varastovastaanottoa vasten äläkä yhdistä hyvin erilaisilla ennakkoajoilla tehtyjä ennusteita yhdeksi selittämättömäksi pistemääräksi.

Valintasääntö on yksinkertainen: valitse integraatio, joka osoitettavasti tukee tarvittavia päätöksiä jäljitettävillä tapahtumilla, ymmärrettävillä arvioilla ja palautettavalla toimituskäyttäytymisellä. Jos noudon suunnittelu edellyttää myös terminaalin saatavuutta, luovutustilaa tai ajanvarauksia, varmista nämä syötteet erikseen äläkä päättele niitä aluksen saapumisesta.

Usein kysytyt kysymykset

Voinko seurata merilähetystä pelkän konttinumeron avulla?

Se riippuu tietolähteestä ja API:sta. Joissakin työnkuluissa voidaan tarvita myös rahdinkuljettajan tunniste, varausviite tai kuljetusasiakirjan viite. Koska kalustoa käytetään uudelleen, varmista, että palautetut tapahtumat kuuluvat tarkoittamaasi matkaan sen sijaan, että luottaisit pelkkään konttinumeroon.

Tarkoittaako aluksen toteutunut saapuminen, että konttini on valmis noudettavaksi?

Ei. Aluksen saapuminen, kontin purkaus, rahdin saatavuus ja noutolupa ovat erillisiä operatiivisia tosiasioita. Lähetyksestä riippuen nouto voi edellyttää myös luovutustietoja ja terminaalivarausta. Varmista asiaankuuluvat ehdot niiltä osapuolilta, jotka vastaavat niistä.

Korvaako AIS-alusseuranta konttiseurannan?

Ei. AIS koskee aluksen tunnistamista ja liiketietoja; se ei itsessään osoita yksittäisen kontin lastaus-, purkaus-, luovutus- tai portilta poistumisen tilaa. Aluksen liike voi tarjota kontekstia, mutta kontin yhteys matkaan on silti vahvistettava.

Kuinka usein meriseuranta-API:n tulisi päivittyä?

Kaikille työnkuluille ei ole yhtä hyödyllistä aikaväliä. Aseta vaatimukset sen mukaan, kuinka nopeasti tiimisi tarvitsee toimia asiaankuuluvan lähdetiedon saataville tulon jälkeen. Mittaa lähteen viive erillään API:n toimitusviiveestä ja selvitä, mitä tapahtuu, kun lähde ei julkaise uutta tapahtumaa.

Voidaanko seurantatapahtumien avulla laskea seisonta- tai viivästysmaksuja?

Tapahtumat voivat tukea aikajanaa, mutta ne eivät muodosta täydellistä maksu­laskelmaa. Tarvitset myös sovellettavat sopimusehdot, vapaa-ajan säännöt, kalenterikäsittelyn sekä auktoritatiiviset alku- ja loppuehdot. Älä johda maksettavia summia pelkistä yleisistä välitavoitteista.

Lähteet

• DCSA: Track & Trace -standardit — Viitekehys konttikuljetusten lähetys-, kuljetus- ja kalustotapahtumille.
• DCSA: OpenAPI-määritysten repositorio — Tekninen viite DCSA:n API-määrityksille ja tapahtumarakenteille. Tarkista sovellettava määritysversio integraatiota suunnitellessasi.
• Kansainvälinen merenkulkujärjestö: automaattiset tunnistusjärjestelmät — Taustatietoa AIS-järjestelmästä ja sen tarjoamista alustiedoista.
• 17TRACK: Tracking API ja virallinen API-dokumentaatio — Lähtökohtia tuotteen soveltuvuuden arviointiin; eivät tässä ole todiste merikonttien tapahtumien tai ennustavan ETA:n tuesta.