Rapporter — Dokumentation

Alla rapportfunktioner finns tillgängliga via REST-API. Autentisering sker med API-nyckel i headern X-API-Key.

Endpoints:

// Rapportjobb:
POST   /api/pro/reports/jobs                   Skapa rapport (asynkront)
GET    /api/pro/reports/jobs                   Lista rapporter (?limit=1-100, standard 20)
GET    /api/pro/reports/jobs/{jobId}            Hämta status + nedladdningslänk

// Delning:
POST   /api/pro/reports/jobs/{jobId}/share      Skapa delningslänk
DELETE /api/pro/reports/jobs/{jobId}/share      Återkalla delningslänk
GET    /api/pro/reports/share/{jobId}           Publik nedladdning (org + token som query params)

// Schemaläggning:
POST   /api/pro/reports/schedules              Skapa schema
GET    /api/pro/reports/schedules              Lista scheman (max 20)
PATCH  /api/pro/reports/schedules/{id}         Uppdatera (enabled, frequency)
DELETE /api/pro/reports/schedules/{id}         Ta bort schema

Exempel: Skapa rapporter

// Skolprofil med rikssnitt och tidsfönster:
POST /api/pro/reports/jobs
{
  "reportType": "skolprofil",
  "schoolCode": "12345678",
  "comparisonLevel": "national",
  "kpis": ["meritRating9", "eligibleYR9", "certifiedTeachersPercent"],
  "fromYear": 2020,
  "toYear": 2025
}
→ 202 { "jobId": "abc", "status": "queued", "reportType": "skolprofil" }

// Trendrapport — jämför tre skolor:
POST /api/pro/reports/jobs
{
  "reportType": "trendrapport",
  "schoolCodes": ["12345678", "23456789", "34567890"],
  "kpis": ["meritRating9", "eligibleYR9"],
  "title": "Jämförelse grundskolor Lund",
  "fromYear": 2019
}
→ 202 { "jobId": "def", "status": "queued", "reportType": "trendrapport" }

// Polla status:
GET /api/pro/reports/jobs/{jobId}
→ { "status": "done", "result": { "downloadUrl": "https://...", "fileName": "skolkoll-skolprofil-12345678-2026-03-18T09-15-42.pdf", "sizeBytes": 184320, "expiresAt": "2026-03-18T10:15:42Z" } }

Exempel: Schemaläggning

// Skapa schema — månadsvis kommunöversikt:
POST /api/pro/reports/schedules
{
  "reportType": "kommunoversikt",
  "municipalityCode": "0180",
  "frequency": "monthly"
}
→ 201 { "id": "abc", "enabled": true, "frequency": "monthly", "spec": {...} }

// Lista alla scheman:
GET /api/pro/reports/schedules

// Pausa/byta frekvens:
PATCH /api/pro/reports/schedules/{id}
{ "enabled": false }

// Ta bort:
DELETE /api/pro/reports/schedules/{id}
→ { "ok": true }

Exempel: Dela rapport

// Skapa delningslänk (30 dagar):
POST /api/pro/reports/jobs/{jobId}/share
{ "expiryDays": 30 }
→ { "shareUrl": "/api/pro/reports/share/{jobId}?org=X&token=abc...", "expiresAt": "2026-04-17T...", "expiryDays": 30 }

// Återkalla delningslänk:
DELETE /api/pro/reports/jobs/{jobId}/share
→ { "ok": true }

// Publik nedladdning (ingen autentisering):
GET /api/pro/reports/share/{jobId}?org=X&token=abc...
→ 302 redirect till signerad PDF-URL

Tillgängliga KPI-nycklar:

Nyckel	Beskrivning	Enhet
meritRating9	Meritvärde åk 9	poäng
certifiedTeachersPercent	Behöriga lärare	%
studentsPerTeacher	Elever per lärare	antal
totalPupils	Antal elever	antal
eligibleYR9	Behörighet gymnasiet åk 9	%
allSubjectsPassed6	Godkänd alla ämnen åk 6	%
allSubjectsPassed9	Godkänd alla ämnen åk 9	%
npSVE9	Nationellt prov svenska åk 9	poäng
npMA9	Nationellt prov matematik åk 9	poäng
npENG9	Nationellt prov engelska åk 9	poäng
examWithin3Years	Gymnasieexamen inom 3 år	%
eligibleHigherEd	Behörighet till högskola	%

Parametrar:

Parameter	Gäller	Beskrivning
reportType	Alla	Obligatorisk: skolprofil, kommunoversikt, huvudmannarapport, trendrapport
schoolCode	Skolprofil	Skolenhetskod (8 siffror)
municipalityCode	Kommunöversikt	Kommunkod (4 siffror)
organizerOrgNr	Huvudmannarapport	Organisationsnummer
schoolCodes[]	Trendrapport	Lista skolenhetskoder (max 20)
municipalityCodes[]	Trendrapport	Lista kommunkoder (max 20)
kpis[]	Alla	Obligatorisk för trendrapport. Valfri för övriga. Max 10 st.
fromYear / toYear	Alla	Startår/slutår för trenddata (heltal 2000-2100)
comparisonLevel	Skolprofil	"municipality" (standard) eller "national"
title	Trendrapport	Valfri rubrik, max 200 tecken
frequency	Scheman	weekly, monthly eller quarterly
expiryDays	Delning	1-90 dagar, standard 30

Detaljer:

Jobbstatus: queued → processing → done | failed. Vid done inkluderas result med downloadUrl, fileName, sizeBytes, storagePath och expiresAt. Nedladdningslänken förnyas vid varje anrop (1 timmes giltighet).

Delning: Token genereras med 32 bytes crypto randomBytes. Publik nedladdning (GET /share/:jobId) kräver org och token som query-parametrar. Utgångna delningslänkar returnerar 410 Gone.

Felkoder:

Kod	Betydelse
400	Valideringsfel — saknad identifierare, ogiltigt reportType, fromYear > toYear, kpis[] saknas (trendrapport), max 10 KPIs överskridet, max 20 enheter överskridet, max 10 scheman överskridet
403	Saknar rapporter-behörighet eller rapporter-tjänsten inte aktiv. Ogiltig share-token.
404	Jobb/schema hittades inte, organisation saknas, ingen delningslänk existerar
410	Delningslänk har gått ut eller rapportfilen har raderats (90-dagars retention)

Begränsningar:

• Max 20 enheter per trendrapport
• Max 10 KPI:er per rapport
• Max 10 scheman per organisation
• 90 dagars retention — genererade PDF:er sparas i 90 dagar
• Nedladdningslänkar har 1 timmes giltighet och förnyas automatiskt
• Delningslänkar: max 90 dagars utgång, standard 30 dagar
• Benchmark-PDF:er skapas via Benchmark-export, inte via rapporternas API