Tilastotietojen noutaminen API:n kautta

Voit luoda tilastoraportteja seuraavilla tavoilla:

• Voit käyttää Opterin tilasto-ohjelmointirajapintaa, jonka avulla voi noutaa tilastotietoja Opterista ja sen jälkeen luoda tilastoraportteja Opterin ulkopuolella.

  On mahdollista ohjelmoida ratkaisu, jolla tehdään kutsu Opterin tilasto-API:lle. Tämän jälkeen saadut tilastotulokset voidaan esittää haluamallanne tavalla. Työnkulku voidaan automatisoida niin, että halutut tilastotiedot haetaan Opterista määritetyin aikavälein. Jos tilastot halutaan esimerkiksi esittää koontinäytöllä, voi olla hyvä, että tilastot haetaan kerran tunnissa.

• Voit halutessasi laatia tilastoraportin manuaalisesti. Lisätietoa: Tilastoraportit.

Näin tilasto-API toimii

• Voit noutaa Opterissa olevia kuljetustilauksiin liittyviä tietoja, kuten toimitusaikojen tarkkuutta koskevia tietoja, tilasto-ohjelmointirajapinnan (API) avulla. Tilasto-API:n toimittamat tiedot ovat raaka- eli perusdataa Opterin tietokannasta.

• Tilastojen API-käyttäjä tarvitsee API-avain (katso Vaihe 2: Luo API-avain alla).

• Kun teet API-kutsun, saat vastauksena kaikki tiedot, jotka olet valinnut noudettavaksi samalla kutsulla. (Tilastotietoja ei jaeta pienempiin osiin eikä sivutusta tehdä.)

• Kun teet API-kutsun, saat tiedot sellaisina kuin ne sillä hetkellä Opterin tietokannassa ovat.

• Voit noutaa tietoja niin usein kuin haluat. Tietoja ei kuitenkaan kannata pyytää useammin kuin on tarpeen.

• API-kutsu:ta kutsuttaessa on pakollista määrittää, miltä ajanjaksolta tilastot halutaan (dateFrom ja dateTo ) ja mihin päivämäärätyypiin tilastojen tulisi perustua (dateType). Lisätietoa: alla oleva taulukko Tilastotietojen perustana olevan päivämäärätyypin valitseminen.

Vaihe 1: Suunnittele

Seuraavista kohdista saat vaiheittaiset ohjeet tilasto-API:n käyttöön. Suosittelemme aloittamaan näin:

1. Mieti, mitä haluat saavuttaa, eli mitä haluat saada tulokseksi ja miksi.

2. Päätä, kuinka usein tilastotiedot noudetaan Opterista.

   Jos tilastot halutaan esimerkiksi esittää koontinäytöllä, voi olla hyvä, että tilastot haetaan kerran tunnissa. Jos tilastoja halutaan käyttää kunkin päivän lopussa tapahtuvaan seurantaan, tilastotiedot voi noutaa aina päivän lopussa.

3. Päätä, kenellä on pääsy tilasto-API:hin. Kaikki tilasto-API:n käyttäjät saavat pääsyn kaikkiin tietoihin, mukaan lukien asiakastietoihin, hintoihin, laskuihin jne.

Vaihe 2: Luo API-avain

Tilasto-API:n käyttämiseen tarvitaan API-avain. Tee näin:

1. Valitse Asetukset > API-käyttöoikeus (ja välilehti Yleinen).

2. Luo uusi käyttäjä valitsemalla ja syöttämällä Nimi.

   Kentässä API-avain näytetään luotu API-avain.

3. Kenttään Kuvaus voit kuvata, mihin käyttäjällä on pääsy.

4. Napsauta välilehteä Käyttöoikeus.

5. Kaksoisnapsauta kohtaa Tilastot luettelossa Poissuljettu, jolloin Tilastot siirretään luetteloon Sisältyy.

   Tämä tarkoittaa, että käyttäjä saa pääsyn kaikkiin Opterin tilastotietoihin tilasto-API:n kautta API-avaimen avulla.

6. Tallenna muutokset valitsemalla .

Vaihe 3: Siirry Swagger-dokumentaatioon

1. Tilasto-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ä tilasto-API:n Swagger-dokumentaatiota, ota yhteyttä EDI-tiimiin: .

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

   

Tietomallin käyttäminen

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

Kokeile API:n käyttöä

Jos haluat testata API:n käyttöä, voit tehdä sen Swagger-sivulla tai käyttää testiohjelmaa, esimerkiksi Postmania.

Jos haluat tehdä testikutsun tilasto-API:lle Swagger-sivulla ja nähdä tulokset, toimi seuraavasti:

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

   

2. Napsauta Authorise. Kopioi API Opterin API-käyttöoikeus -ikkunasta, liitä se Value-kenttään ja napsauta Authorise. Nyt ikkunassa lukee Authorised. Napsauta Sulje.

   (API-avain luotiin osoitteessa Vaihe 2: Luo API-avain edellä.)

3. Vieritä alaspäin kohtaan Tilastot ja napsauta GET.

   

   Kaikki parametrit (”queries”) näytetään.

4. Napsauta Kokeile -painiketta.

5. Valitse avattavasta luettelosta dateType ( pakollinen). Lisätietoa vaihtoehdoista on jäljempänä olevassa taulukossa Tilastotietojen päivämäärätyypin valitseminen.

6. Valitse ajanjakso, jolta haluat tilastotiedot, valitsemalla dateFrom ( pakollinen) ja dateTo ( pakollinen ).

   Päivämäärät ovat muodossa ”vvvv-mm-pp”, esimerkiksi ”2024-08-19”. Jos haluat syöttää sekä päivämäärän että kellonajan, kirjoita välilyönti päivämäärän ja kellonajan väliin, esimerkiksi ”2024-08-19 13:30”.

   Jos syötät vain päivämäärän, käytetään oletusaikaa 00:00.

7. Valitse haluamasi tilastotiedot määrittämällä arvoksi ”true” kyseisten parametrien pudotusvalikosta.

   Jos esimerkiksi asetat includeDeliveries-arvoksi " true", kaikki tilauksia koskevat tiedot haetaan, ja kaikki skannauksia koskevat tiedot haetaan, jos asetat includeScans-arvoksi "true ".

   (Oletusasetus on ”false”, joten arvoksi tarvitsee määrittää ”true” vain niiden parametrien osalta, jotka haluat sisällyttää tilastotietoihin.)

   Yksityiskohtaiset tiedot siitä, mitä tietoja haetaan, jos valitset esimerkiksi includeDeliveries- ja includeScans-kohtiin "true" , on esitetty swagger-dokumentaation alempana kohdassa Schemas. Napsauta Statistics.Delivery ja Statistics.Scan. Näet lisätietoja napsauttamalla kohtaa ”[...]”.

   

8. API-versiokenttään voit valita tietyn version tai jättää kentän tyhjäksi, jos haluat käyttää API:n uusinta versiota. Jos esimerkiksi haluat käyttää versiota 1.0, kirjoita kenttään ”1.0”.

9. Lähetä API-kutsu napsauttamalla Suorita-painiketta. Tulos näytetään kohdassa Vastaukset.

   Server response (Palvelimen vastaus) -kohdassa tulos/vastaus näytetään JSON-muodossa. Lataa JSON-tiedosto napsauttamalla Lataa-painiketta.

   Jos haluat testata samaa API-kutsua esimerkiksi Postman-työkalulla, voit kopioida Curl-koodiikkunassa näkyvän API-kutsun .

10. Jos haluat testata uudelleen (esimerkiksi eri parametreilla), tyhjennä vastaukset valitsemalla Suorita-kohdan vieressä oleva Tyhjennä. Voit sitten tehdä API-kutsun uudelleen painamalla Execute ja tarkastella tulosta.

Tilastotietojen päivämäärätyypin valitseminen

Kun teet API-kutsun, voit käyttää parametreja dateFrom (päivämäärästä ja kellonajasta) ja dateTo ( päivämäärästä ja kellonajasta) valitaksesi ajanjakson, jolta tilastotiedot haetaan.

DateType-parametrilla voit valita päivämäärän tyypin, johon tilastotiedot perustuvat, kuten alla olevassa taulukossa on esitetty.

dateType	Selitys
TransportDate	Kattaa tilaukset, joiden Tilauspäivä on valitulla aikavälillä. Noutoon sisällytetään kaikki tällaisia tilauksia koskevat tiedot, mukaan lukien aikavälin ulkopuoliset laskut, skannaukset jne.
ScanDate	Kattaa skannausrivit (kolli- tai rahtikirjaskannaukset). Noutoon sisällytetään kaikki tiedot tilauksista, joissa on valitulla aikavälillä tehtyjä skannauksia riippumatta tilausten tilauspäivästä, laskujen laskutuspäivästä jne. Laskut ja tilitykset eivät välttämättä ole täydellisiä, vaan mukana ovat vain ne tilaukset, joissa on skannauksia kyseisellä aikavälillä. DateFrom- ja dateTo -parametreissa voi olla tarpeen määrittää sekä päivämäärä että kellonaika. Katso jäljempänä oleva esimerkki.
InvoiceDate	Kattaa laskut, joiden päivämäärä on valitulla aikavälillä. Kaikki tällaisiin laskuihin sisältyvien tilausten tiedot voidaan sisällyttää noutoon. Tätä sovelletaan, vaikka kyseessä olisi vain tilauksen lisälasku (esimerkiksi uusi artikkeli tai hyvitys). Tilauksia, joiden lasku ei vastaa valittua aikaväliä, ei oteta mukaan, vaikka niiden tilauspäivä, skannauspäivä jne. näin tekisi.
BillDate	Kattaa tilitykset, joiden tilityspäivä on valitulla aikavälillä vastaavalla tavalla kuin edellä.
ChangeDate	Kattaa tilaukset, joita on muutettu valitulla aikavälillä. Tämä ei tarkoita ainoastaan muutoksia, jotka on tehty avaamalla tilaus, tekemällä muutoksia ja tallentamalla ne. Mukana ovat myös esimerkiksi ajojärjestelyssä ja sovelluksissa tehdyt muutokset: Jos kuljettaja muuttaa statuksen Opter Driver -sovelluksessa statuksesta Lastattu statukseen Purettu, tilastoissa näytetään, että tilausta on muutettu. Jos ajojärjestelyssä muutetaan tilauksen statusta tai tilaus yhdistetään yhteislastaukseen, tilastoissa näytetään, että tilausta on muutettu. DateFrom- ja dateTo -parametreissa voi olla tarpeen määrittää sekä päivämäärä että kellonaika. Katso jäljempänä oleva esimerkki. Valitulla aikavälillä muutetuista tilauksista näytetään päivämäärä ja kellonaika, jolloin tilausta on muutettu viimeksi (valitulla aikavälillä). Voit saada lisätietoja tilausten muutoksista tarkastelemalla lokitietoja Opterin tilausten vastaanoton ruudussa Tapahtumaloki.

Huomioi seuraavat seikat

• Tilauksista ei ole historiatietoja. Kun teet API-kutsun, saat tiedot sellaisina kuin ne sillä hetkellä Opterissa ovat.

  On kuitenkin mahdollista saada tilastoja siitä, mitä tilauksia on muutettu tietyllä aikavälillä. Katso edellä oleva kohta ChangeDate. Tilastot eivät näytä, mitä on muutettu, vaan ainoastaan päivämäärän ja kellonajan, jolloin tilausta on muutettu viimeksi.

  Voit saada lisätietoja tilausten muutoksista tarkastelemalla lokitietoja Opterin tilausten vastaanoton ruudussa Tapahtumaloki.

• Opter tarjoaa tilasto-API:n käyttöön, mutta käyttäjät ovat itse vastuussa siitä, miten API-kutsujen tuloksia/vastauksia käsitellään ja analysoidaan. Opter ei tarjoa siihen työkaluja.

Esimerkki

Muutettuja tilauksia kuvaavat tilastotiedot

Oletetaan, että haluat noutaa seuraavat tiedot:

• Tilaukset, joita on muutettu tietyllä aikavälillä, esimerkiksi joulukuussa 2024. Syötä päivämääräjakso parametreihin dateFrom " 2024-12-01" ja dateTo " 2025-01-01 ". (Jos syötät vain päivämäärän, käytetään oletusaikaa 00:00.)

• Tilaukset, joita on muutettu tietyn päivämäärän jälkeen nykyiseen päivään saakka, esimerkiksi päivämäärästä ”2024-07-22” alkaen nykyiseen päivämäärään ja kellonaikaan saakka. Anna päivämäärä dateFrom-parametrissa "2024-07-22" ja päivämäärä ja kellonaika dateTo -parametrissa "2024-07-26 13:30" (tämän päivän päivämäärä ja kellonaika).

  Jos et syötä kellonaikaa, käytetään oletusaikaa 00:00. Tämä tarkoittaa, että jos annat dateTo-kohtaan vain (tämän päivän) päivämäärän, et näe, mitkä tilaukset ovat muuttuneet tänään.

• Tilaukset, joita on muutettu edellisen 10 minuutin aikana.

  Jos esimerkiksi kellonaika on 10:20 ja päivämäärä on 2024-07-26, annat tämän päivän päivämäärän ja 10 minuuttia sitten olleen kellonajan dateFrom-parametrin " 2024-07-26 10:10" ja tämän päivän päivämäärän ja tämänhetkisen kellonajan dateTo -parametrin "2024-07-26 10:20".

Valitse "ChangeDate" avattavasta date Type-luettelosta(Lisätietoa: taulukko yllä, ChangeDate.).

Valitse "true" includeDeliveries-pudotusvalikosta.

Vianetsintä

• Jos et löydä tilastojen API:tä swagger-dokumentaatiosta, tarkista, että olet valinnut "Opter API v1" Web-sivun oikeassa yläkulmassa olevan Valitse määritelmä -pudotusvalikosta. Katso kuva yllä.

• Jos API-avain ei toimi, voit luoda uuden API-avaimen ikkunassa API-käyttöoikeus välilehdellä Yleinen kentän API-avain vieressä. Luo uusi API-avain valitsemalla Uusi avain ja tallenna se napsauttamalla painiketta . Sen jälkeen voit käyttää sitä tilasto-API:n käyttämiseen.

• Jos sinulla on kysyttävää tai tarvitset apua vianetsinnässä, ota yhteyttä EDI-tiimiin: .

Katso myös

• Tilastoraportit

• Hae tilastotietoja API:n kautta, Hiilidioksidipäästöt grammoina.