Mer information för den som genomför OUT-integrationen

1. Hämta organisationer

En lista över alla organisationer i Suomi.fi-servicedatalagret som har publicerade tjänster och servicekanaler kan hämtas med metoden GET Organization Metoden returnerar organisationernas namn och id.

2. Hämta organisationernas tjänster

När du känner till organisationens id kan du söka en lista över organisationens tjänster med metoden GET Organization/{id}. Metoden returnerar organisationens tjänster och id:n.

3. Hämta uppgifter om tjänsterna

Näst kan du hämta uppgifter om organisationens tjänster med tjänstens id som returnerats i organisationens uppgifter.

När tjänsterna inte har en basbeskrivning

kan du hämta

• alla uppgifter om en enskild tjänst med metoden GET Service/{id}
• eller alla uppgifter om flera tjänster med GET Service/list-metoden.

När tjänsterna har en basbeskrivning

En del av tjänsterna har en basbeskrivning i bakgrunden. De har gjorts för användning av kommunerna, välfärdsområdena, företagens regiontjänster och församlingarna.

Det är inte obligatoriskt att söka information på basbeskrivningarna, men de innehåller användbar bakgrundsinformation om tjänsterna.

Du kan hämta

• uppgifter om en enskild tjänst med basbeskrivningar med metoden serviceWithGD/{id} eller
• alla uppgifter inklusive basbeskrivningar för flera tjänster med metoden GET Service/serviceWithGD/list.

4. Hämta uppgifter om servicekanaler som kopplats till tjänsterna

Namn- och ID-uppgifterna för de servicekanaler som anslutits till tjänsten returneras i tjänstens uppgifter.

Du kan hämta

• alla uppgifter om en enskild servicekanal med metoden GET ServiceChannel {id} eller
• uppgifter om flera servicekanaler med metoden GET ServiceChannel/list

Observera! Namnet på en e-tjänstkanal och en webbsideservicekanal ska anges så att det kan användas som länktext som leder till servicekanalens URL-adress. När du använder servicekanalens URL-adress, använd kanalens namn som länktext. Visa inte enbart URL-adressen, eftersom den inte är beskrivande eller tillgänglig.

Det finns flera metoder som kan användas för att begränsa den information som du söker. Nedan följer exempel på de viktigaste:

Avgränsning av serviceuppgifter

Listan över tjänster kan begränsas utifrån områdesinformationen. Eventuella begränsningar är kommun (Municipality), landskap (Province) och välfärdsområde (WellbeingServiceCounties).

• /api/v11/Service/list/area/{area}/code/{code} returnerar alla tjänster som har en områdesuppgift enligt avgränsningen samt namnen på servicekanalerna och id:n i anslutning till dem.

Det är också möjligt att avgränsa tjänsterna utifrån följande värden:

• serviceklass (GET Service/serviceClass)
• målgrupp (GET Service/targetGroup)
• typ av tjänst (GET Service/type)
• tjänstens näringsgren (GET Service/industrialClass)

Du hittar de sökparametrar som behövs i följande fil.

Kodsystem som används i SDL, Myndigheten för digitalisering och befolkningsdata (XLSX, 14,07 kB)Öppnas i ett nytt fönster.

Kombinationssökningar med flera parametrar används tyvärr inte.

Avgränsning av servicekanaluppgifter

Även listan över servicekanaler kan avgränsas utifrån områdesuppgifterna. Eventuella begränsningar är kommun (Municipality), landskap (Ppovince) och välfärdsområde (WellbeingServiceCounties).

/api/v11/ServiceChannel/list/area/{area}/code/{code} returnerar alla servicekanaler som har en områdesuppgift enligt avgränsningen samt namnen på de tjänster som hör till dem och id:n.

Det är också möjligt att avgränsa servicekanalerna enligt typ av servicekanal.

Metoden /api/v11/ServiceChannel/type/{type} gör det möjligt att avgränsa sökningen enligt servicekanaltyp. Tillåtna värden är EChannel (e-tjänst), WebPage (webbsida), PrintableForm (utskrivbar blankett), Phone (telefonservice) och ServiceLocation (serviceställe).

Avgränsning av organisationsuppgifter

Listan över organisationer som returneras kan avgränsas utifrån områdesinformationen. Eventuella begränsningar är kommun (Municipality), landskap (Ppovince) och välfärdsområde (WellbeingServiceCounties).

• GET Organisation/area/{area}/code/{code}) returnerar alla publicerade organisationer som har områdesinformation enligt avgränsningen.
• GET Organization/list returnerar alla organisationer som har områdesinformation enligt avgränsningen och visar alla dessa organisationers tjänster och id:n.

Metoden returnerar också tjänster där den sökta organisationen är en annan ansvarig organisation för tjänsten (roleType: OtherResponsible).

Med många metoder är det möjligt att avgränsa sökningen enligt redigeringsdatum och söka innehåll som har ändrats

• efter ett angivet datum (date)
• före ett angivet datum (dateBefore) eller
• mellan vissa datum.

Det här är praktiskt om man bara vill hämta de uppgifter som ändrats efter föregående sökning.

OBS. Tiden i SDL-data har en annan precision än i parametrarna: i SDL-data rapporteras redigeringstiden med millisekundsprecision, men parametrarna har bara möjlighet att begränsa den med sekunders precision.

Uppgifter om organisationer

1. Sök nya och uppdaterade organisationer med metoden

GET api/v11/Organization?date=yyyy-mm-ddThh:mm:ss

• Du får listan id-namn för organisationen.
• OBS! Metoden returnerar antalet sidor i fältet (pagecount). Om värdet är >1, upprepa sökningen för varje sida: api/v11/Organization?date=yyyy-mm-ddThh:mm:ss&page=x.
• Ta tillvara alla id:n.
• Sök fullständiga uppgifter om organisationen i grupper om 100 id:n med metoden /api/v11/Organization/list?guids=id1,id2,id3,id4.
• Lägg till de nya organisationerna i din egen databas och uppdatera uppgifterna om ändrade organisationer.

2. Sök borttagna organisationer med metoden

GET /api/v11/Organization?status=archived&date=yyyy-mm-ddThh:mm:ss

Du får listan namn-id för organisationen. Ta bort organisationerna från din egen databas.

3. Sök organisationer som återställts till utkaststatus med metoden

GET /api/v11/Organization?status=withdrawn&date=yyyy-mm-ddThh:mm:ss

• Du får listan namn-id för organisationen.
• Ta bort organisationerna från din egen databas.

Uppgifter om tjänster

1. Sök nya och uppdaterade tjänster med metoden

GET api/v11/Service?date=yyyy-mm-ddThh:mm:ss

• Du får listan id-namn för tjänsten.
• OBS! Metoden returnerar även id för de tjänster vars kopplingsuppgifter har ändrats: servicekanaler har lagts till eller kopplingar tagits bort, eller tilläggsuppgifterna om en koppling har uppdaterats. OBS! Metoden returnerar antalet sidor i fältet (pagecount). Om dess värde är > 1, upprepa sökningen för varje sida.
• Ta tillvara alla id:n.
• Sök fullständiga uppgifter om tjänsten i grupper om 100 id:n med metoden /api/v11/Service/list?guids=id1,id2,id3,id4.
• Lägg till de nya tjänsterna i din egen databas och uppdatera uppgifterna om ändrade tjänster.

Vid sökning med datum som avgränsning returnerar metoden också de tjänster vars servicekanaler har ändrats: servicekanaler har lagts till eller tagits bort, eller kopplingsuppgifterna har ändrats.

2. Sök borttagna tjänster med metoden

GET /api/v11/Services?status=archived&date=yyyy-mm-ddThh:mm:ss

• Du får listan namn-id för tjänsten.
• Ta bort tjänsterna från din egen databas.

3. Sök tjänster som återställts till utkaststatus med metoden

GET /api/v11/Service?status=withdrawn&date=yyyy-mm-ddThh:mm:ss

• Du får listan namn-id för tjänsten.
• Ta bort tjänsterna från din egen databas.

Uppgifter om servicekanaler

1. Sök nya och uppdaterade servicekanaler med metoden

GET api/v11/ServiceChannel?date=yyyy-mm-ddThh:mm:ss

• Du får listan id-namn för servicekanalen.
• OBS! Metoden returnerar även id för de servicekanaler vars kopplingsuppgifter har ändrats: tjänster har lagts till, kopplingar tagits bort, eller tilläggsuppgifterna om en koppling har uppdaterats. OBS! Metoden returnerar antalet sidor i fältet (pagecount). Om dess värde är > 1, upprepa sökningen för varje sida.
• Ta tillvara alla id:n.
• Sök fullständiga uppgifter om servicekanalen i grupper om 100 id:n med metoden /api/v11/ServiceChannel/list?guids=id1,id2,id3,id4.
• Lägg till de nya servicekanalerna i din egen databas och uppdatera uppgifterna om ändrade servicekanaler.

2. Sök borttagna servicekanaler med metoden

GET /api/v11/ServicesChannel?status=archived&date=yyyy-mm-ddThh:mm:ss

• Du får listan namn-id för servicekanalen.
• Ta bort servicekanalerna från din egen databas.

3. Sök servicekanaler som återställts till utkaststatus med metoden

GET /api/v11/ServiceChannel?status=withdrawn&date=yyyy-mm-ddThh:mm:ss

• Du får listan namn-id för servicekanalen.
• Ta bort servicekanalerna från din egen databas.

Namn och användningsändamål för fälten för betjäningstid

Normala öppettider

Normala öppettider: i avsnittet veckodagar beskrivs de vanligaste öppettiderna för servicekanalen. Öppettiderna kan fastställas för den valda dagen* (00:00–24:00), dvs. öppettiden kan vara över ett dygn. En dags öppettider kan indelas i separata perioder av öppettider. Det kan finnas sammanlagt fyra perioder (exempel 1).

*) Alla veckodagar kan väljas (måndag–söndag)

Normala öppettider: i avsnittet veckodagar kan man som öppettid även välja `Alltid öppet (24/7)´ eller `Öppet med tidsbokning´.

Öppettiden kan antingen gälla tills vidare eller gälla perioden. I alternativet Gäller perioden anger användaren en tidsintervall då öppettiderna gäller. I båda alternativen är ovan nämnda alternativ tillgängliga (val av dag, 24/7, med tidsbokning).

1) gäller tills vidare – på tisdag och onsdag

Öppettider:
• Tisdag kl. 8.00-12.00, 13.00-14:00, 15:00-16:00 och 17:00-18:00
• Onsdag kl. 9.00-16:30
• Torsdag kl. 00:00 - 24:00 ← OBS! 24:00 anges i gränssnittet med värdet 00:00
{
"serviceHourType": "DaysOfTheWeek",
"validFrom": null,
"validTo": null,
"isClosed": false,
"validForNow": true,
"isAlwaysOpen": false,
"isReservation": false,
"additionalInformation": [
{
"value": "Test 1:gäller tills vidare ",
"language": "sv"
}
],
"openingHour": [
{
"dayFrom": "Tuesday",
"dayTo": null,
"from": "08:00:00",
"to": "12:00:00"
},
{
"dayFrom": "Tuesday",
"dayTo": null,
"from": "13:00:00",
"to": "14:00:00"
},
{
"dayFrom": "Tuesday",
"dayTo": null,
"from": "15:00:00",
"to": "16:00:00"
},
{
"dayFrom": "Tuesday",
"dayTo": null,
"from": "17:00:00",
"to": "18:00:00"
},
{
"dayFrom": "Wednesday",
"dayTo": null,
"from": "09:00:00",
"to": "16:30:00"
},
{
"dayFrom": "Thursday",
"dayTo": null,
"from": "00:00:00",
"to": "00:00:00"
}
]
}

2) gäller perioden - onsdag och torsdag

Period:
• 08.12.2023-10.12.2023
Öppettider:
• onsdag kl. 09:30-16:30
• torsdag kl. 09:30-16:30
{
"serviceHourType": "DaysOfTheWeek",
"validFrom": "2023-12-08T00:00:00",
"validTo": "2023-12-10T00:00:00",
"isClosed": false,
"validForNow": false,
"isAlwaysOpen": false,
"isReservation": false,
"additionalInformation": [
{
"value": "Test 2:gäller perioden",
"language": "sv"
}
],
"openingHour": [
{
"dayFrom": "Wednesday",
"dayTo": null,
"from": "09:30:00",
"to": "16:30:00"
},
{
"dayFrom": "Thursday",
"dayTo": null,
"from": "09:30:00",
"to": ”16:30:00"
}
]
}

3) gäller tills vidare – alltid öppet (24/7)

Öppettider:
• Alltid öppet (24/7)
{
"serviceHourType": "DaysOfTheWeek",
"validFrom": null,
"validTo": null,
"isClosed": false,
"validForNow": true,
"isAlwaysOpen": true,
"isReservation": false,
"additionalInformation": [
{
"value": "Test 3: gäller tills vidare – alltid öppet",
"language": "sv"
}
],
"openingHour": []
}

4) gäller tills vidare – öppet med tidsbokning

Öppettider:
• öppet med tidsbokning
{
"serviceHourType": "DaysOfTheWeek",
"validFrom": null,
"validTo": null,
"isClosed": false,
"validForNow": true,
"isAlwaysOpen": false,
"isReservation": true,
"additionalInformation": [
{
"value": "Test 4SV",
"language": "sv"
},
{
"value": "Test 4EN",
"language": "en"
},
{
"value": "Test 4: gäller tills vidare – öppet med tidsbokning",
"language": "sv"
}
],
"openingHour": []
},

5) gäller perioden – alltid öppet (24/7)

Period:
• 03.01.2024-04.01.2024
Öppettider:
• Alltid öppet (24/7)
{
"serviceHourType": "DaysOfTheWeek",
"validFrom": "2024-01-03T00:00:00",
"validTo": "2024-01-04T00:00:00",
"isClosed": false,
"validForNow": false,
"isAlwaysOpen": true,
"isReservation": false,
"additionalInformation": [
{
"value": "Test 5: gäller perioden – alltid öppet",
"language": "sv"
}
],
"openingHour": []
}

6) gäller perioden – öppet med tidsbokning

Period:
• 22.12.2023 - 24.12.2023
Öppettider:
• Öppet med tidsbokning
{
"serviceHourType": "DaysOfTheWeek",
"validFrom": "2023-12-22T00:00:00",
"validTo": "2023-12-24T00:00:00",
"isClosed": false,
"validForNow": false,
"isAlwaysOpen": false,
"isReservation": true,
"additionalInformation": [
{
"value": "Test 6: gäller perioden – öppet med tidsbokning",
"language": "sv"
}
],
"openingHour": []
}

7) gäller tills vidare – endast rubriken

Uppgift om normal betjäningstid kan skickas endast med hjälp av rubrikfältet. Datum eller uppgifter om öppettider är inte obligatoriska.
{
"serviceHourType": "DaysOfTheWeek",
"validFrom": null,
"validTo": null,
"isClosed": false,
"validForNow": true,
"isAlwaysOpen": false,
"isReservation": false,
"additionalInformation": [
{
"value": "Test 2A: endast rubriken",
"language": "sv"
}
],
"openingHour": []
}
],

Normala öppettider: över ett dygn (jour)

Normala öppettider: i avsnittet över ett dygn beskrivs öppettiderna för servicekanalen av jourtyp. I detta avsnitt börjar öppettiden oftast den valda dagen och fortsätter till följande dygn. Öppettiderna kan inte delas in i separata perioder.

*) Alla veckodagar kan väljas (måndag–söndag)

Öppettiden kan antingen gälla tills vidare eller gälla perioden. I alternativet Gäller perioden anger användaren en tidsintervall då öppettiderna gäller.

1) gäller tills vidare – från tisdag till onsdag

Öppettider:
• från tisdag 18:00 till onsdag 02:00
{
"serviceHourType": "OverMidnight",
"validFrom": null,
"validTo": null,
"isClosed": false,
"validForNow": true,
"isAlwaysOpen": false,
"isReservation": false,
"additionalInformation": [
{
"value": "Test 7: gäller tills vidare – från tisdag till onsdag",
"language": "sv"
}
],
"openingHour": [
{
"dayFrom": "Tuesday",
"dayTo": "Wednesday",
"from": "18:00:00",
"to": "02:00:00"
}
]
}

2) gäller perioden - från onsdag till fredag

Period:
• 23.12.2023 - 25.12.2023
Öppettider:
• från onsdag kl. 20:00 till fredag kl. 10:00
{
"serviceHourType": "OverMidnight",
"validFrom": "2023-12-23T00:00:00",
"validTo": "2023-12-25T00:00:00",
"isClosed": false,
"validForNow": false,
"isAlwaysOpen": false,
"isReservation": false,
"additionalInformation": [
{
"value": "Test 8: gäller perioden - från onsdag till fredag",
"language": "sv"
}
],
"openingHour": [
{
"dayFrom": "Wednesday",
"dayTo": "Friday",
"from": "20:00:00",
"to": "10:00:00"
}
]
},

Avvikande betjäningstider

I avsnittet ’Avvikande betjäningstider’ beskrivs öppettider som avviker från servicekanalens normala öppettider. I allmänhet är dessa tillfälliga och för dem fastställs en gällande period.

Tidsperioden för öppettiden kan vara en dag eller längre. I den här delen är det också möjligt att välja alternativet ’Stängt hela dagen’.

1) Datum, Tidsperiod: 26.12.2023

{
"serviceHourType": "Exceptional",
"validFrom": "2023-12-26T00:00:00",
"validTo": null,
"isClosed": false,
"validForNow": false,
"isAlwaysOpen": false,
"isReservation": false,
"additionalInformation": [
{
"value": "Test 9: datum",
"language": "sv"
}
],
"openingHour": [
{
"dayFrom": null,
"dayTo": null,
"from": "12:00:00",
"to": "15:00:00"
}
]
}

2) Dag - stängt hela dagen

Period: 26.12.2023
{
"serviceHourType": "Exceptional",
"validFrom": "2023-12-25T00:00:00",
"validTo": null,
"isClosed": true,
"validForNow": false,
"isAlwaysOpen": false,
"isReservation": false,
"additionalInformation": [
{
"value": "Testi 10: päivä, suljettu koko päivän",
"language": "sv"
}
],
"openingHour": []
},

3) Tidsperiod, Tidsperiod: 24.12.2023-25.12.2023

Öppettider:
• från torsdag kl. 20:00 till fredag kl. 10:00
{
"serviceHourType": "Exceptional",
"validFrom": "2023-12-24T00:00:00",
"validTo": "2023-12-25T00:00:00",
"isClosed": false,
"validForNow": false,
"isAlwaysOpen": false,
"isReservation": false,
"additionalInformation": [
{
"value": "Testi 11: ajanjakso",
"language": "sv"
}
],
"openingHour": [
{
"dayFrom": null,
"dayTo": null,
"from": "20:00:00",
"to": "10:00:00"
}
]
}

4) Tidsperiod - stängt hela dagen, Tidsperiod: 26.12.2023-27.12.2023

{
"serviceHourType": "Exceptional",
"validFrom": "2023-12-26T00:00:00",
"validTo": "2023-12-27T00:00:00",
"isClosed": true,
"validForNow": false,
"isAlwaysOpen": false,
"isReservation": false,
"additionalInformation": [
{
"value": "Testi 12: ajanjakso, suljettu koko päivän",
"language": "sv"
}
],
"openingHour": []
}