Siirry sisältöön

Vaarallisten aineiden REST API

DGAssistantin JSON REST API luo vaarallisten aineiden lähetykset omasta toiminnanohjaus- tai logistiikkajärjestelmästä ja palauttaa lähettäjän ilmoituksen, tarkastuslistan ja kollien merkinnät sovellettavan määräyksen mukaan tarkistettuina. Se on tarkoitettu yrityksille, jotka integroivat nämä asiakirjat ERP-järjestelmäänsä, ja se kattaa myös koonnin.

Mitä API tekee

DGAssistantin ja toiminnanohjausjärjestelmän välinen yhteys

Lähetykset. DGAssistantin JSON REST API luo vaarallisten aineiden lähetyksen omasta toiminnanohjaus- tai logistiikkajärjestelmästä ja palauttaa lähettäjän ilmoituksen, tarkastuslistan ja kollien merkinnät valmiiksi sovellettavaa määräystä vasten tarkistettuina. Oma järjestelmä säilyttää kaupalliset tiedot; DGAssistant tuo määräysosaamisen ja asiakirjat.

Koonti. API kattaa myös useiden lähettäjien lähetysten koonnin kahdella akselilla. Sopimusakseli on päälähetys — varaus, meri- tai lentokuljetuksen koonti tai kokoomakuljetus maanteitse — osapuolineen, viitteineen, siihen liitettyine lähetyksineen, tilasiirtymineen ja historioineen. Fyysinen akseli on kuljetusyksikkö (kontti, ajoneuvo, perävaunu tai yksikkökuormausväline) ja kuljetus (merimatka, lento tai maantiematka) pysähdyksineen sekä tilin alukset, ajoneuvot ja sijaintipaikat. Yli puolet palvelusta on omistettu tälle osalle.

Avaa vaarallisten aineiden API:n määrittely

Kaksi toimintatapaa: eräkäsittely ja vuorovaikutteinen käsittely

Eräkäsittely. Yksi kutsu sisältää lähetyksen täydellisen määrittelyn kaikkine aineineen. Tämä tapa on tarkoitettu toiminnanohjaus- ja logistiikkajärjestelmille, jotka lähettävät kokonaisia, valmiiksi koottuja lähetyksiä.

Vuorovaikutteinen käsittely. Lähetys avataan ensin, ja aineet lisätään yksi kerrallaan. Jokainen vastaus sisältää juuri lisätyn tiedon tarkistusilmoitukset, jotta oma sovellus voi näyttää ne käyttäjälle lähetystä laadittaessa.

Ennalta määritetyt tiedot tai kutsussa määritettävät tiedot

Ennalta määritetyt tiedot. Tuotteet ja osapuolet — lähettäjät, kuljetuksen suorittajat, vastaanottajat, kuormaajat ja kuljettajat — luodaan etukäteen, ja API käyttää niiden koodeja. Tämä on yksinkertaisin toimintatapa, ja sitä suosittelemme, koska määräysten mukainen luokitus ratkaistaan kerran ja sitä käytetään uudelleen jokaisessa lähetyksessä.

Kutsussa määritettävät tiedot. Tuotteet ja osapuolet määritetään samassa kutsussa, jolla lähetys luodaan. Tapa sopii järjestelmille, joissa ei ole omaa tuoteluetteloa tai jotka lähettävät aineita vain satunnaisesti.

Palautettavat asiakirjat

API palauttaa samat asiakirjat, jotka sovellus laatii. Lähetyksen ja koonnin asiakirjat haetaan PDF-, XLSX- tai DOCX-muodossa, ja lähetyksen asiakirjat voidaan myös lähettää sähköpostitse suoraan palvelusta; rahtikirjan asiakirjat haetaan PDF-muodossa.

  • Kustakin lähetyksestä: sovellettavan määräyksen mukainen rahtikirja – ADR-rahtikirja, IMO:n vaarallisten aineiden ilmoitus tai IMDG:n multimodaalinen vaarallisten aineiden lomake sekä IATA:n mukainen lähettäjän vaarallisten aineiden ilmoitus –, tarkastuslista, kollien merkinnät täysikokoisina tai pienessä mukautetussa koossa sekä lentokuljetuksissa lentorahtikirjan tietolomake.
  • Päälähetyksestä: koontilastiluettelo, konttiluettelo, kunkin kuljetusyksikön pakkausluettelo, lähettäjäkohtainen lastausluettelo ja pääasiakirjan tietolomake.
  • Kuljetusyksiköstä: kontin tai ajoneuvon pakkaustodistus, multimodaalinen vaarallisten aineiden lomake, yksikön vaarallisten aineiden yhteenveto, tarkastuslista ennen todistuksen allekirjoittamista ja koontilähetyksen etiketti.
  • Matkasta: vaarallisten aineiden lastiluettelo, aluksella olevien yksiköiden välinen erotteluraportti, ADR:n kohdan 1.1.3.6 vapautusrajan raportti, matkan rajoituslomake, lastausluettelo, ilmoitus ilma-aluksen päällikölle (NOTOC) ja ajoneuvon yhdistetty rahtikirja.
  • Rahtikirjasta: luonnos, allekirjoitettu kopio, liitteenä oleva ADR-rahtikirja ja todisteraportti.

Mitä API tarkistaa

Lähetyksessä. Yhdessä kuljetettavien aineiden välinen erottelu, sovellettavan pakkausohjeen sekä rajoitettujen määrien ja poikkeusmäärien määrärajat, aineiden hyväksyttävyys kyseisessä kuljetusmuodossa, pakkauksen sallittavuus ja ilmoituksen täydellisyys. Jos jokin ei täytä vaatimuksia, vastauksessa kerrotaan, mitä sääntöä ei noudateta ja millä arvoilla, jotta viesti voidaan näyttää omassa sovelluksessa.

Koonnissa. Erottelu kuljetusyksikön sisällä, erottelu samaan kuljetukseen lastattujen yksiköiden välillä, ADR:n kohdan 1.1.3.6 raja-arvon laskenta kuljetukselle erittelyineen sekä tietoina palautettavat matkan rajoitukset, kuten tunnelirajoituskoodi tai sellaisten vaarallisten aineiden mukanaolo, joista voi aiheutua merkittävä turvauhka.

Katetut määräykset ja kuljetustyypit

ADR tiekuljetuksiin, IMDG merikuljetuksiin, IATA lentokuljetuksiin sekä 49 CFR. Kolmea päämääräystä hallitaan yhdessä eikä erillisinä moduuleina, joten lähetystä, jonka kuljetusmuoto vaihtuu, ei tarvitse laatia uudelleen.

Kaikkia seuraavia tuetaan niiden edellyttämine tietoineen: yhteenpakkaaminen, lisäpäällykset, säiliöt, kuljetus irtotavarana, tyhjät puhdistamattomat pakkaukset, jätteet, luokan 1 räjähteet – myös räjähteen nettomassa kollia kohti – ja luokan 7 radioaktiiviset aineet. Asiakirjojen tekstit laaditaan yhdeksällätoista kielellä.

API:n saatavuus

Palvelu on julkaistu kolmella alueella — Euroopassa, Amerikassa sekä Aasian ja Tyynenmeren alueella — ja kullakin alueella on oma osoitteensa, joten integraatio toimii sitä aluetta vasten, jolla tili on. Infrastruktuuri on kahdennettu, ja sitä valvotaan ympäri vuorokauden.

API:n käyttöönotto

Aluksi pyydetään maksuton kahden viikon kokeilu ja sen mukana palvelun tunnistetiedot. Todennuksessa käytetään OAuth 2.0 -protokollaa ja client credentials -myöntötapaa: oma järjestelmä hankkii käyttöoikeustunnuksen ja lähettää sen jokaisessa pyynnössä.

Täydellinen määrittely on julkaistu OpenAPI-muodossa. Sitä voi lukea ja tutkia, ja sen avulla voi luoda asiakasohjelman omalla ohjelmointikielellä jo ennen kuin integraatiokoodia on kirjoitettu riviäkään.

API-määrittelyn osat

Osa
YleiskatsausAPI:n ja sen käyttörajojen esittely, määrittelyn OpenAPI 3.0- ja 2.0-tiedostot ja kaikkien osien luettelo.Avaa
TodennusOAuth2-käyttöoikeustunnukset, jotka myönnetään client credentials -myöntötavalla, vaihtoehtona HTTP Basic -todennukselle kaikissa todennusta edellyttävissä toiminnoissa.Avaa
YhteystarkistuksetAPI:n saatavuuden, API-käyttäjän tunnistetietojen sekä todennuksellisten ja todennuksettomien pyyntöjen tarkistaminen.Avaa
PerustiedotVaaralliset aineet ja radionuklidit, pakkaukset ja pakkausohjeet, koodit, maat ja sijaintipaikat, joihin lähetykset, tuotteet ja koonti viittaavat.Avaa
TuotteetLuettelon yksinkertaiset tuotteet ja yhteenpakkaustuotteet, mukaan lukien yhteenpakkaustuotteen luominen vuorovaikutteisesti lähetystä varten.Avaa
OsapuoletEnnalta määritetyt osapuolet: lähettäjät, vastaanottajat, kuormaajat, kuljetuksen suorittajat, toimittajat ja kuljettajat.Avaa
Ajoneuvot, perävaunut ja aluksetTilien ajoneuvot, perävaunut ja alukset rekisteritunnuksineen, ADR-ajoneuvotyyppeineen ja vaatimustenmukaisuusasiakirjoineen.Avaa
Sijaintipaikat ja rajoituksetTilien satamat, lentoasemat ja terminaalit sekä rajoitukset, joita sovelletaan, kun niihin suunnitellaan tai niissä lastataan kuljetusyksikkö.Avaa
LähetyksetLähetyksen luominen koko sisältöineen (eräkäsittely) tai ensimmäisine sisältöineen (vuorovaikutteinen käsittely) sekä lähetysten haku ja poisto.Avaa
Lähetyksen sisältöTuotteet, yhteenpakkaukset ja lisäpäällykset, jotka lisätään vuorovaikutteisesti käsiteltävään lähetykseen tai poistetaan siitä.Avaa
Lähetyksen asiakirjatLähetyksen asiakirjat (rahtikirja, tarkastuslista, kollien merkinnät ja muut), niiden lähettäminen sähköpostitse sekä lukitut asiakirjat.Avaa
RahtikirjatCMR-rahtikirjat, sähköiset rahtikirjat (e-CMR) ja kotimaan rahtikirjat aina sen tarkistamisesta, kattaako e-CMR-pöytäkirja reitin, laatimiseen, toimitukseen ja peruuttamiseen.Avaa
KoontipyynnötAsiakastilien tai niiden puolesta niiden turvallisuusneuvonantajan tekemät koontipyynnöt sekä koontilähetyksen kokoajan päätökset.Avaa
PäälähetyksetPäälähetykset lähetyksineen ja hyväksyntäprosesseineen.Avaa
KuljetusyksikötKuljetusyksiköt, niiden sisältö, erottelutarkistukset ja siirtohistoria.Avaa
Kuljetukset ja pysähdyksetMerimatkat, lennot ja maantiematkat pysähdyksineen ja kuljetusyksiköineen, erottelutarkistukset, kuorman raja-arvon laskenta (ADR 1.1.3.6) ja rajoitukset.Avaa
Koonnin asiakirjatPäälähetysten, kuljetusyksiköiden ja kuljetusten asiakirjat.Avaa
WebhookitTilin webhook-tilaukset, niiden testaus ja viimeisimmät toimitukset.Avaa

Integroinnin nopeuteen ja helppouteen voi tutustua kahden viikon kokeilujaksolla ilman sitoumuksia