Helsingin seudun ympäristöpalvelut
eRaportin tilastorajapinta

Rajapinta tarjoaa ohjelmalisen väylän jäte- ja vesikulutustietojen hyödyntämiseen. Tietoja voi hakea rajapinnasta eRaportissa muodostetuilla koontiraporttitunnuksilla. Raporttitunnusten kanssa tulee huomioida, että tuotanto- ja tuotantotesti-ympäristöihin on kuhunkin omat koontiraporttitunnuksensa. Tuotantotesti-ympäristön koontiraporttien hallinta tapahtuu samaan tapaan eRaportti-sovelluksen kautta kuin tuotantoympäristössä.

Halutut kohteet lisätään ensin eRaportissa koontiraportille ja tämän jälkeen koontiraportin API-osiosta voidaan noutaa oikeat REST-osoitteet, joilla tiedot voi noutaa JSON-muodossa.

Siirry tästä tuotantotesti-ympäristön eRaportti sovellukseen

1 - Rajapinnan käyttöehdot

2 - Julkaisuhistoria

• 12.09.2016 Dokumentti + rajapinta (R1.6.1 b51 12.09.2016 16:00 #88f7335e7a)
• 13.09.2016 Dokumentti + rajapinta (R1.6.2 b52 13.09.2016 11:00 #8445744c9e)
• 10.10.2016 Dokumentti (R1.6.7 b57 26.09.2016 16:30 #ae78094de3)
  • Päivitetty dokumenttiin IP:eiden tilalle DNS-nimi
• 16.12.2020 Dokumentti (R3.2 b110 7.12.2020 12:00 #e44173a013)
  • Päivitetty dokumenttiin listojen kaksivaiheinen nouto

3 - Rajapinnan tarjoamat palvelut

• 3.1 - Rajapinnan tila
• 3.2 - Rajapinnan versio
• 3.3 - Kulutustietorajapinta
• 3.4 - Palvelukuvaustietorajapinta

3.1 - Rajapinnan tila

Palvelu palauttaa rajapinnan tilan esim. automaattista valvontaa tai virheen etsintää varten. Kun palvelu toimii normaalisti, rajapinta palauttaa sanoman runko-osassa tekstin OK. Virhetilanteen yhteydessä sanoman vastauksen runko-osa alkaa tekstillä WARN tai FAIL ja runko-osan loppu sisältää vapaana tekstinä hieman tarkempaa tietoa virhetilanteesta.

3.1.1 - Rajapinnan kutsuminen

3.1.4 - Esimerkkisanoma tilakyselyn testaamiseksi.

• Palvelun osoite: https://raportit.hsy.fi:8443/report/rest/v1/status/
• Metodi: GET
• Vastaus onnistuneeseen kyselyyn: OK

3.2 - Rajapinnan versio

Palvelu palauttaa rajapinnan version.

3.2.1 - Rajapinnan kutsuminen

3.2.4 - Esimerkkisanoma versiokyselyn testaamiseksi.

• Palvelun osoite: https://raportit.hsy.fi:8443/report/rest/v1/version/
• Metodi: GET
• Vastaus onnistuneeseen kyselyyn: KEHITYSYMPÄRISTÖ: R1.6.0 b50 29.06.2016 11:00 #, running since 29.08.2016 13:14

3.3 - Kulutustietorajapinta

Kulutustiedot voidaan noutaa rajapinnasta kuukausittain tai vuosittain jaksotettuna. Sanoma voi sisältää kerrallaan yhden tai usean kohteen kulutustiedot. Lisäksi voidaan valita sisällytetäänkö sanomaan jäte- ja/tai vesitiedot.

Usean kohteen tietoja haetaessa rajapintakutsun voi tehdä pollaus-tyyppisesti kahdessa vaiheessa tai suoraan yhdellä kutsulla. Isommille listoille suosittelemme kaksivaiheista noutoa, koska muuten kutsun suoritusaika venyy pitkäksi. Pollaus-menetelmällä raportin muodostus käynnistetään ensin yhdellä kutsulla ja tämän jälkeen jäädään pollaamaan listan valmistumista. Raportti voidaan ladata, kun rajapinta ilmoittaa raporttiajon valmistumisesta.

• Nouto yhdessä vaiheessa: Kutsu rajapintaa ../report/rest/v1/reporting/... osoitteella ja odota kunnes valmis raportti latautuu.
• Nouto kahdessa vaiheessa: Kutsu ensin toistamiseen /report/rest/v1/is-reporting-ready/... osoitetta, ja nouda raportti yllä olevalla osoiteella ensimmäisen kutsun vastattua READY. Kaksivaiheinen nouto käytettävissä vain useamman kohteen raporttia noudettaessa.
  
  Ensimmäinen pyyntö käynnistää siis raportin muodostamisen kyseiselle koontilistalle, ja palvelu palauttaa koodin INIATED. Tämän jälkeen listan valmistumista voi seurata pollaamalla samaa osoitetta. Työn ollessa käynnissä, rajapinta palauttaa koodia PENDING. Työn valmistuttua rajapinta palauttaa READY-koodin. Jos palvelukuvaus vastaa jatkuvasti INIATED, parametrina annettu koontiraporttitunnus on virheellinen tai raporttiajossa on tapahtunut virhe.

Jätetiedot: Rajapinnassa esitetyt jätetiedot päivittyvät raporttikohteen laskutusrytmin mukaisesti, eli raportilla esitetyt jätetiedot perustuvat laskutuksen tietoihin. Näin ollen kohteiden tiedot päivittyvät rajapinnassa 1,2,4,6 tai 12 kuukauden jaksoissa.

Vesitiedot:Raportilla esiintyvät vesitiedot perustuvat laskutukseen ilmoitettuihin vesimittarilukemiin ja lukemien tarkkuus riippuu kunkin kohteen lukemienilmoitusrytmistä. Useissa kohteissa lukema ilmoitetaan ainoastaan kerran vuodessa. Lukemat on mahdollista ilmoittaa sähköisen rajapinnan kautta, jolloin ilmoitusrytmi voi olla kerran kuukaudessa.

Vesitilastoissa on vuodenvaihteeseen liittyvä poikkeuskäsittely, joka vuoden vaihtumisen jälkeen täydentää tilastot edellisvuoden lopun osalta arvioidulla kulutuksella. Tämä toiminto suoritetaan, jotta täydet vuodet olisivat heti vuoden vaihtumisen jälkeen keskenään vertailtavissa, eikä vasta sitten kun käyttöpaikalle saapuu seuraava ilmoitettu lukema. Eli esimerkiksi käyttöpaikalle, jolla viimeisin lukema on kesäkuulta:

• Ennen vuodenvaihdetta näytetään käyttöpaikalle vain todellinen ilmoitettu kulutus. Eli, tässä tapauksessa ajalta tammikuu - kesäkuu.
• Vuodenvaihteen jälkeen näytetään kulutukseksi tammikuu-kesäkuu -todellinenkulutus plus kesäkuu-joulukuu -laskennallinenkulutus laskutuksen arviokulutuksen mukaan.
• Kun käyttöpaikan seuraava lukemailmoitus saapuu vuodenvaihteen jälkeen, päivittyy edellisen vuoden tilasto näyttämään todellista kulutusta koko vuoden osalta.

Tämä menettely varmistaa sen, että täydet vuodet ovat keskenään vertailtavissa. Arvioitu kulutus täsmää pääsääntöisesti hyvin todellisen kulutuksen kanssa, ellei käyttöpaikassa ole esim. tehty remonttia tai käyttö on hyvin vaihtelevaa.

3.3.1 - Rajapinnan kutsuminen

Taulukoissa on esitetty erillään rest-kutsun perustiedot sekä varsinaiset kyselyosat yhden kohteen tai yhden koontilistan kohteiden tiedoille.

Kutsun tiedot

Kutsun osoiteen loppu yksittäiselle kohteelle

Kutsun osoiteen loppu koontilistalle

Poikkeuskäsittelyt

3.3.2 - Kyselyosan parametrit

3.3.3 - Paluusanoman kentät

Esimerkki kaksivaiheisen noudon vastauksesta:

• {
    "status": "INITIATED",
    "success": true,
    "created": "2020-12-16T09:36:02.196+02:00"
  }
  	

• INIATED (Muodostus aloitettu),
• INPROGRESS (Muodostus on jo käynnissä ja tulos ei ole vielä valmis),
• READY (Valmiit kuvaukset ladattavissa latausrajapinnan kautta)
• ERROR (Virhe tilanne, muodostuksen käynnistäminen ei ole mahdollista tällä hetkellä.)
• REFUSED (Ruuhkatilanne, liian monta samanaikaista muodostusta käynnissä tai sama raportti ladattu yli kolme kertaa saman päivän aikana),

Esimerkki raporttisanomasta:

Sanoman kentät:

3.3.4 - Esimerkkisanomat joilla voi testata tilastorajapintaa. Tuotantokäyttöä varten ole yhteydessä HSY:hyn. Katso lisätietoja kohdasta Rajapinnan käyttöehdot.

• Palvelun osoite: https://raportit.hsy.fi:8443/report/rest/reporting/waste/list/MOCK-LIST-ID/YEARLY/fi
• Metodi: GET
• Headers:
  • Content-type: application/json;charset=UTF-8
  • X-API-KEY: HSYTEST51_9NOOzOv77pD4Mhx2Kgol86NFSdl9rpOPGNzlQ0A7
• Vastaus onnistuneeseen kyselyyn:

    [
       {
         "messages": [
           "Antamallasi jätepalvelutunnus-yhdistelmällä ei löytynyt voimassa olevaa jätepalvelua.(WS12345)"],
         "moment " : "2003" ,
         "customers" : [
           {
             "address " : "Esimerkkitie 1, 00100, Helsinki (55555 / BB111111111)",
             "wasteContractNumber " : "BB111111111",
             "waterUsageLocationNumber " : "55555",
             "waterUsageLocationAddress " : "Esimerkkitie 1",
             "wasteCollectionAddress " : "Esimerkkitie 1, 00100, Helsinki",
             "waste": [
               {
                 "type " : "Biojäte",
                 "amount " : "1000",
                 "cost " : "500",
                 "amountUnit " : "Kg"
                 "costUnit " : "EUR"
               },
               {
                 "type " : "Sekajäte",
                 "amount " : "1000",
                 "cost " : "500",
                 "amountUnit " : "Kg",
                 "costUnit " : "EUR",
               },
               {
                 "type " : "Muut",
                 "amount " : null,
                 "cost " : "1548",
                 "amountUnit " : null,
                 "costUnit " : "EUR",
               }
            ],
             "water": [
               {
                 "type " : "Vedenkulutus vuosittain",
                 "amount " : "1000",
                 "cost ": null ,
                 "amountUnit " : "m³" ,
                 "costUnit " : "EUR"
               }
            ]
           }
        ]
       }
    ]
  

• Vastaus kun koontiraporttia ei löydy:

  {
    "error": "Koontiraporttia ei löytynyt annetulla tunnuksella",
    "success": "false"
  }
  

3.4 - Palvelukuvaustietorajapinta

Rajapinnasta on noudettavissa palvelukuvaustiedot koontiraportin jätepalvelusopimuksille. Yli neljä kohdetta sisältäville listoille listojen nouto tulee suorittaa kahdessa vaiheessa. Ensimmäisessä vaiheessa käynnistetään listan muodostus, ja toisessa vaiheessa noudetaan edellisen kutsun muodostamat palvelukuvaustiedot. Palvelukuvauksen tiedot voi noutaa uudestaan 12 tunnin välein.

Palvelukuvausten muodostaminen käynnistetään tekemällä GET-pyyntö käynnistysosoitteeseen. Kutsu ei vaadi Api-avainta.

Ensimmäinen pyyntö käynnistää palvelukuvausten muodostamisen kyseiselle koontilistalle, ja palvelu palauttaa koodin INIATED. Tämän jälkeen listan valmistumista voi seurata pollaamalla samaa osoitetta. Työn ollessa käynnissä, rajapinta palauttaa koodia PENDING. Rajapinta ilmoittaa työn valmistumisesta READY-koodilla. Jos palvelukuvaus ei valmistu useasta käynnistysyrityksestä huolimatta, tarkista koontiraporttitunnus, sillä käynnistäminen ei anna virhettä väärästä koontiraportitunnuksesta.

Palvelukuvausten lataaminen voidaan suorittaa käynnistämisen valmistuttua tai jos koontilistaan kuuluu alle viisi kohdetta, voidaan palvelukuvaukset ladata ilman esikäynnistystä.

Palvelukuvausten muodostuksen aikana on mahdollista esiintyä tietoliikennekatkoksia tai kohteiden tiedoissa voi olla virheitä, joilloin yksittäisen listan kohteen tietojen haku voi epäonnistua. Näissä tapauksissa kohteen jäteastioiden tilalla on tyhjä astiarivi ja messages-kentässä kerrotaan tietojen latauksen epäonnistuneen.

3.4.1 - Rajapinnan kutsuminen

Kutsun tiedot

Kutsun osoiteen loppu koontilistan jätepalvelukuvauksille

3.4.2 - Kyselyosan parametrit

3.4.3 - Paluusanoman kentät

Palvelukuvausten muodostuksen käynnistys -kyselyn vastaukset

• {
    "status": "INITIATED",
    "success": true,
    "created": "2020-12-16T09:36:02.196+02:00"
  }
  	

• INIATED (Muodostus aloitettu),
• INPROGRESS (Muodostus on jo käynnissä ja tulos ei ole vielä valmis),
• READY (Valmiit kuvaukset ladattavissa latausrajapinnan kautta)
• ERROR (Virhe tilanne, muodostuksen käynnistäminen ei ole mahdollista tällä hetkellä.)
• REFUSED (Ruuhkatilanne, liian monta samanaikaista muodostusta käynnissä tai sama raportti ladattu yli kolme kertaa saman päivän aikana),

Esimerkkivastaussanoma palvelukuvausten latauspyynnölle:

Sanoman kentät:

Jätepalvelukuvauksen kentät (wasteCustomerDetails):

3.4.4 - Esimerkkisanomat joilla voi testata tilastorajapintaa. Tuotantokäyttöä varten ole yhteydessä HSY:hyn. Katso lisätietoja kohdasta Rajapinnan käyttöehdot.

• Palvelun osoite: https://raportit.hsy.fi:8443/report/rest/v1/details/waste/MOCK-LIST-ID/fi
• Metodi: GET
• Headers:
  • Content-type: application/json;charset=UTF-8
  • X-API-KEY: HSYTEST51_9NOOzOv77pD4Mhx2Kgol86NFSdl9rpOPGNzlQ0A7
• Vastaus onnistuneeseen kyselyyn:

  {
      "statisticsDetails": [
          {
              "queryParameters": {
                  "usageLocationNumber": null,
                  "waterInvoice": "0",
                  "serviceNumber": "WS-MOCK-WASTE-ID",
                  "wasteInvoice": "0",
                  "created": "2018-10-21 19:02:04",
                  "postalCode": "0",
                  "customerNumber": "0"
              },
              "messages": [
                  "MOCK DATA"
              ],
              "wasteCustomerDetails": {
                  "serviceNumber": "WS-MOCK-WASTE-ID",
                  "postalCode": "0",
                  "invoiceNumber": "0",
                  "address": "Mocktie 1",
                  "collectionPoints": [
                      {
                          "name": "1",
                          "containers": [
                              {
                                  "collectionInterval": "1 krt/viikko ti",
                                  "wasteType": "Sekajäte",
                                  "containerSize": "660 l",
                                  "containerCount": "1",
                                  "nextCollectionDate": "23.10.18",
                                  "containerType": "astia isopyöräinen",
                                  "containerOwner": "Vuokra"
                              },
                              {
                                  "collectionInterval": "1 krt/viikko pe",
                                  "wasteType": "Biojäte",
                                  "containerSize": "200 l",
                                  "containerCount": "1",
                                  "nextCollectionDate": "26.10.18",
                                  "containerType": "säkki ",
                                  "containerOwner": "-"
                              },
                              {
                                  "collectionInterval": "1 krt/viikko pe",
                                  "wasteType": "Biojäte",
                                  "containerSize": "240 l",
                                  "containerCount": "1",
                                  "nextCollectionDate": "26.10.18",
                                  "containerType": "astia ",
                                  "containerOwner": "Vuokra"
                              }
                          ]
                      },
                      {
                          "name": "2",
                          "containers": [
                              {
                                  "collectionInterval": "1 krt/viikko ti",
                                  "wasteType": "Sekajäte",
                                  "containerSize": "660 l",
                                  "containerCount": "1",
                                  "nextCollectionDate": "23.10.18",
                                  "containerType": "astia isopyöräinen",
                                  "containerOwner": "Vuokra"
                              },
                              {
                                  "collectionInterval": "1 krt/viikko pe",
                                  "wasteType": "Biojäte",
                                  "containerSize": "200 l",
                                  "containerCount": "1",
                                  "nextCollectionDate": "26.10.18",
                                  "containerType": "säkki ",
                                  "containerOwner": "-"
                              },
                              {
                                  "collectionInterval": "1 krt/viikko pe",
                                  "wasteType": "Biojäte",
                                  "containerSize": "240 l",
                                  "containerCount": "1",
                                  "nextCollectionDate": "26.10.18",
                                  "containerType": "astia ",
                                  "containerOwner": "Vuokra"
                              }
                          ]
                      }
                  ]
              },
              "waterCustomerDetails": null
          }
      ],
      "success": true,
      "created": "2018-10-21T19:02:04.993+03:00"
  }

• Vastaus kun koontiraporttia ei löydy:

  {
    "error": "Koontiraporttia ei löytynyt annetulla tunnuksella",
    "success": "false"
  }
  

• Vastaus kun yhdelle koontilistan kohteelle ei löydy tietoja:

  {
      "statisticsDetails": [
          {
              "queryParameters": {
                  "usageLocationNumber": null,
                  "waterInvoice": "0",
                  "serviceNumber": "WS-MOCK-WASTE-ID",
                  "wasteInvoice": "0",
                  "created": "2018-10-21 19:01:36",
                  "postalCode": "0",
                  "customerNumber": "0"
              },
              "messages": [
                  "MOCK DATA"
              ],
              "wasteCustomerDetails": {
                  "serviceNumber": "WS-MOCK-WASTE-ID",
                  "postalCode": "0",
                  "invoiceNumber": "0",
                  "address": "Mocktie 1",
                  "collectionPoints": [
                      {
                          "name": "Jätepisteiden tietojen nouto epäonnistui.",
                          "containers": [
                              {
                                  "collectionInterval": "",
                                  "wasteType": null,
                                  "containerSize": null,
                                  "containerCount": null,
                                  "nextCollectionDate": "",
                                  "containerType": null,
                                  "containerOwner": "-"
                              }
                          ]
                      }
                  ]
              },
              "waterCustomerDetails": null
          }
      ],
      "success": true,
      "created": "2018-10-21T19:01:37.001+03:00"
  }