Fra FSWS-Feide-Semreg til FS GraphQL API

⚠ Denne tjenesten avvikles etter 31. mars 2027. Nye integrasjoner bør bygges direkte på FS GraphQL API. Se Sikts avviklingspraksis og avviklingsloggen. Kilde: Teknisk dokumentasjon for FSWS-Feide-Semreg

Denne guiden hjelper deg migrere fra FSWS-Feide-Semreg til FS GraphQL API.

FSWS-Feide-Semreg leverer dataene et digitalt studentbevis trenger: navn, brukernavn, studentnummer, strekkodegrunnlag, semesterregistreringsstatus med gyldig-til-dato, og lærestedets navn på bokmål og engelsk.

Under gir vi et eksempel per endepunkt. GraphQL gir større fleksibilitet enn Semreg: du bestemmer selv hvilke felt som skal med. Ta kontakt med fs-support@sikt.no dersom du trenger hjelp til å finne en spørring som passer ditt behov.

Før du starter

Sett deg inn i disse tingene før du går videre:

• Tilgang, endepunkt og kontraktsnivå (Feature-Flags-header): Kom i gang
• Feilhåndtering: Mutasjoner
• Autorisasjon (RAS): Tilgangsstyring med RAS
• Bruker du en integrasjonsplattform (Gravitee/IntArk): FS GraphQL API og IntArk
• Utforsk skjemaet selv: Introspeksjon
• Generell spørringsdokumentasjon: Spørringer

Tilgang: ingen egen RAS-rolle kreves

Denne guidens datasett har ingen egen navngitt RAS-rolle. Vanlig autentisert tilgang er nok — se Tilgangsstyring med RAS for hvordan API-brukeren din bestilles.

Autentisering: megVedLarested krever et sluttbrukertoken

Semreg leste studentens identitet fra Dataporten-innloggingen. megVedLarested gjør det samme: spørringen finner personen ut fra fødselsnummeret i tokenet, og returnerer én PersonProfil per lærested personen er registrert ved og som klienten har tilgang til. Spørringen tar ingen argumenter — lærestedet trenger du ikke oppgi selv.

Har tokenet ikke et fødselsnummer — for eksempel et rent maskin-til-maskin-token (client credentials) — returnerer spørringen en tom liste, ikke en feilmelding (bekreftet i QueryResolver.megVedLarested()). Skal integrasjonen din hente studentbevisdata uten en innlogget student, bruk oppslagsspørringene i stedet.

Kontraktsnivå i eksemplene

Alle eksemplene i denne guiden krever headeren Feature-Flags: beta,experimental.

• beta: megVedLarested, StudentVedLarested.bilde
• experimental: studentbeviskode, gjeldendeSemesterkvittering (og alle dens felt: erGyldigNaa, utlopsdato, termin), escUrl, samt selve spørringen studenterGittFodselsnumre

Studentbevis-feltene er i dag kun tilgjengelige på experimental. Trenger du dem i produksjon, ta kontakt med fs-support@sikt.no og be om at de løftes til beta. Se Stabil semesterregistreringsstatus uten experimental-felt for en stabil, men mindre presis, variant.

IDer: er de samme som i FSWS-Feide-Semreg?

Semreg hadde ingen objekt-IDer i det hele tatt — svaret inneholdt bare verdier (studentnr, strekkode, brukernavn), ingen identifikator du kunne slå opp med senere. Verdiene du kjenner fra Semreg er uendret: student.studentnummer gir samme verdi som studentnr, og student.studentbeviskode gir samme verdi som strekkode.

FS GraphQL API gir i tillegg hvert objekt en egen id — disse er nye og har ingen motpart i Semreg. Behandle dem som ugjennomsiktige: du kan base64-dekode dem, men innholdet er en intern implementasjonsdetalj som kan endres uten varsel. Trenger du en identifikator til en senere, mer avgrenset spørring, be om id-feltet direkte i samme kall du allerede gjør.

Sjekk om studenten har gyldig semesterregistrering

Semreg returnerte en enkel boolean. I GraphQL bruker du megVedLarested og navigerer til student.gjeldendeSemesterkvittering.erGyldigNaa.

FSWS-Feide-Semreg eksempel:

GET <dataporten-url>/gyldig

FSWS-Feide-Semreg respons:

true

FS GraphQL API spørring:

query SjekkGyldigSemesterregistrering {
  megVedLarested {
    student {
      gjeldendeSemesterkvittering {
        erGyldigNaa
        utlopsdato
        termin {
          arstall
          betegnelse {
            kode
          }
        }
      }
    }
  }
}

Eksempel på respons:

{
  "data": {
    "megVedLarested": [
      {
        "student": {
          "gjeldendeSemesterkvittering": {
            "erGyldigNaa": true,
            "utlopsdato": "2026-08-31",
            "termin": {
              "arstall": 2026,
              "betegnelse": {
                "kode": "VÅR"
              }
            }
          }
        }
      }
    ]
  }
}

erGyldigNaa er ikke helt det samme som Semregs gyldigRegistrert — se Viktige forskjeller under.

Hent studentinformasjon for studentbevis

Semreg returnerte et komplett Student-objekt. I GraphQL bruker du megVedLarested og navigerer til student for tilsvarende data.

FSWS-Feide-Semreg eksempel:

GET <dataporten-url>/info

FSWS-Feide-Semreg respons (forenklet):

{
  "navn": "Ola Nordmann",
  "brukernavn": "ola",
  "studentnr": "123456",
  "strekkode": "123456",
  "gyldigRegistrert": true,
  "termin": "2026V",
  "datoGyldigTil": "2026-08-16",
  "studiested": "Universitetet i Oslo",
  "studiestedEn": "University of Oslo",
  "bilde": {
    "bildeBase64": "/9j/4AAQSkZJRgABAQ...",
    "bildetype": "JPG"
  }
}

FS GraphQL API spørring:

query HentStudentInfo {
  megVedLarested {
    navn {
      fornavn
      etternavn
    }
    feideBruker
    student {
      studentnummer
      studentbeviskode
      larested {
        navnAlleSprak {
          nb
          en
        }
      }
      gjeldendeSemesterkvittering {
        erGyldigNaa
        utlopsdato
        termin {
          arstall
          betegnelse {
            kode
          }
        }
      }
      bilde {
        bilde
        filtype
      }
      escUrl
    }
  }
}

Eksempel på respons:

{
  "data": {
    "megVedLarested": [
      {
        "navn": {
          "fornavn": "Ola",
          "etternavn": "Nordmann"
        },
        "feideBruker": "ola@uio.no",
        "student": {
          "studentnummer": "123456",
          "studentbeviskode": "123456",
          "larested": {
            "navnAlleSprak": {
              "nb": "Universitetet i Oslo",
              "en": "University of Oslo"
            }
          },
          "gjeldendeSemesterkvittering": {
            "erGyldigNaa": true,
            "utlopsdato": "2026-08-31",
            "termin": {
              "arstall": 2026,
              "betegnelse": {
                "kode": "VÅR"
              }
            }
          },
          "bilde": {
            "bilde": "/9j/4AAQSkZJRgABAQ...",
            "filtype": "JPG"
          },
          "escUrl": "https://myesc.org/12345678"
        }
      }
    ]
  }
}

Nytt i FS GraphQL API: escUrl fantes ikke i Semreg — det er URL til studentens europeiske studentbevis, satt sammen av tjenestens adresse og studentens ESCN, og er tom dersom studenten ikke har et ESCN.

Oppslag uten innlogget bruker

megVedLarested fungerer bare når tokenet representerer studenten selv. Kjører du en integrasjon som skal hente studentbevisdata på vegne av lærestedet — uten et innlogget sluttbrukertoken — bruker du et oppslag i stedet. Begge returnerer StudentVedLarested direkte; persondataene (navn, Feide-bruker) ligger da under personProfil, ikke på toppnivå.

Argumentet eierOrganisasjonskode er institusjonsnummeret til lærestedet som eier dataene. Eksemplene bruker "1234" — bytt til ditt eget.

Med Feide-brukernavn (krever full form med domene — studenterGittFeideBrukere hopper stille over brukernavn uten @, og returnerer tomt svar uten feilmelding):

query HentStudentInfoGittFeideBrukere {
  studenterGittFeideBrukere(
    eierOrganisasjonskode: "1234"
    feideBrukere: ["ola@uio.no"]
  ) {
    studentnummer
    studentbeviskode
    personProfil {
      navn {
        fornavn
        etternavn
      }
      feideBruker
    }
    larested {
      navnAlleSprak {
        nb
        en
      }
    }
    gjeldendeSemesterkvittering {
      erGyldigNaa
      utlopsdato
      termin {
        arstall
        betegnelse { kode }
      }
    }
    bilde {
      bilde
      filtype
    }
    escUrl
  }
}

Med fødselsnummer (studenterGittFodselsnumre er selv experimental, i tillegg til de øvrige experimental-feltene):

query HentStudentInfoGittFodselsnumre {
  studenterGittFodselsnumre(
    eierOrganisasjonskode: "1234"
    fodselsnumre: ["XXXXXXXXXXX"]
  ) {
    studentnummer
    studentbeviskode
    personProfil {
      navn {
        fornavn
        etternavn
      }
      feideBruker
    }
    larested {
      navnAlleSprak {
        nb
        en
      }
    }
    gjeldendeSemesterkvittering {
      erGyldigNaa
      utlopsdato
      termin {
        arstall
        betegnelse { kode }
      }
    }
    bilde {
      bilde
      filtype
    }
    escUrl
  }
}

Stabil semesterregistreringsstatus uten experimental-felt

gjeldendeSemesterkvittering er experimental. Trenger du bare å vite om studenten er semesterregistrert og har betalt semesteravgift, finnes en stabil vei:

Kontraktsnivå: megVedLarested er beta, resten er stable. Krever Feature-Flags: beta.

query SemesterstatusStabil {
  megVedLarested {
    student {
      semesterregistreringIInnevarendeSemester {
        erSemesterregistrert
        harBetaltSemesteravgiftV2
        termin {
          arstall
          betegnelse { kode }
        }
      }
    }
  }
}

⚠ Ikke bruk harBetaltSemesteravgift (uten V2) — den er @deprecated med frist 15.03.2026, allerede passert.

Merk at dette ikke er en fullverdig erstatning for erGyldigNaa: den tar ikke hensyn til betalings- og registreringsform eller utløpsdato + 24 timers grace-periode. Til et digitalt studentbevis som skal vise gyldighet, trenger du fortsatt gjeldendeSemesterkvittering.

Feltmapping

Studentinformasjon (fra GET <dataporten-url>/info)

Feltmapping fra FSWS-Feide-Semreg til FS GraphQL API

FSWS-Feide-Semreg felt	FS GraphQL API (sti fra megVedLarested)	Kontraktsnivå
navn	navn.fornavn + navn.etternavn	stable
brukernavn	feideBruker	stable
studentnr	student.studentnummer	stable
strekkode	student.studentbeviskode	experimental
gyldigRegistrert	student.gjeldendeSemesterkvittering.erGyldigNaa — ikke identisk betydning, se under	experimental
termin ("2026V", én streng)	student.gjeldendeSemesterkvittering.termin.arstall (2026) + .betegnelse.kode ("VÅR"/"HØST")	experimental
datoGyldigTil	student.gjeldendeSemesterkvittering.utlopsdato — ikke identisk betydning, se under	experimental
studiested	student.larested.navnAlleSprak.nb	stable
studiestedEn	student.larested.navnAlleSprak.en	stable
bilde.bildeBase64	student.bilde.bilde	beta
bilde.bildetype	student.bilde.filtype	beta

fodselsdato og escnInfoUrl finnes ikke i FSWS-Feide-Semregs faktiske skjema (kun de 10 feltene i tabellen over, verifisert mot tjenestens publiserte schemav1.json) — ikke bruk dem som utgangspunkt for mapping. GraphQL sin escUrl er nytt, ikke en migrert erstatning — se over.

Gyldighetsstatus (fra GET <dataporten-url>/gyldig)

Gyldighetsstatus (fra GET <dataporten-url>/gyldig)

FSWS-Feide-Semreg	FS GraphQL API
Returnerer true/false	gjeldendeSemesterkvittering.erGyldigNaa

Viktige forskjeller

• Gyldighetsstatus: Semreg returnerte gyldigRegistrert (om studenten er gyldig semesterregistrert) og datoGyldigTil (dato studentkortet er gyldig). erGyldigNaa er ikke det samme: den krever i tillegg at betaling er OK, at betalings- og registreringsform tillater kvittering, og at utløpsdato + 24 timers grace-periode ikke er passert. utlopsdato er en beregnet fast dato — 31. august samme år for VÅR/SOM, 31. januar neste år for HØST — og kan derfor avvike fra Semregs datoGyldigTil. Kontroller mot dine egne data før du bytter.
• Terminformat: Semreg returnerte "2026V" som én streng. GraphQL gir termin.arstall (2026) og termin.betegnelse.kode ("VÅR" eller "HØST") hver for seg.
• Navn: Semreg returnerte navn som én streng («Fornavn Etternavn»). GraphQL gir navn.fornavn og navn.etternavn separat — klienten setter dem sammen selv.
• Enhetsendepunktene har ingen erstatning. /devices lagret hvilken mobilenhet en bruker hadde studentbevisappen installert på. Dette er ikke FS-data, og FS GraphQL API eksponerer det ikke. Trenger appen din denne koblingen, må du lagre den i din egen backend.

Kontakt oss for hjelp ved behov

Kontakt fs-support@sikt.no dersom du trenger hjelp til å komme i gang, eller underveis i migreringen.