Beda Publikt Meriter API version 2

Här ligger dokumentationen av det publika API:et. För att läsa mer om API specifikationen gå till Publikt Meriter API swagger ui

• Övergripande beskrivning
• Termer och förkortningar
• Ändringshistorik
• Behörighetskontroller
  • Syften
  • API-anslutningspart
  • Ansvarsfördelning mellan Beda och PVL
    • Exempel: Olika kommuners API-anslutningspart har olika Syften i sitt avtal
    • Exempel: Delar av en elevs meriter lämnas ut från Beda
• Merittyp
  • Bakgrund
  • Utbildningsversion
  • Bedamerittyp
  • Ämnesbetyg går att utfärda först 2025-07-01
  • Listning av typer med beskrivning
• Identifikation av merit
  • Exempel Examensbevis högskoleförberedande examen GY11
  • Exempel Gymnasieintyg GY11
  • Listning av naturliga nycklar
• Inrapportering av meriter
  • Skapa
    • MeritId efter inrapportering
    • Exempel: PVL skickar in en merit som ny
    • Exempel: PVL skickar in en merit som ny, men som Beda redan har
    • Exempel: PVL skickar in merit, men går mot fel endpoint
  • Uppdatera
    • Meriten är skapad via API
    • Meriten är skapad via filinskick
      • Exempel: Beda hittar en motsvarande merit
      • Exempel: Beda hittar en motsvarande merit, men returnerar inget MeritId
  • Utdrag från betygskatalogen
• Felhantering och felmeddelanden
  • Regler per merittyp
    • Exempel: Regel för skapa Examensbevis högskoleförberedande examen GY11
• Hantering av personer med skyddade personuppgifter
  • Inrapportering av merit tillhörande person med skyddade personuppgifter
  • Utlämnande av meriter tillhörande person med skyddade personuppgifter
• Personnummer och samordningsnummer
• Allmänna villkor
• Juridiska krav som ställs på API-anslutningsparten
  • Inför anslutning
  • Vid användning av Bedas API
• Versionshantering
• Servicenivå
  • Testmiljö
  • Undantag
    • Force majeure
    • Fel orsakade av avtalsparten eller avtalsbrott
    • Tredjepartssystem utanför leverantörens kontroll
  • Systemtillgänglighet
  • "Rate limit"
  • Kontakt

Övergripande beskrivning

Detta API tillhandahåller funktionalitet för inrapportering och utlämning av meriter, både gymnasiala- och folkhögskolemeriter.

Inrapportering sker med hjälp av synkrona anrop med en persons merit per anrop. Vilken resurs som ska användas beror på vilken typ av merit som ska inrapporteras. För mer detaljer se stycket om merittyp. Vid inrapportering så validerar Beda att meriten ser korrekt ut och uppfyller vissa krav genom att applicera ett omfattande regelverk baserat på lagar och förordningar.

Utlämning sker genom personresursen och angivet personnummer. Då returneras en lista av länkar till personens meriter om de existerar enligt ett definierat syfte. Dessa länkar har dessutom metadata i form av merittyp, och utfärdandedatum. Genom att följa dessa länkar så visas all data för den valda meriten

Termer och förkortningar

• Identifikationsnummer - Kan vara antingen personnummer eller samordningsnummer
• Merit - Det som också ofta benämns som betyg. Då betyg dock kan betyda såväl ett betygsvärde t ex A eller MVG, som ett Högskoleförberedande examensbevis läst på gymnasiet, så har termen merit valts.
• Programvaruleverantör (PVL) - Behörighetsansvarig för slutanvändare och klient till API:et
• Utlämnande - Hämtning av en persons olika meriter
• Inrapportering - Inskick av merit till Beda

Ändringshistorik

För att se ändringar i API:et, se Ändringshistorik

Behörighetskontroller

Utgående från en enskild användare på en skola som vill rapportera in meriter till Beda, alternativt hämta ut meriter för en person från Beda behöver ett antal kontroller göras för att inblandade aktörer (Beda och PVL) ska kunna avgöra om begäran ska tillåtas eller inte:

• Vilket system är det som anropar Beda och är det ett system som får anropa Beda?
  • Avgörs av vilken PVL UHR utfärdat certifikatet till.
• Vid begäran om utlämnande: I vilket syfte görs begäran?
  • Vilken arbetsuppgift som användaren just nu ägnar sig åt avgör om meriter överhuvudtaget kommer att lämnas ut, samt vilka av en persons meriter som får lämnas ut, av juridiska skäl.
• Vid begäran om utlämnande och inrapportering: Har den enskilda användaren rätt att utföra arbetsuppgiften?
  • Se resonemang nedan om hur det avgörs.

Eftersom det inte skulle vara praktiskt möjligt för Beda att hålla ett fullständigt register med alla användare och dess rättigheter hos alla aktörer som anropar Beda behöver ansvaret för behörighetskontrollen delas mellan Beda och PVL.

Syften

För att uppnå uppgiftsminimering så filtreras sökresultatet med något som Beda valt att kalla Syfte, som kan likställas med syftet av uthämtningen av meriter. Ett syfte filtrerar främst på vilka merittyper som är aktuella. De kan även filtrera på visst ingående information. T.ex. om sekretessstatus från skatteverket ska skickas med eller inte. Det existerar syften som inte filtrerar information. PVL:ens behörighetssystem ska alltså inte tillåta användare att hämta meriter från Beda annat än vid nedan specificerade Syften. Vilka Syften som en API-anslutningspart får använda specificeras i avtal mellan API-anslutningspart och UHR.

I API:anrop ska Syfte anges med Id i tabellen ovan.

Vid oklarheter av hur Syftena ska tolkas, kontakta UHR.

Syfte används enbart vid utlämnande från Beda. Vid inrapportering är Syfte inte relevant och ska inte skickas med.

API-anslutningspart

För att ovanstående delning av ansvar ska kunna göras har Beda infört konceptet API-anslutningspart. En API-anslutningspart i Beda är en kommun, friskolekoncern eller liknande. Alltså en organisation som är huvudman för en eller flera skolenheter, och den organisation som UHR sluter avtal med för tillgång till Bedas API.

API-anslutningspart identifieras genom anslutningspartens organisationsnummer. UHR meddelar vilket organisationsnummer som ska användas för vilken kund. Anslutningspartens organisationsnummer är alltid 10 siffror utan bindestreck.

En API-anslutningspart har/kan ha:

• rättighet att hämta meriter från Beda baserat på ett eller flera syften (Se lista på syften ovan)
• rättighet att rapportera in meriter till Beda från en eller flera specifika skolenheter/folkhögskolor.
• en eller flera PVL:er som tillåts skicka anrop mot Beda. En kommun kan t.ex. ha en PVL som tillhandahåller elevhanteringssystem för gymnasiet och en annan PVL som tillhandahåller antagningssystem för komvux.

Det innebär att Beda vid begäran om utlämnande kontrollerar enligt:

• Om giltigt Certifikat
  • Om API-anslutningspart finns i Beda och har status aktiv
    • Om API-anslutningspart matchar Certifikat dvs. API-anslutningsparten i Beda har meddelat att de använder den PVL som Beda utfärdat certifikatet till.
      • Om API-anslutningspart har det inskickade Syftet bland sina beviljade Syften
        • Beda lämnar ut länkar till personens meriter filtrerade beroende på Syfte, dvs. en person kan ha 10 meriter i Beda, men Beda svarar med bara 7 länkar eftersom Syftet inte tillåter att de sista 3 lämnas ut. För att få tillgång till innehållet i meriterna följs en eller flera av länkarna.

Motsvarande för inrapportering:

• Om giltigt Certifikat
  • Om API-anslutningspart finns i Beda och har status aktiv
    • Om API-anslutningspart matchar Certifikat
      • Om API-anslutningspart får rapportera in meriter för den Skolenhet som meriten är utfärdad av behandlas meriten

Ansvarsfördelning mellan Beda och PVL

PVL:s ansvar:

• Endast behöriga användare ska få möjlighet att göra de arbetsuppgifter i PVL:ens system som ger tillgång till data från Beda. Det kan till exempel innebära att användargränssnittet för komvuxantagning bara ska kunna användas av personer som jobbar med komvuxantagning.
• Logga vilken enskild användare som gjort vilket enskilt anrop.
• Skicka med i vilket Syfte som användaren gör sin begäran (endast vid utlämnande, inte vid inrapportering) enligt av Beda specificerad lista. Exempelvis utfärdande av komvuxexamen.
• Skicka med vilken API-anslutningspart (se ovan) som användaren tillhör.

Bedas ansvar:

• Kontrollera att certifikatet är giltigt, utfärdat av UHR osv.
• Kontrollera att den API-anslutningspart som användaren tillhör har:
  • rättighet att hämta merit med det syfte som angetts. Det avgörs av avtal mellan API-anslutningspart och UHR.
  • rättighet att rapportera in betyg för den skolenhet/folkhögskola som betyget är utfärdat av.
• Filtrera utdata baserat på i vilket syfte som begäran har gjorts.

Exempel: Olika kommuners API-anslutningspart har olika Syften i sitt avtal

Stora kommunen har i sitt avtal med UHR ett Syfte: Antagning till kommunal vuxenutbildning. Lilla kommunen har istället Syftet Handläggning kommunalt aktivitetsansvar. Båda använder samma PVL:s IT-system SkolIT. Personal i Lilla kommunen som ska handlägga komvuxantagning ska då kunna använda SkolIT:s antagningsfunktionalitet, men inte få möjlighet att hämta meriter från Beda. När behörig handläggare i Stora kommunen handlägger komvuxantagning ska denne förutom att använda grundfunktionaliteten för antagning också kunna hämta meriter från Beda. SkolIT måste alltså hålla reda på vilka Syften som respektive kommun har, förutom att bara behörig personal inom kommunen ska kunna göra hämtning från Beda.

Exempel: Delar av en elevs meriter lämnas ut från Beda

• Anna Elevsson har ett Folkhögskoleintyg och ett Studiebevis, samt några kurser från Komvux från två olika kommuners komvuxskolor, i Beda.
• Martin i Stora kommun använder BetygIT:s funktion för att utfärda komvuxexamen och vill därför hämta hennes meriter från Beda.
  • BetygIT hanterar Martins behörighet att få använda den funktionen
  • Martin begär ut Annas meriter från Beda via BetygIT
  • BetygIT skickar en begäran till Beda med Syfte ”Utfärdande av komvuxexamen”
  • Beda lämnar ut länkar till Annas Studiebevis och samtliga kurser från Komvux, men inte Folkhögskoleintyget
  • I BetygIT visas möjlighet för Martin att hämta Studiebeviset och Komvuxkurserna.
  • Martin väljer i BetygIT att titta på Studiebeviset
  • BetygIT anropar återigen Beda för att hämta Studiebeviset
  • Beda lämnar ut Studiebeviset efter att återigen gjort behörighetskontroller för utlämnandet

Merittyp

Bakgrund

När en person genomfört en utbildning så utfärdas ett bevisdokument till personen som vi i denna kontext kallar för merit. Se definition av merit i avsnitt Termer och förkortningar ovan. Genom åren så har regelverk för utbildningar och dess utfärdade bevisdokument (meriter) förändrats kontinuerligt allt eftersom nya lagar och förordningar börjat gälla. Vissa förordningar har lett till helt nya typer av meriter, t.ex. i och med GY94 så kom de s.k. Slutbetygen och i och med GY11 kom Examensbevis (högskoleförberedande examen/yrkesexamen). Utöver dessa större lagändringar/förordningar så har det även tillkommit ett flertal som inte lett till nya typer av meriter utan bara förändrade regelverk kring existerande form av meriter. I och med att Beda validerar inskickade meriter mot det regelverk som existerar vid ett utfärdandedatum så är det en stor utmaning för Beda att veta vilket exakt regelverk som gäller. Existerande typer har inte varit finkorniga nog för att särskilja mellan t.ex. Slutbetyg från GY94 och GY00 så för att kunna veta vilka regler som ska appliceras så har det varit tvunget att analysera innehållet på meriten för att göra en bedömning. Detta har medfört problem vid validering av merit då det kan uppkomma fall där värden som analyseras för att välja regler råkar ha felaktigheter. För att adressera detta så har specifika begrepp för Beda skapats. Dessa är "Utbildningsversion" och "BedaMerittyp". Den senare benämns också vidare i detta dokument som "merittyp" men är en specifik typ som definieras av Beda.

Utbildningsversion

Det är skapat för att kunna hålla ihop regelverk och grunddata för utbildningar och dess utfärdade bevis på ett bättre sätt när lagar och förordningar ändras. Utbildningsversion är helt enkelt ett sätt att ge regelverk en kontext och livscykel att förhålla sig till. Utfärdandedatum är ett viktigt attribut gällande utbildningsversion. Det styr bland annat när utbildningsversion startar och slutar. En utbildningsversion innehåller också ett antal s.k. merittyper. När en förändring sker i regelverk, t.ex. i form av en ny förordning, stegas utbildningsversion upp och nya merittyper skapas. Det ska poängteras att det inte existerar någon skarp gräns när en utbildningsversion stegas upp och meriter får en ny typ. Det är helt enkelt subjektiv bedömning från Beda.

Exempel på utbildningsversioner kan hittas i tabellen nedan. GUV5 (Gymnasieutbildningsversion 5) är nuvarande utbildningsversion för gymnasiemeriter som i huvudsak utfärdas inom GY11. VUV2 (Vuxenutbildningsversion 2) är huvudsakligen meriter utfärdade inom VUX12. VUV3 är utbildningsversion för examensbevis högskoleförberedande examen komvux utfärdade fr.o.m. 2021-07-01. Anledningen till stegning från VUV2 -> VUV3 är att på examensbevis högskoleförberedande examen komvux så infördes studieområdeskod samt nya regler kring dessa fr.o.m. 2021-07-01. Så i VUV3 finns bara en enda merittyp, examensbevis högskoleförberedande examen komvux. Ändringar påverkade alltså inte yrkesexamen komvux så den behövde inte en ny typ.

Bedamerittyp

Från en utbildningsversion så skapas ett antal bedamerittyper. En inrapportering till Beda via API ska alltså göras på en av Beda definierad bedamerittyp. D.v.s. en inrapportering till Beda är ett påstående baserat på "Bedamerittyp" som gör att en klient till API måste veta exakt vilken "Bedamerittyp" den tänker sig rapportera in. Denna specifika bedamerittyp från en utbildningsversion styr vilket regelverk som ska appliceras vid validering. För att underlätta valet kommer nedan en tabell som listar typer med beskrivning och utfärdandedatum

Ämnesbetyg går att utfärda först 2025-07-01

Det kan vara värt att notera att GY-25 reformen började gälla först 2025-07-01 och därför kommer det inte gå att rapportera meriter med ett utfärdandedatum före det datumet. Det påverkar samtliga meriter som innehåller ämnesbetyg, så meriter med utbildningsversion GUV6, GUV7, VUV4, VUV5, FUV2, FUV3.

Listning av typer med beskrivning

Identifikation av merit

En merit i Beda har alltid en syntetisk nyckel i form av ett MeritId som är implementerad som en UUID. För varje merittyp finns även en naturlig nyckel som består av den minsta mängden attribut som kan definiera unikhet.

För merittyper där en person bara får ha en merit av en merittyp så består den naturliga nyckeln av identifikationsnummer.

För merittyper där en person får ha flera meriter av samma merittyp består den naturliga nyckeln av de värden som kan skilja sig åt mellan dessa meriter.

Exempel Examensbevis högskoleförberedande examen GY11

En student kan endast få ett examensbevis utfärdat och följdaktligen består den naturliga nyckeln endast av identifikationsnummer.

Exempel Gymnasieintyg GY11

En student kan dels få utfärdat flera gymnasieintyg där studievägskoden skiljer, men även flera där studievägskoden är samma men utfärdandedatumet skiljer.

Listning av naturliga nycklar

Inrapportering av meriter

Dels är inrapportering uppdelad i olika endpoints utifrån merittyp som nämnts ovan. Dels är det specifika endpoints för skapa och uppdatera som vi delat upp i separata underrubriker nedan.

Utdrag från betygskatalogen är till sin natur annorlunda än övriga meriter och avhandlas i en separat underrubrik nedan

Skapa

Skapa avser inrapportering av en ny merit som inte finns i Beda sedan tidigare. Med ny merit menas en merit vars naturliga nyckel (ett attribut/en kombination av flera attribut på en merit som unikt identifierar meriten i fråga i Beda), inte redan finns i Beda.

Endpointen har mönstret:

POST /meriter/v2/[gymnasie|komvux|folkhogskola]/"utbildningsversion"/"meritnamn"

t ex POST /meriter/v2/gymnasie/guv5/examensbevisyrkesexamen

MeritId efter inrapportering

När Beda sparat meriten returneras ett MeritId (en syntetisk nyckel i form av ett UUID) som måste sparas av PVL:en för att möjliggöra eventuell framtida rättning av den redan inskickade meriten i Beda.

Exempel: PVL skickar in en merit som ny

En kurs i biologi på Komvux ska rapporteras in till Beda från BetygIT. Läraren som satt betyget väljer att klicka på knappen för Bedaexport. Beda kontrollerar behörighet, att begäran uppfyller API-specifikationen, och kör ett paket med regelkontroller för att säkerställa att alla uppgifter är korrekta. Beda lagrar kursen och returnerar dess MeritID till BetygIT. BetygIT lagrar MeritID:t och presenterar för läraren att kursen exporterats till Beda.

Exempel: PVL skickar in en merit som ny, men som Beda redan har

En kurs på komvux för en elev rapporteras in till Beda enligt ovanstående exempel. Dagen efter skickas kursen igen, men med ett nytt betygsvärde. Då kommer den stoppas av Beda eftersom Beda anser att det är samma merit där bara innehållet ändrats. Om syftet var att rätta betygsvärdet, ska i stället endpoint för uppdatering användas, se nedan.

Exempel: PVL skickar in merit, men går mot fel endpoint

En skola utfärdar en Yrkesexamen från Bygg- och anläggningsprogrammet i GY11. Administratören på skolan väljer i BetygIT att exportera examen till Beda. PVL-en har kodat så att trots att det är en Yrkesexamen så skickas examen mot endpointen /meriter/v2/gymnasie/guv5/examensbevishogskoleforberedandeexamen. Beda svarar med felmeddelande om att studievägkoden inte är tillåten på merittypen.

Uppdatera

Uppdatera avser rättning av en till Beda redan inrapporterad merit. De flesta merittyper låses för uppdatering i Beda 14 dagar efter första inskick. Beda kommer att avvisa ändringen om försök till uppdatering av en låst merit görs. Skolan måste då kontakta UHR och begära upplåsning för att uppdatering ska kunna göras.

Endpointen har mönstret:

PUT /meriter/v2/[gymnasie|komvux|folkhogskola]/"utbildningsversion"/"meritnamn"/{meritId}

t ex PUT /meriter/v2/gymnasie/guv5/examensbevisyrkesexamen/af1287d0-50dc-3eea-9fbf-019b6fa24722

Meriten är skapad via API

Uppdatering (rättning) av innehåll i en merit som skickats in sedan tidigare till Beda görs genom att anropa uppdaterings-endpoint för den aktuella merittypen med det MeritId som Beda svarade med när meriten skapades. Visst innehåll i meriterna tillåter Beda inte att det ändras. Det är merittypsberoende, men kan till exempel vara personnummer, skolenhetskod och utfärdandedatum. Skulle ett sådant innehåll behöva uppdateras (rättas) måste skolan kontakta UHR som beroende på merittyp antingen plockar bort den redan inrapporterade meriten för att lämna plats för den nya eller så uppdaterar UHR den redan inrapporterade meriten manuellt.

Meriten är skapad via filinskick

Om meriten skapades före övergång till API-inskick har PVL:en inget MeritId sparat, och kan därför inte anropa en uppdaterings-endpoint med MeritId. Här beskrivs hur PVL:en kan göra för att få tag på det aktuella MeritId och i övrigt gäller allt som står under rubriken Meriten är skapad via API ovan.

För att få tag på MeritId för en merit i Beda finns endpoints med mönstret:

POST /meriter/v2/[gymnasie|komvux|folkhogskola]/"utbildningsversion"/"meritnamn"/motsvarande

t ex POST /meriter/v2/gymnasie/guv5/examensbevisyrkesexamen/motsvarande

Till denna endpoint ska bifogas en NaturligNyckelRequest vars innehåll varierar från merittyp till merittyp. Se stycket Identifiering av merit.

Beda kommer bara att svara med ett MeritId i de fall där API-anslutningsparten har behörighet att uppdatera meriten.

Notera att Beda inte gör någon kontroll av innehållet i meriten annat än den naturliga nyckeln och merittyp för att avgöra om det finns en motsvarande sparad i Beda. Innehållet i meriten som är sparad i Beda kan därför skilja sig betydligt från den som ligger hos PVL:en och som Beda kommer att uppdatera till när MeritId:t som hämtats via "motsvarande" sen används för att begära uppdatering av meriten.

Observera att denna funktion endast får användas i samband med uppdateringar av meriter som skickats in via filinskick. I annat fall måste det av PVL:en tidigare sparade MeritId:t användas vid uppdatering.

Exempel: Beda hittar en motsvarande merit

• En elev kontaktar skolan och gör de uppmärksamma på att de rapporterat in fel betygsvärde på hennes betyg i SVESVE01 i hennes högskoleförberedande examen från EKJUR. Hon säger att det ska vara D, men att det står E på hennes examensbevis. Skolan utreder och kommer fram till att de gjort fel.
• Skolan ändrar betyget i BetygIT och önskar uppdatera det i Beda. BetygIT har ingen syntetisk nyckel till meriten eftersom den rapporterades in på fil. Användaren väljer att uppdatera betyget i Beda. BetygIT skickar först en förfrågan till Beda för att ta reda på vilken den syntetiska nyckeln är genom att skicka förfrågan till motsvarande-endpointen för högskoleförberedande examen med personnumret som indata.
• Beda hittar en högskoleförberedande examen för det personnumret utfärdad på en av de skolor som API-anslutningsparten har behörighet att rapportera för.
• Beda returnerar MeritId:t.
• BetygIT anropar uppdatera endpoint i Beda med MeritId och den uppdaterade meriten.
• Meriten i Beda avspeglar nu innehållet i Beda

Exempel: Beda hittar en motsvarande merit, men returnerar inget MeritId

• Två första punkterna som exemplet ovan
• Beda hittar en högskoleförberedande examen för det personnumret utfärdad på en skola som inte är kopplad till den API-anslutningspart som anropat Beda.
• Beda returnerar inget MeritId. Istället returneras HTTP status 403

Utdrag från betygskatalogen

Utdrag från betygskatalogen skiljer sig från övriga meriter i Beda. De representerar en ögonblicksbild av en students samlade delmeriter inom en utbildningsversion vid ett givet datum för en specifik skola. Med delmeriter avses kurser, arbeten, ämnesnivåer, dvs det som när studenten läst klart används för att utfärda en examen/studiebevis/gymnasieintyg.

Varje sådan delmerit har ett datum för betygssättning. Själva utdraget har ett utfärdandedatum som representerar när ögonblicksbilden togs.

Då utdraget representerar en ögonblicksbild så har vi inte som för övriga meriter separata endpoints för skapa och uppdatera/rätta. Istället har vi en enda endpoint som sparar utdraget och skriver över eventuellt existerande utdrag för samma person och skola.

Det kan noteras att endpointen inte returnerar något MeritId då det inte finns något behov av det. Däremot kan det vara klokt för anroparen att vid ett lyckat anrop spara undan personnummer, skolenhetskod, utfärdandedatum och merittyp för att kunna se när det senast skickades in ett utdrag av viss merittyp för en person och skola.

Beda lagrar alltså det senaste inskickade utdraget för en person och skola inom en utbildningsversion. Utdragen får således aldrig någon senast ändrad tidpunkt i Beda utan registreringsdatum representerar när det nu aktuella utdraget sparades i beda.

Felhantering och felmeddelanden

Vid anrop mot det publika api:t kan åtta typer av fel uppkomma:

Vi använder oss av RFC:n problem.json vid fel som uppkommer vid anrop till API:et som beskriver ett standardiserat sätt att visa felmeddelanden. Den sista delen är konfigurerbar och här har vi valt en lista med valideringsproblem som innehåller två uppgifter.

• meddelande - en detaljerad beskrivning av problemet
• metadata - metadata som kan vara orsaken till problemet

Regler per merittyp

I tabellen nedan finns länkar till de kontroller som sker vid behörighetsprövning och inrapportering för respektive merittyp. Detta för att möjliggöra för klienten att kunna göra rätt kontroller och ge rätt förutsättningar i sin klientprogramvara för att inrapporteringen inte ska leda till onödiga valideringsproblem.

Exempel: Regel för skapa Examensbevis högskoleförberedande examen GY11

I tabellen visas i kolumnerna Beskrivning respektive Felmeddelande: "Kurskoder måste vara unika i en gymnasieexamen. D.v.s. inga duplicerade kurskoder tillåts." och "Kurskoder existerar mer än en gång på gymnasieexamen" För att få bättre kontroll över feedback till användaren i klientens egna system så görs lämpligen denna kontroll på klientsidan så att det kan fångas redan innan en inrapportering sker mot Beda.

Hantering av personer med skyddade personuppgifter

I Beda finns meriter tillhörande personer som har skyddade personuppgifter hos Skatteverket. De kan antingen ha skyddsnivån Sekretessmarkering eller Skyddad folkbokföring. Mer information om de olika typerna av skydd finns hos Skatteverket, på https://skatteverket.se/privat/folkbokforing/skyddadepersonuppgifter.4.18e1b10334ebe8bc80001711.html

Inrapportering av merit tillhörande person med skyddade personuppgifter

Meriter tillhörande personer med skyddade personuppgifter ska rapporteras in på samma sätt som för övriga elever. Elevens namn och personnummer ska anges, dvs. inget fiktivt namn eller personnummer får användas vid inrapportering.

Utlämnande av meriter tillhörande person med skyddade personuppgifter

Vid varje utlämnande av meriter från Beda görs en slagning mot Skatteverket för att hämta aktuell skyddsstatus. I de fall personen har skyddade personuppgifter lämnas meriterna i regel ut och i svaret från endpointen ”personer” levereras information om personens skydd, se PersonMetadataRepresentation i Swaggerdokumentationen.

Personnummer och samordningsnummer

Beda hanterar enbart meriter tillhörande personer med svenska personnummer eller samordningsnummer. Observera att det alltså inte går att rapportera in meriter från personer med s.k. tillfälliga personnummer. Information om samordningsnummer finns på https://skatteverket.se/privat/folkbokforing/samordningsnummer.4.5c281c7015abecc2e201130b.html

Allmänna villkor

I UHR:s allmänna villkor Allmänna villkor för bedas api för API-tjänsten finns bland annat vissa krav på loggning hos PVL och information om hur förändringar i API:et kan komma att göras osv. De allmänna villkoren är därför ett viktigt komplement till denna introduktion, Swaggerdokumentationen mm.

Juridiska krav som ställs på API-anslutningsparten

Inför och vid användning av Bedas API-tjänst ställer UHR ett antal krav på API-anslutningsparten (AAP). Till följd av dessa krav begränsas i praktiken programvaruleverantörernas (PVL) möjlighet att behandla uppgifter som hämtas från Beda eftersom kraven tvingar AAP att reglera PVL:ens hantering.

Inför anslutning

I samband med att AAP ansöker om anslutning för att lämna in och/eller hämta ut uppgifter ska de ange om de använder sig av PVL. Om så är fallet ska de intyga att de har personuppgiftsbiträdesavtal samt att de har reglerat tystnadsplikt/sekretess i avtal om PVL:en i fråga inte omfattas av offentlighets- och sekretesslagen (2009:400).

Ett personuppgiftsbiträdesavtal ska innehålla en instruktion från den personuppgiftsansvarige till biträdet (i detta fall PVL:en). Instruktionen ska följa villkoren för nyttjande av tjänsten (vilket bl.a. innefattar efterlevnad till GDPR) samt ange hur aktuella personuppgifter får behandlas och för vilka ändamål. Det är inte tillåtet för biträdet att behandla personuppgifter på ett sätt som strider mot, eller går utöver, vad som anges i instruktionen. I personuppgiftsbiträdesavtalet sätter AAP/PUA gränser för PVL:s/PUB möjligheter att behandla personuppgifter, detta för att säkerställa att dess underbiträde lever upp till samma krav som ställs på PUA i villkor för tjänsten/dataskyddslagstiftning.

Den reglerade tystnadsplikten ska medföra att PVL:en inte får röja uppgifter som hämtas från Beda för någon annan än AAP:n vid tillhandahållandet av sin tjänst. Detta innebär att PVL:en inte får dela eller tillgängliggöra uppgifterna från Beda i samband med att de hämtas via API:et till annan än den bestämda slutmottagaren, dvs. AAP. Det är därmed inte tillåtet för en PVL att skicka/visa uppgifter från Beda för utomstående parter eller den enskilde själv innan AAP:en har gjort en sekretessprövning.

Vid användning av Bedas API

Möjligheten att hämta uppgifter om gymnasiala meriter via Bedas API-tjänst bygger på att AAP hanterar uppgifterna i enlighet med gällande dataskydds- och sekretessreglering. För det fall AAP använder sig av en PVL gäller kraven på lagenlighet även denne. Om regelefterlevnad inte upprätthålls riskerar AAP:n att tillfälligt eller permanent, stängas av från eller begränsas i sin åtkomst till Bedas API. Det är därför nödvändigt att den personuppgiftsansvarige (AAP) gör en bedömning av lagligheten i varje tilltänkt personuppgiftsbehandling som denne och dess biträden (PVL) vill genomföra.

Versionshantering

Vi använder oss av semantisk versionshantering.

Vi använder oss även av MAJOR version i URL i form av v2

Servicenivå

Denna sektion beskriver Bedas servicenivå.

Beda är normalt tillgänglig dygnet runt, bortsett från ett servicefönster, se Systemtillgänglighet. Beda kan begränsa tillgängligheten till API:et i enlighet med vad som framgår av detta dokument samt de Allmänna villkoren.

Testmiljö

Programvaruleverantörer har tillgång till en anonymiserad miljö för att testa integration mot Bedas publika API. Den miljön omfattas inte av angivna servicenivåer.

Undantag

Följande situationer undantar de garanterade servicenivåerna.

Force majeure

Om händelser utanför rimlig kontroll som omöjliggör eller väsentligt försvårar fullgörandet av servicenivån uppstår gäller inte angivna servicenivåer. Detta inkluderar men är inte begränsat till, krig, terroristattacker eller militära konflikter, naturkatastrofer såsom översvämningar, jordbävningar eller stormar, pandemi eller nationella hälsokriser, strejk eller arbetskonflikt som påverkar Bedas verksamhet, strömavbrott i samhällskritisk infrastruktur utanför Bedas kontroll.

Fel orsakade av avtalsparten eller avtalsbrott

Situationer där avtalsparternas egna handlingar eller underlåtenhet orsakat fel eller avbrott:

• Felaktig implementering eller användning av API:et som avviker från publicerad specifikation
• Användning av föråldrade API-versioner
• Överträdelse av rate limiting
• Underlåtenhet att bistå leverantören med nödvändig information vid felsökning
• Bristande efterlevnad av säkerhetskrav, t.ex. hantering av API-certifikat
• Avtalspartens egna system, nätverk eller konfigurationsfel

Tredjepartssystem utanför leverantörens kontroll

Fel eller avbrott som uppstår i Beda eller infrastruktur som Beda inte rår över kan påverka servicenivån. Ex. oförutsedda händelser hos driftleverantör eller Navets tillgänglighet.

Systemtillgänglighet

API:et är normalt tillgängligt veckans alla dagar, exklusive planerade avbrott. Planerade avbrott är möjliga varje morgon mellan 06:30 och 07:30. Under den tiden kan API:et vara nere p.g.a. uppdateringar, när det bedöms nödvändigt.

Sällsynta oplanerade avbrott kan uppstå om akut patchning behövs, utan möjlighet till förvarning. Det kan röra sig om, men inte begränsat till, akuta säkerhetsuppdateringar.

"Rate limit"

För att skydda Beda från överbelastning är "rate limiting" konfigurerad. Det innebär att det finns en gräns för hur många anrop en programvaruleverantör kan göra under en viss tidsperiod. Om gränsen överskrids kommer API:et att returnera en HTTP statuskod "429 Too Many Requests" och programvaruleverantören måste vänta innan den kan göra fler anrop. Gränserna för rate limiting kan komma att justeras över tid.

Beda följer Dataportalens riktlinjer för REST API:er för rate limiting.

Beda retunerar därmed följande headrar i varje svar:

Om ni slår i rate limit kommer ni att få en HTTP statuskod 429 Too Many Requests, och ni måste vänta tills rate limit återställs innan ni kan göra fler anrop. Svaret kommer även att innehålla en Retry-After header som anger hur många sekunder ni måste vänta innan ni kan göra fler anrop.

Kontakt

Frågor om denna dokumentation eller andra frågor om Bedas API, inklusive felanmälan, skickas till beda@uhr.se.