Voimassa alkaen: Opter 2023.12.203

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 luoda tilastoraportin manuaalisesti milloin vain. 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.

• Tilasto-API:n käyttämiseen tarvitaan API-avain (katso alla oleva kohta Vaihe 2: API-avaimen luominen).

• 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-kutsua tehtäessä on määritettävä aikaväli, jolta tilastot halutaan (dateFrom ja dateTo), sekä päivämäärätyyppi, johon tilastojen tulee perustua (dateType). Lisätietoa: Tilastotietojen päivämäärätyypin valitseminen jäljempänä.

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”.

   

Käytä tietomallia (valinnainen)

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

Testaa API:n käyttöä (valinnainen)

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. Valitse Authorize. Kopioi API-avain Opterin ikkunasta API-käyttöoikeus, liitä se kenttään Value ja valitse Authorize. Nyt ikkunassa lukee Authorized. Valitse Close.

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

3. Selaa alaspäin kohtaan Statistics ja valitse GET.

   

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

4. Napsauta painiketta Try it out.

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

6. Määritä aikaväli, 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 kohdan includeDeliveries arvoksi ”true”, kaikki tilauksia koskevat tiedot haetaan, ja jos asetat kohdan includeScans arvoksi ”true”, kaikki skannauksia koskevat tiedot haetaan.

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

   Tarkemmat tiedot siitä, mitä tietoja noudetaan, jos esimerkiksi parametrien includeDeliveries ja includeScans arvoksi asetetaan ”true”, on alempana Swagger-dokumentaatiossa kohdassa Schemas. Valitse Statistics.Delivery ja Statistics.Scan. Näet lisätietoja napsauttamalla kohtaa ”[...]”.

   

8. Jos haluat käyttää tiettyä versiota, syötä se kenttään api-version. Jos haluat käyttää API:n uusinta versiota, jätä kenttä tyhjäksi. Jos esimerkiksi haluat käyttää versiota 1.0, kirjoita kenttään ”1.0”.

9. Lähetä API-kutsu napsauttamalla painiketta Execute. Tulokset näytetään kohdassa Responses.

   Tulos/vastaus näytetään JSON-muodossa kohdassa Server response. Voit ladata JSON-tiedoston napsauttamalla painiketta Download.

   Jos haluat testata samaa API-kutsua esimerkiksi Postman-työkalussa, voit kopioida API-kutsun koodi-ikkunasta Curl.

10. Jos haluat testata uudelleen (esimerkiksi eri parametreilla), napsauta kohtaa Clear kohdan Execute vieressä, jolloin kohta Responses tyhjennetään. Sen jälkeen voit lähettää uuden API-kutsun ja tarkastella tuloksia valitsemalla Execute.

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

Kun tehdään kutsu tilasto-API:lle, on valittava ajanjakso, jolta tilastotiedot noudetaan, käyttämällä parametreja dateFrom (alkaen-päivämäärä ja -kellonaika) ja dateTo (saakka-päivämäärä ja -kellonaika).

Päivämäärätyyppi, johon tilastotiedot perustuvat, valitaan käyttämällä parametria dateType oheisen taulukon mukaisesti.

dateType	Kuvaus
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ä. Parametreissa dateFrom ja dateTo 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. Parametreissa dateFrom ja dateTo 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.

Rajoitukset

• 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ä aikaväliksi 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. Syötä päivämääräksi parametriin dateFrom ”2024-07-22” ja päivämääräksi ja kellonajaksi parametriin dateTo ”2024-07-26 13:30” (senhetkinen päivämäärä ja kellonaika).

  Jos et syötä kellonaikaa, käytetään oletusaikaa 00:00. Tämä tarkoittaa, että jos syötät vain (nykyisen) päivämäärän kohtaan dateTo, et näe, mitä tilauksia on muutettu tänään.

• Tilaukset, joita on muutettu edellisen 10 minuutin aikana.

  Jos nykyinen kellonaika on esimerkiksi 10.20 ja päivämäärä 26.7.2024, syötä parametriin dateFrom nykyinen päivämäärä ja 10 minuuttia sitten ollut kellonaika ”2024-07-26 10:10” ja parametriin dateTo nykyinen päivämäärä ja kellonaika ”2024-07-26 10:20”.

Valitse ”ChangeDate” pudotusvalikosta dateType. (Lisätietoa:ChangeDate.)

Valitse ”true” pudotusvalikosta includeDeliveries.

Vianetsintä

• Jos et löydä tilasto-API:ta Swagger-dokumentaatiosta, tarkista, että olet valinnut pudotusvalikkokohdan ”Opter API v1” sivun oikeassa yläkulmassa olevasta pudotusvalikosta Select a definition. 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: .

---