Työnhakuprofiilien noutorajapinnan tekninen dokumentaatio

Sisällysluettelo

• Sisällysluettelo
• Dokumentaation tarkoitus
• Käyttötarkoitus
• Käyttöönotto
• Tietojen siirron prosessi
• Työnhakuprofiilin tietojen siirron valtuuttaminen
  • Käyttäjän valtuutuksen osoite
  • Query-parametrit
  • Uudelleenohjaus takaisin ulkoiseen järjestelmään
  • Virhetilanteet
• Työnhakuprofiilin siirron valtuuskoodin haku
  • Endpoint
  • Header
  • Request body
  • Vastaus
  • Access-tokenin rakenne
  • Virhetilanteet
• Työnhakuprofiilin tietojen siirto ulkoiseen järjestelmään
  • Endpoint
  • Header
  • Vastaus
  • Paluukoodit
• Koodistot

Dokumentaation tarkoitus

Tämä dokumentaatio tarkentaa Työmarkkinatorin työnhakuprofiilien noutorajapinnan teknisiä vaatimuksia ja kuvaa tarkemmin varsinaisen rajapinnan käytön. Rajapinnan käyttöönoton prosessi on kuvattu tarkemmin[Työmarkkinatorin sivulla] (https://tyomarkkinatori.fi/ohjeet-ja-tuki/yhteistyokumppanit). Samasta paikasta löytyvät myös työnhakuprofiilien noutorajapintaan liittyvien rajapintojen (P60 ja P64) OpenApi-kuvaukset.

Käyttötarkoitus

Rajapinnan avulla käyttäjä voi siirtää tietoja Työmarkkinatorin työnhakuprofiilistaan ulkoisiin palveluihin. Tällaisia palveluita ovat esimerkiksi erilaiset osaamistietopankit ja toimialakohtaiset rekrytointipalvelut.

Työkokemus ja osaamistietojen siirto Työmarkkinatorilta ulkoisiin järjestelmiin vaatii aina käyttäjän valtuutuksen. Tämä valtuutus annetaan Työmarkkinatorilla, jonka jälkeen halutut tiedot siirretään ulkoiseen palveluun. Rajapinta ei ota kantaa siihen miten tiedot lisätään ulkoisen järjestelmän tietoihin.

Käyttöönotto

Rajapinta käyttäjän työnhakuprofiilin tietojen siirtäminen ulkoiseen palveluun tarjotaan KEHA-keskuksen integraatioalustan(Kipa) kautta. Tunnukset integraatioalustan käyttöön sekä siihen liittyvät IP-avaukset tehdän KEHA-keskuksen toimesta osana rajapinnan käyttöönoton prosessia. Rajapinnan käytössä tarvittavat tunnukset toimitetaan rajapinnan käyttäjälle tietoturvallisesti. Tarkempia tietoja käyttöönotosta löytyy[Työmarkkinatorin sivuilta] (https://tyomarkkinatori.fi/ohjeet-ja-tuki/yhteistyokumppanit).

Tietojen siirron prosessi

Tarkempi tietojen siirron prosessi on kuvattu alla olevassa kaaviossa. Eri vaiheisiin liittyvät kutsut ja niiden parametrit on avattu seuraavissa kappaleissa.

Työnhakuprofiilin tietojen siirron valtuuttaminen

Työnhakuprofiilin tietojen siirto ulkoiseen järjestelmään alkaa sillä, että käyttäjä siirtyy ulkoisen järjestelmän toiminnosta noutamaan tietoja Työmarkkinatorilta. Toiminto ohjaa käyttäjän Työmarkkinatorin tietojen siirron valtuutusprosessiin. Käyttäjä tunnistautuu Työmarkkinatorille ja valtuuttaa haluamansa työnhakuprofiilin tiedot siirrettäväksi ulkoiseen järjestelmään. Näille tiedoille muodostetaan kertakäyttöinen ja väliaikainen valtuuskoodi, jota hyödynnetään varsinaisessa tietojen siirrossa.

Osana käyttäjän tekemää luvitusprosessia muodostetaan myös tekninen access-token, jonka avulla järjestelmä pyytää varsinaista luvituskoodia tietojen siirtoa varten.

Käyttäjän valtuutuksen osoite

Alla kuvattu tuotantoympäristön osoitteet, joiden kautta käyttäjän valtuutus tietojen siirtoon tehdään. Testiympäristössä urlin alkuosa on muotoa https://tmt-qa.tyomarkkinatori.fi. Testiympäristön käyttö on rajattu, joten testaus pitää tehdä yhdessä KEHA-keskuksen kanssa. Endpoint ei versioidu.

• Suomeksi
  • https://tyomarkkinatori.fi/henkiloasiakkaat/oma-tyopolku/profiilitietojen-haun-luvitus
• Ruotsiksi
  • https://tyomarkkinatori.fi/sv/personkunder/min-karriarstig/autentisering-for-hamtning-av-profildata
• Englanniksi
  • https://tyomarkkinatori.fi/en/personal-customers/my-job-path/permission-to-retrieve-profile-data

Query-parametrit

Ulkoisen järjestelmän on välitettävä valtuutus-kutsussa seuraavat tiedot. Kutsu lähtee käyttäjän selaimesta ulkoisen järjestelmän sivulta.

Esimerkki

curl -X GET https://tyomarkkinatori.fi/henkiloasiakkaat/oma-tyopolku/profiilitietojen-haun-luvitus?
response_type=code&client_id=f47ac10b-58cc-4372-a567-0e02b2c3d479&
redirect_uri=https%3A%2F%2Fexampledomain.fi%2Fexamplepath&state=abcXYZ123

Uudelleenohjaus takaisin ulkoiseen järjestelmään

Onnistuneen käyttäjän valtuutuksen jälkeen valtuutuskutsu uudelleenohjataan osoitteeseen, jonka ulkoinen järjestelmä välitti valtuus-kutsun redirect_url query-parametrina.

Query-parametrit

Esimerkki

Luvituksen jälkeen palataan annettuun osoitteeseen

https://exampledomain.fi/exmaplepath?state=abcXYZ123

Virhetilanteet

Jos pyynnössä välitetty redirect_uri on kelvollinen, mutta kutsun tiedot muuten puutteelliset, välitetään kutsujalle seuraavat tiedot. Tiedot välitetään query-parametreina applcation/x-www-form-urlencoded formaatissa.

Esimerkki

https://exampledomain.fi/exmaplepath?error=access_denied&state=abcXYZ123

Jos kutsussa ei ole redirect_uri-parametria tai välitetty uri ei ole validi tai jos kutsussa ei ole client_id-parametria tai välitetty client-id ei ole validi, kutsua EI uudelleenohjata redirect_uri osoitteeseen, vaan Työmarkkinatorille kirjautuneelle käyttäjälle esitetään virheilmoitus.

Työnhakuprofiilin siirron valtuuskoodin haku

Tässä kohdassa prosessia ulkoinen järjestelmä hakee käyttäjälle luodun kertakäyttöisen valtuuskoodin Kipa-integraatioalustan palvelun P64 kautta Työmarkkinatorin taustapalvelusta. Tällä varmistetaan se, että siirtoa yrittää sama järjestelmä, jonka kautta käyttäjä on valtuuden antanut. Kutsussa tarvittava KIPA-Subscription-Keyon sama kaikille palveluille.

Rajapinta on versioituva ja versionumero on osa rajapinnan URIa. Käyttävän järjestelmän tunnistautumisessa käytetään HTTP Basic Authenticationia (RFC2617). Ulkoisen järjestelmän on valitettävä valtuuskoodin haun kutsussa alla kuvatut tiedot:

Endpoint

• Metodi: POST
• Testiympäristö: https://api-qa.ahtp.fi/kipa/p64/v1/request-token
• Tuotantoympäristö: https://api.ahtp.fi/kipa/p64/v1/request-token

Header

Request body

Esimerkki

curl -X POST https://api.ahtp.fi/kipa/p64/v1/request-token \
     -H "Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW" \
     -H "KIPA-Subscription-Key: <KIPA API key>" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "grant_type=authorization_code" \
     -d "code=1SnMFAfrkhrM0V_U9PlZf6ZfgxdjSgjEOz5Y4uxkuXxN3ZSeT84" \
     -d "redirect_uri=https%3A%2F%2Fexampledomain.fi%2Fexamplepath"

Vastaus

Onnistuneessa kutsussa (http-status 200) tiedot välitetään vastauksen bodyssä (content-type: application/json)

Access-tokenin rakenne

JWS Protected Header

JWS Payload

Esimerkki

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
 
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.
     eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkFsaWNlIERvZSIsImlhdCI6MTY5MzAwMDAwMH0.
     SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
  "token_type": "bearer",
  "expires_in": 600
}

Virhetilanteet

Epäonnistuneessa kutsussa (http-status 400) tiedot välitetään responsen bodyssä (content-type: application/json)

Esimerkki

HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
 
{
  "error": "invalid_request"
}

Työnhakuprofiilin tietojen siirto ulkoiseen järjestelmään

Varsinainen tietojen siirto tapahtuu valtuuskoodin haun jälkeen Kipa-integraatioalustan palvelun P60 kautta Työmarkkinatorin taustapalvelusta. Työmarkkinatorin työnhakuprofiilista siirrettävät datat ovat vastauksen payloadissa rajapinnan YAML-kuvauksen mukaisessa json-formaatissa.

Endpoint

• Metodi: GET
• Testiympäristö: https://api-qa.ahtp.fi/kipa/p60/v1/profile
• Tuotantoympäristö: https://api.ahtp.fi/kipa/p60/v1/profile

Header

Vastaus

Onnistuneessa kutsussa (http-status 200) tiedot välitetään vastauksen bodyssä (content-type: application/json)

Esimerkki onnistuneesta siirrosta

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
 
{
  "profile": {
    "educations": ["...", "...", "..."],
    "projects": ["..."],
    "certifications": ["...", "..."]
  }
}

Paluukoodit

Esimerkki virhetilanteesta

HTTP/1.1 401 Unauthorized
Content-Type: application/json;charset=UTF-8

Koodistot

Työnhakuprofiiliin liittyvät erilaiset koodistoarvot ovat saatavilla Työmarkkinatorin koodistopalvelusta. Alla on kuvattu eri tietojen koodistot. Myös OpenApi-kuvauksessa on tieto attribuuttiin liittyvästä koodistosta.

Koodiston json-rakennetta luetaan siten, että koodiarvot löytyvät tunnus-elementistä ja tunnukseen liittyvä kuvaus lokalisoituna selite-elementistä. Jokaiseen koodiarvoon liittyy myös voimassaoloaika. Koodistossa saattaa olla siis koodiarvoja, jotka on jo poistettu käytöstä. Tälloin koodeilla on loppupaiva-tieto. Joillain koodistoilla voi olla laajennuksia, joilla koodiston hyödyntämistä voidaan tarkentaa. Esimerkiksi osajoukko-laajennuksella halutaan rajata vain tietyt kooditunnukset tiettyyn tarkoitukseen. Järjestysnumero-laajennus kertoo koodien halutun järjestyksen esimerkiksi valintalistoissa. Lisäksi joitain koodiarvoja hyödynnetään myös muissa järjestelmissä ja erityisesti asiakkaalle Työmarkkinatorilla näytettävät tekstit on tarkennettu AsiakkaalleNaytettavaSelite-laajennuksella.

• Ajokortti (AJOKORTTILUOKKA)
• Ammatti (ESCO_AMMATTI)
• Ammattiluvat ja kortit (TYÖNHAKUPROFIILI_LUPA_KORTTI)
• Kieli (KIELI)
• Kielitaidon taso (TYÖNHAKUPROFIILI_KIELITAIDON_TASO)
• Koulutuksen tila (TYÖNHAKUPROFIILI_KOULUTUS_TILA)
• Koulutus (TYÖNHAKUPROFIILI_KOULUTUS)
• Kunta (KUNTA)
• Maa (MAA)
• Maakunta (MAAKUNTA)
• Osaaminen (ESCO_OSAAMINEN)
• Työn aloitus (TYÖN_ALOITUS)
• Yritystoiminnan tyyppi (TYÖNHAKUPROFIILI_TYÖN_TYYPPI, osajoukko YRITYSTOIMINTA)