Rajapinta tarjoaa ohjelmalisen väylän vesimittarin lukeman ilmoittamiseksi. Vesimittari ja sopimus tunnistetaan yhdistelmällä sopimusnumero - 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.
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 |
|
| Metodi | GET |
3.1.4 - Esimerkkisanoma tilakyselyn testaamiseksi.
Palvelu palauttaa rajapinnan version.
3.2.1 - Rajapinnan kutsuminen
| Kutsun lähettäminen | |
|---|---|
| Osoite |
|
| Metodi | GET |
3.2.4 - Esimerkkisanoma versiokyselyn testaamiseksi.
Palvelulla ilmoitetaan sopimuksen 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 sopimuksella on useampi mittari, tulee kaikki mittarit lukea samana päivänä ja ilmoittaa mittareille lukema samassa sanomassa.
Kuukauden ensimmäisten kuuden päivän aikana ilmoitetut lukemat huomioidaan edellisen kuukauden laskutuksessa. Lukeman ei kuitenkaan tarvitse ole tasan kuun viimeiseltä tai ensimmäiseltä päivältä. Esimerkiksi 25.11. luettu ja ajoissa ilmoitettu lukema aiheuttaa sen, ettei marraskuun arviolaskutuksessa laskuteta erikseen 26.11.-30.11. ajanjaksoa.
Kuukauden kuluessa ilmoitetusta lukemasta seuraa aina tasauslasku, joka lähtee ilmoittamista seuraavana arkipäivänä. Kuukauden 6. arkipäivä on hyvä takaraja ilmoittaa kuunvaihteen lukema, jos haluaa välttyä arviolaskuilta.
Sopimuksen vesimittareiden numerot voi tarkistaa asiakas- ja sopimusnumerolla mittarilukemanilmoituksen www-lomakkeen avulla (TESTIYMPÄRISTÖ). Viimeisimmät tiedot löytyvät vain tuotantoympäristöstä. Päästäksesi tuotantoympäristöön, poista osoitteesta portti 8443.
3.3.1 - Rajapinnan kutsuminen
| Kutsun lähettäminen | |
|---|---|
| Osoite |
|
| Metodi | POST |
| Headers | Content-type: application/json;charset=UTF-8 |
| Api-avain |
|
| Rajoitukset |
|
| Validointi |
|
3.3.2 - Pakolliset tiedot
Ajantasaiset tunnistetiedot saa mm. sopimuksen laskulta. Vuosien saatossa tunnisteissa on tapahtunut konversioita järjestelmäpäivitysten myötä
ja näitä ei ole välttämättä päivitetty asikkaiden toimialajärjestelmiin. Jos lukemailmoitus ei mene läpi, tunnistetiedot kannattaa
tarkistaa viimeisimmältä laskulta tai vesimittarin luentapyynnöltä.
Sopimuksen vesimittarit voi hakea mittarinlukemailmoituksen www-lomakeen avulla. Linkki palveluun löytyy tämän osion
johdantokappaleesta.
Testiympäristössä tulee huomioida se, että ympäristön tiedot saattavat olla osin vanhentuneita. Viimeiset kohdistustestit on sujuvinta ajaa
tuotantoa vasten dry-run-lipulla.
| 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ä aikavä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ä sopimuksen ja mittareiden tunnuksista. | |
| customerNumber | Asiakasnumero | Merkkijono, numeroita 10-100 merkkiä | 123456 | Asiakkaan vesitoimialajärjestelmän asiakasnumero. Numero löytyy esimerkiksi vesilaskulta. | |
| contractNumber | Vesisopimuksen numero | Merkkijono, 1-10 numeroa | 123456 | Asiakkaan vesisopimuksen numero. Numero löytyy esimerkiksi vesilaskulta. | |
| usageLocationNumber | Vesisopimuksen numero | Merkkijono, 1-10 numeroa | 123456 | Asiakkaan käyttöpaikan numero. Poistumassa käytöstä! 2020 alkaen tulisi käyttää asiakasnumero+sopimusnumero-yhdistelmää. Käyttöpaikkanumeron kanssa tulee käyttää vanhaa ennen 2020 voimassa ollutta asiakasnumeroa. | |
| 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 | Sopimuksen vesimittarit | Lista | Kaikille sopimuksen vesimittareille tulee ilmoittaa uusi lukema samalle päivällä ja samassa sanomassa. Voit käyttää mittarilukeman ilmoituksen www-lomaketta sopimuksen 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ä ajan tasalla. | |
| 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 |
|---|---|---|---|---|
| tooLargeReadingWarningDisabled | Ohita varoitus | Totuusarvo | true | Jos edellisestä lukemasta laskettu kulutus ylittää 9999m3, annetaan tästä tallennuksen estävä varoitus. Jos kohteelta on jäänyt ilmoitus tekemättä pitemmän aikaa, poikkeuksellisen ison lukeman voi käydä ilmoittamassa käsin www-lomakkeen kautta. Joillekin kohteille raja on automaattisesti liian tiukka ja varoituksen voi ohittaa asettamalla tooLargeReadingWarningDisabled-lipun arvoksi true. |
| 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.
{
"id" : "1234567890112345678901123456789011234567891",
"apiKey" : "HSYTEST01_12gWSDuocGj4tP8qGHJKu31mbEjwIusfdnHzehq7",
"customerNumber" : "888888888",
"readingDate" : "11.10.2016",
"contractNumber" : "777777777",
"readingList" : [
{
"reading": "100",
"meterNumber": "MOCK000001"
}],
"submitterInformation" : "Interface Postman-demo"
}
{
"success": true,
"message": null,
"errorList": null
}
{
"error": "Annetuilla tunnuksilla ei löytynyt sopimusta",
"success": false
}
{
"success": false,
"message": "Luentapäivä ei voi yli 3kk menneisyydessä",
"errorList": [
{
"field": "readingDate",
"rule": "PastMax",
"message": "Luentapäivä ei voi yli 3kk menneisyydessä"
}
]
}