Lisätietoa tuonti-integraation toteuttajalle (rajapintaversio 12)

Tämä sivu on alustava ja täydentyy syksyn 2026 aikana.

Ennen kuin aloitat tuonti-integraation toteuttamisen, tutustu ohjeeseen Tekninen dokumentaatio integraation toteuttajalle (rajapintaversio 12).

Käyttölupahakemus

Tuontirajapinnan käyttö edellyttää erillistä käyttölupaa. Tee käyttölupahakemus ennen tuonti-integraation käyttöönottoa.

Miten otan käyttöön tuontirajapinnan

Ohjeita integraation toteuttamiseen

Kun olet tehnyt käyttölupahakemuksen, voit aloittaa tuonti-integraation toteuttamisen asiakastestiympäristössä. Asiakastestiympäristön tiedot ovat tämän sivun lopussa.

Huolehdi, että integraatio siirtää lähdejärjestelmässä tehdyt muutokset PTV:hen vähintään kerran vuorokaudessa. Poista PTV:stä tiedot, jotka on poistettu lähdejärjestelmästä. Tee poistot vähintään kerran vuorokaudessa. 

Tutustu rajapintojen metodeihin ja tietorakenteisiin Scalar-dokumentaatiossa:

• Asiakastestiympäristön rajapintadokumentaatio ScalarissaAvautuu uuteen ikkunaan.
• Tuotantoympäristön rajapintadokumentaatio Scalarissa Avautuu uuteen ikkunaan.

Tunnistautuminen tuontirajapintaan

Tuontirajapinnan metodien ja käyttöoikeudeltaan rajattujen hakurajapinnan metodien käyttöön tarvitset

• voimassa olevan tokenin
• voimassa olevan API-avaimen. Katso API-avaimen käyttöohje.

Tokenilla tunnistetaan käyttäjän käyttöoikeudet. API-avaimella tunnistetaan integraatio, josta rajapintakutsu tehdään.

Tuonti-integraatiototeutus on aina organisaatiokohtainen. Lähetä organisaatiokohtainen API-käyttäjätunnus ja salasana Suomi.fi-palveluhallinnan käyttövaltuushallinnan palvelimelle. Palvelin palauttaa tunnistautumisessa tarvittavan tokenin.

Tunnistautuminen tuotantoympäristöön tokenin avulla

Tuotantoympäristön token sisältää käyttöoikeustiedot ja tokenin voimassaoloajan. Tarkista voimassaoloaika tokenin tiedoista ja hae uusi token ennen nykyisen tokenin vanhenemista.

Tokenin hakemisen osoite: (täydentyy myöhemmin)

Hae token

Lähetä token-pyyntö seuraavilla tiedoilla.

Header
Content-Type:application/json

Body
username: user
password: pwd
apiUserOrganisation: organisation ID (valinnainen)

Kutsu palauttaa serviceToken -parametrin.

Jos API-käyttäjätunnus on liitetty useaan organisaatioon

• Kohdista token-pyyntö haluamaasi organisaatioon käyttämällä apiUserOrganisation-kenttää.
• Anna kentän arvoksi Suomi.fi-palveluhallinnan palauttama organisaation tunniste (ID).
• Jos et anna apiUserOrganisation-kenttää, token muodostetaan sille organisaatiolle, joka on merkitty aktiiviseksi Suomi.fi-palveluhallinnassa.

Kutsuesimerkki 1, organisaation ID:tä ei anneta

{
  "username":"username@domain.fi",
  "password":"validpassword"
}

Kutsuesimerkki 2, organisaation ID annetaan

{
  "username":"username@domain.fi",
  "password":"validpassword",
  "apiUserOrganisation": "9cb2abc6-5458-4811-bbdd-83f75ceeed25"
}

Esimerkkivastaus

{
  "serviceToken":"eyJhlsdlksd...."
}

Huomio tuotanto- ja asiakastestiympäristöstä

Tuotantoympäristön ja asiakastestiympäristön tokenit eroavat rakenteeltaan toisistaan.
Kun haet tokenia tuotantoympäristöstä, käytä pyynnössä apiUserOrganisation-kenttää, jos haluat kohdistaa tokenin tiettyyn organisaatioon.

Testaa integraatio ennen tuotantoon siirtymistä

Testaa tuonti-integraatio asiakastestiympäristössä ennen kuin otat sen käyttöön tuotantoympäristössä.

Tutustu ensin testausohjeeseen: 

• Tuonti-integraation testaus asiakastestiympäristössä (sisältää testausraporttien pohjat) 

Testaa, että: 

• integraatio toimii teknisesti suunnitellulla tavalla
• siirrettävät tiedot vastaavat PTV:n vaatimuksia 
• rajapintayhteydet ja käyttöoikeudet toimivat oikein. 

Laadi testauksesta vaaditut raportit ja toimita ne DVV:lle testausohjeessa kuvatulla tavalla. 

Korjaukset ja tuotantoasennus

Kun olet suorittanut vaaditut testaukset ja toimittanut testausraportit DVV:lle, etene tuotantoon siirtymisessä testausohjeen mukaisesti.

Siirry tuotantoon

1. Toimita testausraportit DVV:lle.
2. Odota testauksen hyväksyntää.
3. Vastaanota tuotantoympäristön API-käyttäjätunnuksen tiedot.
4. Tee tuotantoasennus.

Kun testaus on hyväksytty, DVV toimittaa PTV:n tuotantoympäristön API-käyttäjätunnuksen ja siihen liittyvän salasanan käyttölupahakemuksessa ilmoitettuun sähköpostiosoitteeseen.

Esimerkkiohjeita yleisimpiin käyttötapauksiin

Header
Content-Type: application/json

Body
username: user
password: pwd

{
  "username":"username@domain.fi",
  "password":"validpassword"
}

{
  "ptvToken":"eyJhlsdlksd...."
}