Fra FSWS-Hovedbok 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-Hovedbok
FSWS-Hovedbok overfører studentkrav og studentinnbetalinger til lærestedets økonomisystem, gjennom ett endepunkt: POST /okonomi/hovedbok. Endepunktet dekket to brukstilfeller, styrt av parameteren beregning:
beregning=Ny– kjører en ny hovedbokføring med alle konteringer til og med en gitt datoberegning=Tidligere– gjenskaper en hovedbokføring som er kjørt tidligere, gitt buntnummeret
I FS GraphQL API er de to brukstilfellene delt i én mutasjon og én spørring:
| FSWS-Hovedbok (REST) | FS GraphQL API |
|---|---|
POST /okonomi/hovedbok med beregning=Ny | Mutasjonen overfoerTilHovedbok |
POST /okonomi/hovedbok med beregning=Tidligere | Spørringen tidligereHovedbokfoering |
Denne guiden hjelper deg migrere. Ta kontakt med fs-support@sikt.no dersom noe mangler.
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
Kontraktsnivå i eksemplene
Alt i denne guiden — begge operasjonene og alle felt i svaret — ligger på kontraktsnivå beta. Alle eksemplene under krever derfor headeren Feature-Flags: beta. Uten den finnes ikke feltene i skjemaet, og du får feilen FieldUndefined.
Tilgang: du trenger RAS-rollen HOVEDBOK
Datasettet i denne guiden krever RAS-rollen HOVEDBOK, som gir både lese- og skrivetilgang til hovedbokoverføring. Mangler du rollen, feiler både tidligereHovedbokfoering og overfoerTilHovedbok med en eksplisitt feilmelding — du får ikke et tomt eller delvis svar.
Se Tilgang til Hovedbokføring for bestillingsrutine.
Institusjonsnummer i eksemplene
I FSWS-Hovedbok var lærestedet implisitt gitt av brukeren du autentiserte deg som. I FS GraphQL API oppgir du det eksplisitt i input.eierOrganisasjonskode. Eksemplene under bruker "1234" — bytt ut med institusjonsnummeret til ditt lærested.
IDer: er de samme som i FSWS-Hovedbok?
Ja. buntnummer og bilagsnummer er nøyaktig de samme verdiene FSWS-Hovedbok returnerte som buntnr og bilagsnr — bare uten eventuelle mellomrom foran og bak. Lagrede buntnumre fra din eksisterende integrasjon kan brukes direkte som input.buntnummer.
Hent en tidligere hovedbokføring
Kontraktsnivå: beta
I FSWS-Hovedbok hentet du en tidligere bunt ved å sette beregning=Tidligere og oppgi buntnr. I FS GraphQL API bruker du spørringen tidligereHovedbokfoering.
Til tross for at dette er en spørring og ikke en mutasjon, kjører den hovedbokberegningen på nytt for å gjenskape bunten — akkurat som beregning=Tidligere gjorde i FSWS-Hovedbok. Den er derfor tyngre enn en vanlig spørring og bør ikke kalles i en løkke eller parallelt for mange bunter samtidig. Den endrer ikke data i FS.
Parameteroversikt
| FSWS-Hovedbok (REST) | FS GraphQL API |
|---|---|
beregning=Tidligere | (ingen — valget er selve spørringsnavnet) |
buntnr (format F + yyyyMMdd, f.eks. F20220401) | input.buntnummer (samme verdi) |
| (implisitt fra innlogget bruker) | input.eierOrganisasjonskode |
Eksempel
query HentTidligereHovedbokfoering {
tidligereHovedbokfoering(
input: {
eierOrganisasjonskode: "1234"
buntnummer: "F20220401"
}
) {
buntnummer
antallrader
sumposbelop
sumnegbelop
bilagListe {
bilagsnummer
dato
tekst
belop
kdim0
kdim1
kdim5
}
}
}
{
"data": {
"tidligereHovedbokfoering": {
"buntnummer": "F20220401",
"antallrader": 3,
"sumposbelop": 15000,
"sumnegbelop": 15000,
"bilagListe": [
{
"bilagsnummer": "1",
"dato": "2022-03-28",
"tekst": "Semesteravgift",
"belop": "5000",
"kdim0": "3400",
"kdim1": null,
"kdim5": "100"
},
{
"bilagsnummer": "2",
"dato": "2022-03-30",
"tekst": "Semesteravgift",
"belop": "10000",
"kdim0": "3400",
"kdim1": null,
"kdim5": "200"
},
{
"bilagsnummer": "3",
"dato": "2022-04-01",
"tekst": "Semesteravgift",
"belop": "-15000",
"kdim0": "1500",
"kdim1": null,
"kdim5": null
}
]
}
}
}
Feltnavn i svaret
Feltene er de samme som i FSWS-Hovedbok, men flere har fått nytt navn:
Kjør ny hovedbokføring
Kontraktsnivå: beta
I FSWS-Hovedbok kjørte du en ny beregning med beregning=Ny, dato og oppdaterFS. I FS GraphQL API bruker du mutasjonen overfoerTilHovedbok.
oppdater: true bokfører på ekteoppdater: true merker innbetalingene i utplukket som bokført i FS, på samme måte som oppdaterFS=J gjorde. Det kan ikke angres fra API-et. Bruk oppdater: false når du bare vil se hva et utplukk ville gitt.
Parameteroversikt
| FSWS-Hovedbok (REST) | FS GraphQL API |
|---|---|
beregning=Ny | (ingen — valget er selve mutasjonsnavnet) |
dato (format yyyyMMdd) | input.dato (Date, ISO 8601, f.eks. 2022-04-01) |
oppdaterFS (J/N) | input.oppdater (true/false) |
buntnr | (finnes ikke — buntnummeret genereres og returneres i svaret) |
| (implisitt fra innlogget bruker) | input.eierOrganisasjonskode |
Eksempel
mutation KjoerNyHovedbokfoering {
overfoerTilHovedbok(
input: {
eierOrganisasjonskode: "1234"
dato: "2022-04-01"
oppdater: true
}
) {
buntnummer
antallrader
sumposbelop
sumnegbelop
bilagListe {
bilagsnummer
dato
tekst
belop
kdim0
kdim1
kdim5
}
}
}
{
"data": {
"overfoerTilHovedbok": {
"buntnummer": "F20220401",
"antallrader": 2,
"sumposbelop": 8000,
"sumnegbelop": 8000,
"bilagListe": [
{
"bilagsnummer": "1",
"dato": "2022-03-29",
"tekst": "Semesteravgift",
"belop": "8000",
"kdim0": "3400",
"kdim1": null,
"kdim5": "100"
},
{
"bilagsnummer": "2",
"dato": "2022-03-29",
"tekst": "Semesteravgift",
"belop": "-8000",
"kdim0": "1500",
"kdim1": null,
"kdim5": null
}
]
}
}
}
overfoerTilHovedbok returnerer HovedbokBunt direkte og har ingen errors-blokk på selve mutasjonssvaret — den følger altså ikke ...Payload { errors }-mønsteret beskrevet under Mutasjoner. Feil (for eksempel manglende HOVEDBOK-rolle) kommer i stedet som en feil på toppnivå i svaret.
Viktige forskjeller
Hva om mitt behov ikke er dekket?
Ta kontakt med fs-support@sikt.no og beskriv behovet.