Denna dokumentation preciserar de tekniska kraven för Jobbmarknadens gränssnitt för hantering av platsannonser och
beskriver mer detaljerat hur själva gränssnittet används. Processen för att ta gränssnittet i bruk beskrivs mer ingående
på Jobbmarknadens webbplats. På samma plats
finns även OpenAPI-beskrivningar för P66-gränssnittet som är kopplat till hantering av platsannonser.
Platsannonser fron externa tjänster kan publiceras på Jobbmarknaden genom gränssnittet. Platsannonser kan också schemaläggas för publicering. Publicerade platsannonser kan redigeras och arkiveras via gränssnittet.
Gränssnittet för hantering av platsannonser är utformat så att användaren av gränssnittet inte behöver vara den faktiska
arbetsgivaren för jobbet, utan kan använda det för att hantera platsbannonser från flera olika företag. Platsannonsen
skapas för det företag som anges i parametern businessId i URL:en.
Gränssnittet för hantering av platsannonser på Jobbmarknaden tillhandahålls via KEHA-centrets integrationsplattform (Kipa). Användaruppgifter för plattformen samt relaterade IP-öppningar hanteras av KEHA-centret som en del av införandeprocessen. De uppgifter som behövs för att använda gränssnittet levereras säkert till användaren. Mer detaljerad information om införandet finns på Jobbmaknaden webbplats.
Detaljerade processer för hantering av platsannonser illustreras i diagrammet nedan.
Den faktiska hanteringen av platsannonser sker via tjänsten P66 på Kipa-integrationsplattformen, som kommunicerar med
Jobbmarknadens backend-tjänst. Tillgängliga funktioner, datainnehåll och svar beskrivs i
YAML-beskrivningen för hanteringsgränssnittet.
Anrop via Kipa-integrationsplattformen auktoriseras med en API-nyckelmekanism, och anropets header-information måste
innehålla KIPA-Subscription-Key som tillhandahålls för Kipa-användning. Header attributet KIPA-MessageId ställs in
automatiskt av integrationsplattformen.
Tjänsten P66 på Kipa-integrationsplattformen finns på följande adresser:
https://api-qa.ahtp.fi/kipa/p66/v1/jobpostinghttps://api.ahtp.fi/kipa/p66/v1/jobpostingPlatsannonsen hanteras via API-anropet /v1/jobposting/{businessId}/{externalId}. Den
HTTP-metod som används anger vilken åtgärd som ska utföras på platsannonsen. Alternativen är att hämta information om platsannonsen (GET), skapa eller uppdatera den (PUT) eller arkivera den (DELETE).
Platsannonsens unika externalId-identifierare i uuid-format måste anges i gränssnittsanropet när en platsannons
skapas på Jobbmarknaden.
Om man vill uppdatera en befintlig platsannons måste man lägga till If-Match-informationen i anropets header-information,
där man anger värdet i etag-fältet som finns i den platsannons som ska uppdateras. Detta säkerställer att den senaste versionen av platsannonsen behandlas. Om etag-värdet inte stämmer överens med värdet i databasen, har platsannonsen redigerats efter att informationen hämtades och uppdateringen misslyckas. För att säkerställa att uppdateringen lyckas
rekommenderas det att hämta informationen om platsannonsen med GET-metoden innan man försöker uppdatera.
Platsannonser kan importeras till Jobbmarknaden antingen direkt i publicerad status eller i väntande status för publicering
vid en viss tidpunkt. Publicerade eller väntande platsannonser kan uppdateras. Platsannonser tas automatiskt bort från
publicering vid slutet av ansökningsperioden eller kan tas bort med hjälp av metoden DELETE. I båda fallen flyttas
platsannonsen till arkiverad status och är inte längre offentlig. Om en platsannons innehåller olämpligt innehåll och
myndigheterna förhindrar dess publicering ändras platsannonsens status till blockerad, varefter den inte längre kan
behandlas via administrationsgränssnittet.
Platsannonser kan skickas in på tre språk, och de språk som används ska rapporteras med hjälp av attributet languages.
De lokaliserade fritextfälten valideras för att säkerställa att de innehåller
översättningselement på alla språk som anges i platsannonsen. Om så inte är fallet kommer platsannonsen att avvisas.
Platsannonser använder den europeiska ESCO-klassificeringen för att beskriva yrken och kompetenser. En nationell utvidgning (FINESCO) har gjorts av klassificeringen, som inkluderar den senaste ESCO-klassificeringen och nationella yrken som lagts till. Användningen av FINESCO säkerställer att platsannonser också kan överföras till portalen för europeiska arbetsförmedlingstjänster (EURES). FINESCO-klassificeringen finns tillgänglig på webbplatsen för Jobbmarknaden.
När det gäller yrkesuppgifter bör det noteras att uppgifter om lediga tjänster sammanställs i arbetsförmedlingens statistik.
Dock kan endast ett yrke anges där, även om den platsannons tillåter flera yrken. Av denna anledning hämtas det yrke som
används för statistiska ändamål i platsannons som importeras via gränssnittet från det första alternativet i yrke listan,
om det inte finns något värde i fältet mainOccupation.
I platsannonsen är de kompetenser som krävs för jobbet valfri information. Det rekommenderas att fylla i de kompetenser som krävs, eftersom de används för att matcha platsannonser och jobbsökningprofiler.
Platsen i platsannonsen måste anges som minst en kommun, men det är också möjligt att ange andra platser. Information om kommunen krävs för att platsannonsen ska kunna klassificeras till rätt arbetsförmedling.
Datamodellen för platsannonser består av de element som visas i figuren nedan. Obligatorisk information anges med fet stil.
För saknad information måste strukturen antingen vara null eller så måste nyckeln utelämnas helt.
Nedan följer ett exempel på strukturen för en platsannons när du skapar en ny platsannons i tjänsten.
{
"languages": [
"fi",
"en"
],
"descriptionsContentType": "markdown",
"application": {
"expires": "2026-05-27T16:15:00.00Z",
"extraVisibility": [
"EURES_FLAGGED"
],
"helpText": {
"fi": "Cras tempor bibendum bibendum. Etiam auctor viverra augue at
posuere. Nunc fermentum aliquam est, vel eleifend ligula efficitur
nec. Ut nec ullamcorper lacus, nec aliquam justo. Quisque ultrices
enim diam, ac maximus lectus sodales in. Quisque quis maximus velit.
Phasellus a rutrum lorem. Ut mollis augue quis justo tempus
bibendum. Curabitur pretium ex neque, a pulvinar nulla scelerisque
quis.
\n\nAliquam elementum orci et vulputate consequat. Morbi sit amet
tortor sed ante volutpat congue. In egestas laoreet tempor. Aliquam
sed purus at tellus laoreet varius. Mauris eleifend nunc ante, a
tempor sem malesuada at. Nunc in nisl ligula. Donec porttitor
porttitor vulputate.",
"en": "Cras tempor bibendum bibendum. Etiam auctor viverra augue at
posuere. Nunc fermentum aliquam est, vel eleifend ligula efficitur
nec. Ut nec ullamcorper lacus, nec aliquam justo. Quisque ultrices
enim diam, ac maximus lectus sodales in. Quisque quis maximus velit.
Phasellus a rutrum lorem. Ut mollis augue quis justo tempus
bibendum. Curabitur pretium ex neque, a pulvinar nulla scelerisque
quis.
\n\nAliquam elementum orci et vulputate consequat. Morbi sit amet
tortor sed ante volutpat congue. In egestas laoreet tempor. Aliquam
sed purus at tellus laoreet varius. Mauris eleifend nunc ante, a
tempor sem malesuada at. Nunc in nisl ligula. Donec porttitor
porttitor vulputate."
},
"openPositions": 2,
"published": "2026-05-03T18:00:00Z",
"url": {
"fi": "https://example.com/lorem",
"en": "https://example.com/ipsum"
}
},
"client": {
"businessId": "2296962-1",
"company": "KEHA-keskus",
"companyVisible": true,
"industryCode": null,
"officeCode": null,
"officeName": null
},
"externalLinks": [
{
"description": "External link",
"url": "http://www.google.com/"
}
],
"location": {
"countries": [
"FI"
],
"municipalities": [
"090",
"097"
],
"regions": [
"01",
"14"
],
"requiresTravelling": true,
"workplaceAddress": "Valamontie 42",
"workplaceName": {
"fi": "Valamon luostari",
"en": "Valamon luostari"
},
"workplacePostOffice": "Uusi-Valamo",
"workplacePostalCode": "79850"
},
"owner": {
"company": {
"fi": "Eezy Henkilöstöpalvelut Oy",
"en": "Eezy Henkilöstöpalvelut Oy"
},
"industryCode": "78200",
"officeCode": null,
"officeName": null,
"reference": "reference 12345"
},
"position": {
"continuityOfWork": [
"01"
],
"criminalRecordVerification": [
"1"
],
"drivingLicenses": [
"B"
],
"durationOfTemporary": "06",
"employmentRelationship": "0101",
"jobDescription": {
"fi": "**Donec a dolor at nunc gravida gravida.** Nulla lacinia
malesuada neque, eu tincidunt lacus lacinia a. Nulla cursus leo
nulla, eu consequat lectus feugiat sit amet. Cras dapibus augue
eu hendrerit placerat. Morbi sit amet bibendum ligula, sed
vehicula erat. Sed nisl nisl, ornare ut ultricies in, ornare ut
enim.
\n\n- praesent\n \n- dignissim\n \n- sagittis\n \n- lobortis\n
\n\nNullam ornare orci at feugiat dictum. Nullam porttitor nibh
non aliquam pretium. Duis sed purus neque. Ut nec tortor
placerat, vehicula mi at, tempor ligula. Nam quis nisi ex. Nam
dignissim risus quis viverra tempus. Nulla facilisi. Aliquam
efficitur auctor augue, ac gravida leo volutpat vitae. Aenean
vitae tortor ut urna scelerisque aliquam. Sed elit velit, mollis
id ante sit amet, eleifend suscipit nulla.",
"en": "**Donec a dolor at nunc gravida gravida.** Nulla lacinia
malesuada neque, eu tincidunt lacus lacinia a. Nulla cursus leo
nulla, eu consequat lectus feugiat sit amet. Cras dapibus augue
eu hendrerit placerat. Morbi sit amet bibendum ligula, sed
vehicula erat. Sed nisl nisl, ornare ut ultricies in, ornare ut
enim.
\n\n- praesent\n \n- dignissim\n \n- sagittis\n \n- lobortis\n
\n\nNullam ornare orci at feugiat dictum. Nullam porttitor nibh
non aliquam pretium. Duis sed purus neque. Ut nec tortor
placerat, vehicula mi at, tempor ligula. Nam quis nisi ex. Nam
dignissim risus quis viverra tempus. Nulla facilisi. Aliquam
efficitur auctor augue, ac gravida leo volutpat vitae. Aenean
vitae tortor ut urna scelerisque aliquam. Sed elit velit, mollis
id ante sit amet, eleifend suscipit nulla."
},
"mainOccupation": "http://data.europa.eu/esco/occupation/9bf4c8ea-e814-4772-ae31-0f29672dc497",
"marketingDescription": {},
"occupations": [
{
"uri": "http://data.europa.eu/esco/occupation/1de91afd-9da2-47ab-a7e7-19bf931709a4"
},
{
"uri": "http://data.europa.eu/esco/occupation/7ed2e153-8da8-4c0d-b4c5-3402c623f34b"
}
],
"partTimeInfo": {
"fi": "10-15 Orci varius natoque penatibus.",
"en": "10-15 Orci varius natoque penatibus."
},
"permitCards": [
"002"
],
"permitCardsDescription": {
"fi": "Curabitur non tristique nunc. Nam at rutrum tellus.
Vestibulum interdum ut leo at gravida. Aliquam non nunc lectus.
Nam et bibendum lorem, id euismod nisl.",
"en": "Curabitur non tristique nunc. Nam at rutrum tellus.
Vestibulum interdum ut leo at gravida. Aliquam non nunc lectus.
Nam et bibendum lorem, id euismod nisl."
},
"skills": [
{
"uri": "http://data.europa.eu/esco/skill/00506f28-e884-4496-800c-3477c67eb355"
},
{
"uri": "http://data.europa.eu/esco/skill/2e2bde69-09df-45f7-88f4-a938717bee04"
}
],
"title": {
"fi": "Pellentesque vitae eros aliquet",
"en": "Pellentesque vitae eros aliquet."
},
"wagePrinciple": "0101",
"wagePrincipleInfo": {
"fi": "Nunc a dui sed.",
"en": "Nunc a dui sed."
},
"wageRange": "12",
"workLanguages": [
"fi",
"en"
],
"workTime": "01",
"workTimeDetails": [
"01",
"02"
]
},
"recruiter": {
"contactInfoVisible": true,
"contacts": [
{
"email": "lorem@ipsum.com",
"firstName": "Lorem",
"lastName": "Ipsum",
"telephone": "+358401234567"
}
]
}
}
Olika koduppsättningsvärden relaterade till jobbsökningsprofilen finns tillgängliga från JobbMarknadens-koduppsättningstjänsten. Koduppsättningarna för olika data beskrivs nedan. OpenApi-beskrivningen innehåller också information om koduppsättningen relaterad till attributet.
Koduppsättningens json-struktur läses på ett sådant sätt att kodvärdena kan hittas i id-elementet och beskrivningen
relaterad till id:t lokaliserad i description-elementet. Varje kodvärde har också en giltighetsperiod. Koduppsättningen
kan därför innehålla kodvärden som redan har tagits ur bruk. I sådana fall har koderna information om utgångsdatum.
Vissa koduppsättningar kan ha tillägg som kan användas för att förfina användningen av koduppsättningen. Till exempel
används tillägget subset för att begränsa endast vissa kod-ID:n till ett specifikt syfte. Tillägget sekvensnummer
anger önskad ordning för koderna, till exempel i urvalslistor.