Helsingin seudun ympäristöpalvelut
Vesimittarin lukeman ilmoitus -rajapinta

Rajapinta tarjoaa ohjelmalisen väylän vesimittarin lukeman ilmoittamiseksi. Vesimittari ja käyttöpaikka tunnistetaan yhdistelmällä käyttöpaikan numero - asiakasnumero - vesimittarin numero. Käytännössä ohjelmallinen ilmoitus vastaa perinteistä postitse lähetettyä vesimittarin lukeman ilmoitusta. Kullekin HSYn vesimittarille tulee ilmoittaa lukema vähintään kerran vuodessa. Rajapinnan kautta mittarille on mahdollista ilmoittaa lukema kerran kuukaudessa, jolloin veden käyttötilastot on saatavissa HSY:n eRaportti-palvelusta tarkemmalla tasolla. Vesilaskutuksessa laskutuksen tasaus tehdään kuitenkin vain kerran vuodessa.

1 - Rajapinnan käyttöehdot

Rajapinnan käyttö on sallittu sekä ei-kaupalliselle että kaupalliselle käytölle, eikä sen käytöstä peritä maksua. Käyttöehto on voimassa toistaiseksi ja HSY varaa oikeuden muuttaa sitä ennalta ilmoittamatta. Testiympäristön käyttö on vapaata ja esimerkkisanomasta löytyy testiympäristön Api-avain. Tuotantokäyttöä varten järjestelmäkohtainen avain on saatavissa sähköpostitse osoitteesta timo.vakkilainen@hsy.fi.

2 - Julkaisuhistoria

3 - Rajapinnan tarjoamat palvelut

3.1 - Rajapinnan tila

Palvelu palauttaa rajapinnan tilan. 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

Kutsun lähettäminen
Osoite
  • TESTI: https://lukemat.hsy.fi:8443/vesimittari/rest/v1/status/
  • TUOTANTO: https://lukemat.hsy.fi/vesimittari/rest/v1/status/
  • (Suora linkki viimeisimpään versioon ilman versionumeroa: .../rest/status/)
Metodi GET

3.1.4 - Esimerkkisanoma tilakyselyn testaamiseksi.

3.2 - Rajapinnan versio

Palvelu palauttaa rajapinnan version.

3.2.1 - Rajapinnan kutsuminen

Kutsun lähettäminen
Osoite
  • TESTI: https://lukemat.hsy.fi:8443/vesimittari/rest/v1/version/
  • TUOTANTO: https://lukemat.hsy.fi/vesimittari/rest/v1/version/
  • (Suora linkki viimeisimpään versioon ilman versionumeroa: .../rest/version/)
Metodi GET

3.2.4 - Esimerkkisanoma versiokyselyn testaamiseksi.

3.3 - Vesimittarinlukeman ilmoittaminen

Palvelulla ilmoitetaan käyttöpaikan vesimittarin tai vesimittareiden juoksevat lukemat. Vesimittarin laskurin lukemasta huomioidaan kokonaisia kuutiometrejä osoittava lukema. Laskurin etunollia ei lisätä lukeman eteen, eikä osakuutiometrejä näyttävien punaisten osoittimien asennolla ole merkitystä. Palvelu laskee mittausjakson kulutuksen ilmoitetun lukeman sekä viimeksi ilmoitetun lukeman erotuksesta. Jos käyttöpaikassa on useampi mittari, niiden kaikkien lukema tulee ilmoittaa kerralla samassa viestissä.

Käyttöpaikan vesimittareiden numerot voit tarkistaa asiakas- ja käyttöpaikkanumerolla mittarilukemanilmoituksen www-lomakkeen avulla..

3.3.1 - Rajapinnan kutsuminen

Kutsun lähettäminen
Osoite
  • TESTI: https://lukemat.hsy.fi:8443/vesimittari/rest/v1/reading/store/
  • TUOTANTO: https://lukemat.hsy.fi/vesimittari/rest/v1/reading/store/
Metodi POST
Headers Content-type: application/json;charset=UTF-8
Api-avain
  • TESTI: HSYTEST01_12gWSDuocGj4tP8qGHJKu31mbEjwIusfdnHzehq7
  • TUOTANTO: Katso kohta Rajapinnan käyttöehdot
Rajoitukset
  • Vesimittarille tulee ilmoittaa korkeintaan yksi lukema kuukaudessa.
  • Testiympäristössä mittarinlukemat eivät päivity aktiivisesti käyttöpaikan tietoihin, koska ympäristössä ei ajeta aktiivisesti päivityksen tekevää eräajoa. Näin ollen esim. edellisen onnistuneen ilmoituksen päivämäärä ei välttämättä päivity, ja samalla päivämäärällä voi ilmoittaa lukeman monta kertaa.
  • Lukemienilmoitusrajapinnassa on rajoitus maksimiliikenteelle, joka tulee huomioida mm.:
    • Automaattisesti luettujen mittareiden lukemien ilmoittamisessa heti ensimmäisellä sekunnilla kuun vaihteen jälkeen. On parempi viivästää ilmoittaminen tuntien tai päivien päähän kuukauden vaihteesta, jottei liian moni järjestelmä ilmoita lukemia samalla hetkellä.
    • Ilmoitettaessa eräajolla usean käyttöpaikan lukemat kerralla, on perättäiset ilmoitukset hyvä tallentaa sarjassa muutamalla sekunnilla viivästettynä vs. useammalla säikeellä samaan aikaan, koska rajapinnassa saattaa olla muutakin liikennettä samanaikaisesti.
  • Tällä hetkellä kello 01-05 välille asettuu varmistusten aiheuttama kannan huoltokatko, joka ei normaalisti kestä pitkään.
  • Testiympäristössä tulee huomioida, että osalla käyttöpaikoista lukemailmoitukset saattavat epäonnistua testidatassa esiintyvien poikkeamien johdosta. Pääasiassa tämä koskettaa niitä kohteita, joissa mittarinumerot tai sopimustiedot ovat päivittyneet vuoden sisällä. Tuotannon data kopioidaan pari kertaa vuodessa testiympäristöön ja näin tietojen päivittyminen testiin saattaa kestää melko pitkään.
Validointi
  • Rajapinta validoi annettujen parametrien muodon ja tarkistaa mm. annetun vesimittarin löytymisen.
  • Annetun lukeman ja käyttöpaikan tietojen oikeellisuus arvioidaan käyttöpaikan tietoja ja viimeksi ilmoitettua lukemaa vasten. Epäuskottavat lukemat hylätään tai välitetään asiakaspalvelun hyväksyttäväksi.
  • Rajapinta palauttaa ilmoituksen tiedoissa olevista virheistä kenttäkohtaisesti loppukäyttäjälle esitettävissä olevan virheilmoituksen sekä teknisistä virheistä suppeamman teknisen virheen.

3.3.2 - Pakolliset tiedot

*) Huomioi muutokset tunnistetiedoissa: Asiakasnumerot, käyttöpaikkanumerot sekä vesimittarinumerot ovat saattaneet vuosien saatossa muuttua. Viime vuosina mittarinumeroiden eteen on lisätty mm. kuntakohtainen tunnus E, H tai V. Muutoksia ei ole välttämättä päivitetty asiakkaiden järjestelmiin. Niinpä jos lukemailmoitus ei mene läpi, tunnistetiedot kannattaa tarkistaa viimeisimmältä laskulta tai vesimittarin luentapyynnöltä. Käyttöpaikan vesimittarit voi myös hakea mittarinlukemailmoituksen www-lomakeen avulla. Linkki palveluun tämän osion johdantokappaleessa.

Testiympäristössä kannattaa huomioida se, että vuoden sisällä tehdyt mittarinvaihdot eivät ole välttämättä päivittyneet tesiympäristöön. Tuotannon data päivitetään testiympäristöön kerran vuodessa.

Kenttä sanomassa Kentän nimi Muoto Esimerkki Kuvaus
apiKey Api-avain Merkkijono HSYTEST01_1...7 Rajapinnan käyttöön vaadittava järjestelmäkohtainen tunnus. Katso lisätietoja kohdasta Rajapinnan käyttöehdot.
id Tapahtuma-id Merkkijono 10-100 merkkiä 20160401-001 Rajapinnan kutsujan muodostama yksilöllinen tunniste, jolla ilmoitustapahtuma ja sanoma voidaan tunnistaa lähettävässä sekä vastaanottavassa järjestelmässä. Rajapinta estää tunnuksen avulla lyhyellä aikavaälillä tehtävät tuplalähetykset. Käytetyt tunnisteet tallennetaan muistinvaraisesti, eli pitkällä aika välillä ei tule luottaa siihen, että saman tunnuksen uudelleenkäyttö estetään. Tunniste voi olla esimerkiksi kuluvan hetken aikaleima tai yhdistelmä ilmoituspäivämäärästä sekä käyttöpaikan ja mittareiden tunnuksista.
customerNumber Asiakasnumero Merkkijono, numeroita 10-100 merkkiä 123456 Asiakkaan vesitoimialajärjestelmän asiakasnumero. Numero löytyy esimerkiksi vesilaskulta. *) Katso: Huomioi muutokset tunnistetiedoissa.
usageLocationNumber Käyttöpaikan numero Merkkijono, 1-10 numeroa 123456 Asiakkaan vesisopimuksen käyttöpaikan numero. Numero löytyy esimerkiksi vesilaskulta. *) Katso: Huomioi muutokset tunnistetiedoissa.
submitterInformation Ilmoittajan tiedot Merkkijono, 3-50 merkkiä Ilkka Ilmoittaja, 555 5555 55 Ilmoittajan yhteystiedot, kuten ilmoittajan nimi ja puhelinnumero tai ilmoittavan järjestelmän vastuuhenkilön sähköpostiosoite ja/tai puhelinnumero. Tietoja käytetään virhetapausten tai virheellisten kirjausten selvittämiseen.
readingDate Luentapäivä Merkkijono, pp.kk.vvvv 01.01.2016 Mittarien luentapäivä. Päivämäärä tulee olla viimeksi kuluneen kolmen kuukauden sisällä.
readingList Käyttöpaikan vesimittarit Lista Kaikille käyttöpaikan vesimittareille tulee ilmoittaa uusi lukema samalle päivällä ja samassa sanomassa. Voit käyttää mittarilukeman ilmoituksen www-lomaketta käyttöpaikan mittarinumeroiden tarkistamiseksi. Linkki palveluun tämän osion johdantokappaleessa.
  meterNumber Mittarin numero Merkkijono, 1-20 merkkiä, [A-zA-Z0-9]* H123456 Vesimittarin numero. Numero löytyy esimerkiksi vesilaskulta. Vanhempien vesimittareiden stanssatut vesimittarinumerot eivät ole välttämättä ajantasalla. *) Katso: Huomioi muutokset tunnistetiedoissa.
  reading Mittarin lukema Kokonaisluku 99999 Vesimittarin juokseva lukema kokonaisina kuutiometreinä. Lukeman etunollia ei lisätä lukeman eteen. Osakuutiometrejä näyttävien punaisten osoittimien asennolla ei ole merkitystä mittaria luettaessa. Palvelu laskee mittausjakson kulutuksen ilmoitetun lukeman sekä viimeksi ilmoitetun lukeman erotuksesta. Palvelu osaa huomioi myös esimerkiksi mittarin lukeman ympäripyörähtämisen.

3.3.3 - Vapaaehtoiset täydentävät tiedot virhetapausten tai virhekirjausten selvittämistä varten.

Kenttä sanomassa Kentän nimi Muoto Esimerkki Kuvaus
language Virheilmoitusten kieli Merkkijonovakio FINNISH Rajapinnan palauttammisssa virheilmoituksissa käytettävä kieli. Tuetut kielet ovat FINNISH, SWEDISH, ENGLISH. Kieli voidaan jättää antamatta, jolloin oletuksena käytetään suomenkieltä.
customerName Asiakkaan nimi Merkkijono, 3-50 merkkiä Veikko Vesi Asiakkaan nimi virhetapausten tai -kirjausten selvittämistä varten. Voidaan jättää antamatta.
addressStreet Käyttöpaikan osoite Merkkijono, 3-100 merkkiä Esimerkkitie 1 Käyttöpaikan tiedot virhetapausten tai -kirjausten selvittämistä varten. Voidaan jättää antamatta.
addressPostalCode Käyttöpaikan postinumero Merkkijono, 5 numeroa 00100 Käyttöpaikan tiedot virhetapausten tai -kirjausten selvittämistä varten. Voidaan jättää antamatta.
addressPostOffice Käyttöpaikan postitoimipaikka Helsinki Merkkijono, 1-50 merkkiä Käyttöpaikan tiedot virhetapausten tai -kirjausten selvittämistä varten. Voidaan jättää antamatta.

3.3.4 - Lisätoiminnot

Kenttä sanomassa Kentän nimi Muoto Esimerkki Kuvaus
dryRun Kuivaharjoittelu true Totuusarvo Sanoman tallentamista voi kuivaharjoitella testissä sekä tuotannossa lisäämällä sanomaan dryRun-parametrin arvolla true.

Vaihtoehtoisesti kuivaharjoittelun voi suorittaa lisäämällä urlin loppuun "dry-run"
(esim: https://lukemat.hsy.fi:8443/vesimittari/rest/v1/reading/store/dry-run)

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