Export — Dokumentation

Exportfunktioner används via portalen och organisationens inloggade Firebase-session. Det här är interna Pro-endpoints för exporter, inte Skolkolls publika API-roadmap eller en API-nyckelprodukt.

Endpoints:

// Exportjobb:
POST   /api/pro/export/jobs                  Skapa export
         format (csv|xlsx|json, obligatoriskt)
         entityType (school|municipality, obligatoriskt)
         schoolCodes / municipalityCodes (valfritt, utelämna för alla)
         kpis (valfritt, array med KPI-nycklar)
         includeHistory (valfritt, bara school)
         compress (valfritt, tvinga ZIP)
GET    /api/pro/export/jobs                  Lista exporter
         ?limit=20                           Max antal (standard 20)
GET    /api/pro/export/jobs/{jobId}          Hämta enskilt jobb

// Schemaläggning:
POST   /api/pro/export/schedules             Skapa schema
         format, entityType, frequency (daily|weekly|monthly)
         kpis, includeHistory (valfria)
GET    /api/pro/export/schedules             Lista scheman
PATCH  /api/pro/export/schedules/{id}        Uppdatera (enabled, frequency etc.)
DELETE /api/pro/export/schedules/{id}        Ta bort schema

Svar från exportjobb följer kontraktet konto.first-value-output.v1. sampleRows är begränsade och kalkylbladssäkrade; emptyReason anges när urvalet ger 0 rader.

Exempel:

// Exportera utvalda skolor till Excel med historik:
POST /api/pro/export/jobs
{
  "format": "xlsx",
  "entityType": "school",
  "schoolCodes": ["12345678", "23456789"],
  "kpis": ["meritRating9", "totalPupils", "certifiedTeachersPercent"],
  "includeHistory": true,
  "compress": false
}
→ 201 {
    "jobId": "job_abc123",
    "status": "done",
    "downloadUrl": "https://storage.googleapis.com/...",
    "fileName": "skolkoll-school-2026-03-18.xlsx",
    "rowCount": 2,
    "schemaPreview": [{ "key": "skolenhetskod", "label": "Skolenhetskod", "nullCount": 0 }],
    "sampleRows": [{ "skolenhetskod": "12345678", "namn": "Exempelskolan" }],
    "emptyReason": null,
    "dataVersion": "2026-03-18"
  }

// Exportera kommundata till CSV:
POST /api/pro/export/jobs
{
  "format": "csv",
  "entityType": "municipality",
  "municipalityCodes": ["0180", "0580", "1480"],
  "kpis": ["meritvardeSnitt", "kostnadPerElev"]
}
→ 201 {
    "jobId": "job_def456",
    "status": "done",
	    "downloadUrl": "https://storage.googleapis.com/...",
	    "fileName": "skolkoll-municipality-2026-03-18.csv",
	    "rowCount": 3,
	    "schemaPreview": [{ "key": "kommunKod", "label": "Kommunkod", "nullCount": 0 }],
	    "sampleRows": [{ "kommunKod": "0180", "kommun": "Stockholm" }],
	    "emptyReason": null,
	    "dataVersion": "2026-03-18",
	    "summary": { "coverage": { "status": "complete", "rowCount": 3 } }
	  }

// Schemalägg veckovis export:
POST /api/pro/export/schedules
{
  "format": "csv",
  "entityType": "school",
  "frequency": "weekly",
  "kpis": ["meritRating9", "totalPupils"],
  "includeHistory": true
}
→ 201 { "id": "sched_abc", "enabled": true, "frequency": "weekly", "nextRunAt": "2026-03-24T02:00:00Z" }

// Lista/pausa/ta bort scheman:
GET /api/pro/export/schedules
PATCH /api/pro/export/schedules/sched_abc
{ "enabled": false }
DELETE /api/pro/export/schedules/sched_abc
→ 200 { "ok": true }

Detaljer:

Jobbstatus: queued → processing → done (eller failed). Klara jobb inkluderar downloadUrl, fileName och fileSize.

Obs: municipalityCodes måste vara 4-siffriga strängar (t.ex. "0180", inte 180).

Webhook: Avslutade exporter triggar en export.completed webhook med jobId, downloadUrl, fileName och fileSize. Webhooks aktiveras per organisation efter separat Pro-konfiguration.

Dataretention: Exporterade filer sparas i 90 dagar. Nedladdningslänkar förnyas vid varje listanrop (1 timmes giltighet).

Max: 10 scheman per organisation, 100 jobb per dygn.

Felkoder: 400 (valideringsfel, t.ex. ogiltigt format eller saknad entityType), 403 (saknar export-behörighet), 404 (jobb/schema hittades inte), 429 (daglig gräns nådd).