Tekninen dokumentaatio
Verkkotoimija
Verkkotoimijan nimenkirjoitusoikeudellinen voi antaa Suomi.fi valtuudet -palvelussa alla olevia valtuuksia verkkotoimijan henkilöstölle tai muun/muiden organisaatioiden henkilöstölle. Valtuuksia voi alkaa antamaan 5.4.2022 lähtien.
Sijaintitietopalvelu tarjoaa rajapinnat seuraaviin käyttötarkoituksiin:
- Verkkotoimija: Verkkotietojen toimittaminen ja päivittäminen
- Näyttötarpeen jatkoselvitys: Saatavilla olevat näyttötarpeen jatkoselvityspyynnöt verkkotoimijalle tai hänen valtuuttamalleen palveluntarjoajalle
- Näyttöpalvelu: Kaapelin tai muun verkon osan sijainnin näyttäminen maastossa maanrakennustyöhön ryhtyvälle tai sen merkitseminen maahan.
Yleistä rajapintojen käytöstä:
- Sijaintitietopalvelu on kehitysvaiheessa. Dokumentaatio ja rajapintakuvaukset esittävät Sijaintitietopalvelun toiminnallisuuksien nykyistä tilannetta ja osa rajapinnoista on edelleen keskeneräisiä
- Rajapinnat ovat normaalitilanteessa käytössä 24/7
- Rajapinnat ovat maksuttomia
- Rajapintojen hyödyntäminen vaatii toimijaorganisaation rekisteröitymisen Sijaintitietopalveluun ennen käytön aloittamista
- Rajapintojen tunnistautumiseen käytetään rajapinta- ja toimijakohtaisia API Key -avaimia, jotka toimija saa käyttöönsä organisaation rekisteröitymisen jälkeen
- Rajapintojen kutsuminen vaatii toimijaorganisaation järjestelmän IP-osoitteen lisäämistä organisaation omiin tietoihin Sijaintitietopalvelussa yhteyden mahdollistamiseksi
Verkkotietojen toimitus -rajapinta
Verkkotietojen toimitus -rajapinnan kautta verkkotoimijat voivat lähettää verkkotietonsa Sijaintitietopalveluun.
Lähetysprosessi aloitetaan tekemällä lähetyspyyntö, joka sisältää lähetettävien verkkotietojen perustiedot.
Verkkotoimijan järjestelmä tunnistautuu Sijaintitietopalveluun sille määritetyn API Keyn avulla. API Key on generoitavissa ja noudettavissa Sijaintitietopalvelusta. Luotu API -Key on käytettävissä vain Verkkotietojen toimitus -rajapinnassa.
Hyväksytyn pyynnön vastauksena saadaan vastaanotto-osoite verkkotietojen toimittamista varten sekä toimituskohtaiset tunnukset.
Verkkotiedot toimitetaan SFTP-protokollan ylitse tarjottuun vastaanotto-osoitteeseen hyödyntäen toimituskohtaisia tunnuksia.
Verkkotietojen toimitus -rajapinta tarjoaa toiminnollisuudet aineiston hyväksymiselle sekä toimitukseen liittyvien raporttien hakemiselle: verkkotietojen toimitusraportti ja aktivointiraportti.
Verkkotiedot toimitetaan JSON- muodossa.
Verkkotietojen rakennetta kuvaavat Excel-tiedosto ja JSON-esimerkkitiedostot ovat ladattavissa tältä sivulta:
- STP rajapintakuvaus v1_3 (päivitetty 12.3.2024)
Rajapintaversioon v1_3 tehdyt muutokset - STP_verkkotiedot_JSON-esimerkit
Verkkotietojen toimitus -rajapinnan tekninen kuvaus (Ulkoinen linkki)
Näyttötarpeen jatkoselvityspyyntö -rajapinta
Rajapinnan kautta välitetään Sijaintitietopalvelussa saatavilla olevat näyttötarpeen jatkoselvityspyynnöt verkkotoimijalle tai hänen valtuuttamalleen palveluntarjoajalle.
Pyyntöön vastataan asynkronisesti: "Näyttö tarvitaan", "Näyttöä ei tarvita - suoritetaan karttakaivuu" tai "Näyttöä ei tarvita - suoritetaan karttakaivuu erilliskartalla".
Jatkoselvityspyyntöön tulee vastata Sijaintitietopalvelulle yhden kokonaisen työpäivän aikana (aikaväli klo 8-16). Jos verkkotoimija tai sen palveluntarjoaja ei vastaa jatkoselvityspyyntöön edellä mainitun aikamääreen aikana, Sijaintitietopalvelu toteaa, että näyttö tarvitaan.
Verkkotoimijan tai hänen valtuuttamansa palveluntarjoajan järjestelmä tunnistautuu Sijaintitietopalveluun sille määritetyn API Keyn avulla. API Key on generoitavissa ja noudettavissa Sijaintitietopalvelusta. Luotu API Key on käytettävissä vain Näyttötarpeen jatkoselvityspyyntö
-rajapinnassa.
Näyttötarpeen jatkoselvityspyyntö -rajapinnan tekninen kuvaus (Ulkoinen linkki)