Työpaikkailmoitusten hakurajapinnan tekninen dokumentaatio

Dokumentaation tarkoitus

Tämä dokumentaatio tarkentaa Työmarkkinatorin työpaikkailmoitusten hakurajapinnan teknisiä vaatimuksia ja kuvaa varsinaisen rajapinnan käytön. Rajapinnan käyttöönoton prosessi on kuvattu tarkemmin Työmarkkinatorin sivulla. Samasta paikasta löytyvät myös työpaikkailmoitusten hakuun liittyvän P67-rajapinnan OpenApi-kuvaukset.

Rajapinnan käyttötarkoitus

Rajapinnan kautta ulkoisista palveluista voidaan hakea työpaikkailmoituksia Työmarkkinatorilta. Hakuun on mahdollista antaa erilaisia suodattimia rajaamaan haun tulosjoukkoa. Hakutulokset palautetaan työpaikkailmoituksen rakenteen mukaisesti hakevalle järjestelmälle.

Käyttöönotto

Rajapinta työpaikkailmoitusten hakuun Työmarkkinatorilta 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 sivulla.

Työpaikkailmoitusten haku

Tarkempi työpaikkailmoitusten hakuun liittyvä prosessi on kuvattu alla olevassa kaaviossa.

Varsinainen työpaikkailmoitusten haku tapahtuu Kipa-integraatioalustan palvelun P67 kautta Työmarkkinatorin taustapalveluun. Tarjolla olevat toiminnot, tietosisällöt ja vastaukset on kuvattu hakurajapinnan YAML-kuvauksessa.

Haku tapahtuu HTTP:n POST-metodilla, jotta uudistuneet suodattimet saadaan helpommin mukaan kutsuun ja niiden käsittely on suoraviivaisempaa rajapinnan molemmissa päissä.

Kutsut Kipa integraatioalustan kautta autorisoidaan API key mekanismilla ja kutsun header-tietoihin on lisättävä Kipan käyttöä varten toimitettu KIPA-Subscription-Key.

Endpoint

Kipa-integraatioalustan palvelu P67 löytyy seuraavista osoitteista

• Testiympäristö: https://api-qa.ahtp.fi/kipa/p67/v2/jobpostings
• Tuotantoympäristö: https://api.ahtp.fi/kipa/p67/v2/jobpostings

Työpaikkailmoituksen rakenne

Työpaikkailmoituksen tietomalli koostuu alla olevan kuvan mukaisista kokonaisuuksista.

Hakutulokset

Suodattimien mukaiset hakutulokset palautetaan ulkoiselle palvelulle Newline-delimited JSON (NDjson) streamina.

Koodistot

Työpaikkailmoitukseen 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.

• Ammatti (ESCO_AMMATTI)
• Ammattiryhmä (ISCO_AMMATTILUOKITUS)
• Ajokortti (AJOKORTTILUOKKA)
• Ammattiluvat ja kortit (TYÖNHAKUPROFIILI_LUPA_KORTTI)
• Kieli (KIELI)
• Kunta (KUNTA)
• Maa (MAA)
• Maakunta (MAAKUNTA)
• Määräaikaisuuden kesto (MÄÄRÄAIKAISUUDEN_KESTO)
• Osaaminen (ESCO_OSAAMINEN)
• Palkan peruste (PALKAN_PERUSTE)
• Palkkahaitari (PALKKAHAITARI)
• Palvelussuhde (PALVELUSSUHDE)
• Rikosrekisteriotteet (TYOPAIKKAILMOITUS_RIKOSREKISTERIOTE)
• Toimiala (TOIMIALA)
• Työaika (TYÖAiKA)
• Työn jatkuvuus (TYÖN_JATKUVUUS)
• Työpaikkailmoituksen ilmoittajan tyyppi (TYOPAIKKAILMOITUS_ILMOITTAJAN_TYYPPI)
• Työskentelyaika (TYÖSKENTELYAIKA)

Versio