Skip to content

API Endpunkte

Für Entwicklerinformationen siehe EntwicklerInformationen Für Fehlerbehandlung siehe Fehlerbehandlung Für Testinformationen siehe Testing Für Konfigurationsdetails siehe Konfiguration

Gemeinsame Filterparameter

Die meisten Endpunkte (Export und AiAddress) akzeptieren Datumsfilter als Query-Parameter. Alle Datumsangaben verwenden das Schweizer Format dd.MM.yyyy.

Datumsformat-Varianten

Format Bedeutung Beispiel
dd.MM.yyyy Einzelnes Datum (Von = Bis) 01.01.2024
dd.MM.yyyy-dd.MM.yyyy Von-Bis-Zeitraum 01.01.2024-31.12.2024
dd.MM.yyyy- Ab Datum (offen nach oben) 01.01.2024-
-dd.MM.yyyy Bis Datum (offen nach unten) -31.12.2024

Verfügbare Filter

Parameter Verfügbar bei Beschreibung
Created personen, pks, schulklassen, schuljahre, aiaddress/* Erstellungszeitraum -- filtert auf das Beginn-Datum des Dossiers
Updated personen, pks, schulklassen, schuljahre, aiaddress/* Änderungszeitraum -- filtert auf Modifikationsdatum (siehe Tabelle unten)
Valid personen, pks, schulklassen, schuljahre, aiaddress/* Gültigkeitszeitraum
Expired personen, pks, schulklassen, aiaddress/addresses, aiaddress/contacts Ablaufzeitraum -- filtert auf das Ende-Datum des Dossiers

Updated-Filter: Worauf reagiert er je Endpunkt?

Der Updated-Filter prüft je nach Endpunkt auf unterschiedliche Objekte:

Endpunkt Updated prüft auf
/personen Person-Objekt, Dossier (Lernende/Personal), Adresse
/pks KlassenzuteilungLernende, KlassenzuteilungLehrperson
/schulklassen Schulklassendossier, Teilklasse
/schuljahre Schuljahr, Schuljahrperiode

Bei allen Endpunkten genügt es, wenn mindestens eines der aufgeführten Objekte im Updated-Zeitraum geändert wurde.

Implizite Gültigkeitsprüfung (Valid)

Wichtig: Jede Abfrage enthält immer eine Gültigkeitsprüfung. Wenn Valid nicht explizit angegeben wird, wird er aus den anderen Filtern abgeleitet:

Filter gesetzt Impliziter Valid-Zeitraum Betrifft Endpoints
Valid=X X (explizit) alle
nur Created=X = Created-Zeitraum pks, schuljahre, aiaddress/* ¹
nur Expired=Y = Expired-Zeitraum pks, aiaddress/addresses, aiaddress/contacts ¹
Created=X + Expired=Y {Von: X.Von, Bis: Y.Bis} pks, aiaddress/* ¹
nur Updated=X = heute (Stichtag) alle
keiner = heute (Stichtag) alle

¹ Ausnahme personen, schulklassen: Bei diesen Endpoints filtern Created und Expired direkt auf das Beginn- bzw. Ende-Datum des Dossiers — ohne eine implizite Gültigkeitsprüfung abzuleiten. Created erzeugt ausschliesslich eine Bedingung auf das Beginn-Datum, Expired ausschliesslich auf das Ende-Datum. Wird keine explizite Valid-Angabe gemacht und auch kein Created/Expired gesetzt, gilt der Default "heute gültig". Grund: Diese Endpoints arbeiten mit Beginn/Ende-Feldern der Dossiers, bei denen eine Vermischung von Created→Ende oder Expired→Beginn zu fehlerhaften Ergebnissen führen würde.

Hinweis zu Updated: Im Gegensatz zu Created und Expired beeinflusst Updated den impliziten Valid-Zeitraum nicht. Wird nur Updated ohne Valid angegeben, gilt die Gültigkeit per heute. Das bedeutet: Personen die im Updated-Zeitraum geändert wurden, aber deren Dossier inzwischen abgelaufen ist, werden nicht geliefert. Bei historischen Updated-Abfragen sollte deshalb zusätzlich Valid angegeben werden.

Standardverhalten (keine Filter gesetzt)

Wenn kein Filter angegeben wird, gilt Gültigkeit per heute: Es werden nur Datensätze geliefert, die am heutigen Datum gültig sind (Beginn <= heute UND (Ende >= heute ODER Ende leer)).

Validierungsregeln

  • Created darf nicht in der Zukunft liegen
  • Updated darf nicht in der Zukunft liegen
  • Bei Created + Expired: Created-Von darf nicht nach Expired-Von liegen
  • Bei Created + Updated: Created-Von darf nicht nach Updated-Von liegen
  • Bei allen Bereichen: Von-Datum darf nicht nach Bis-Datum liegen

Export API

1. Personen (/export/personen)

Beschreibung

Stellt Informationen über alle Personen im System bereit.

Request

Endpoint: GET /export/personen

Parameter
  • Created: Erstellungszeitraum (Dossier-Beginn), Format: dd.MM.yyyy(-dd.MM.yyyy)
  • Updated: Änderungszeitraum (Person-/Dossier-/Adress-Modifikationsdatum), Format: dd.MM.yyyy(-dd.MM.yyyy)
  • Valid: Gültigkeitszeitraum, Format: dd.MM.yyyy(-dd.MM.yyyy)
  • Expired: Ablaufzeitraum (Dossier-Ende), Format: dd.MM.yyyy(-dd.MM.yyyy)

Siehe Gemeinsame Filterparameter für Details zur Filterlogik.

Response

[
  {
    "svid": "4e8cbe720ff5455597a03e49e536bdca",
    "anredeCd": null,
    "sexCd": "Male",
    "typCd": "Custodian",
    "sgid": 7,
    "name": "Tester",
    "vorname": "Damian",
    "adresse": "REDACTED",
    "plzFk": 4218868136,
    "gebDat": "REDACTED",
    "ahv": "REDACTED",
    "eMailGeschaeft": "REDACTED",
    "eMailPrivat": null,
    "telPrivat": "REDACTED",
    "telGeschaeft": null,
    "gueltigVon": null,
    "gueltigBis": null,
    "gv1Fk": "0",
    "gv2Fk": "0",
    "nestid": 9999,
    "voiceEnabled": false
  },
  // weitere
]
Struktur
[
  {
    "nestid": "<integer>",
    "sexCd": "Male",
    "svid": "<string>",
    "typCd": "Staff",
    "anredeCd": 111,
    "sgid": "<integer>",
    "name": "<string>",
    "vorname": "<string>",
    "adresse": "<string>",
    "plzFk": "<long>",
    "gebDat": "<dateTime>",
    "ahv": "<string>",
    "eMailGeschaeft": "<string>",
    "eMailPrivat": "<string>",
    "telPrivat": "<string>",
    "telGeschaeft": "<string>",
    "gueltigVon": "<dateTime>",
    "gueltigBis": "<dateTime>",
    "gv1Fk": "<string>",
    "gv2Fk": "<string>",
    "voiceEnabled": "<boolean>"
  },
  {
    "nestid": "<integer>",
    "sexCd": "Male",
    "svid": "<string>",
    "typCd": "Teacher",
    "anredeCd": 112,
    "sgid": "<integer>",
    "name": "<string>",
    "vorname": "<string>",
    "adresse": "<string>",
    "plzFk": "<long>",
    "gebDat": "<dateTime>",
    "ahv": "<string>",
    "eMailGeschaeft": "<string>",
    "eMailPrivat": "<string>",
    "telPrivat": "<string>",
    "telGeschaeft": "<string>",
    "gueltigVon": "<dateTime>",
    "gueltigBis": "<dateTime>",
    "gv1Fk": "<string>",
    "gv2Fk": "<string>",
    "voiceEnabled": "<boolean>"
  }
]

Personentypen

  • Student (Lernende, TypCode 105)
  • Person mit aktivem Lernendedossier (Beginn/Ende im Gültigkeitszeitraum)

  • Kann mehreren Klassen gleichzeitig zugeordnet sein

  • Teacher (Lehrpersonen, TypCode 218)

  • Person mit aktivem Personaldossier, bei der mindestens eine (zeitlich relevante) Personalanstellung eine Anstellungsfunktion mit customIstLehrperson = true hat
  • Zeitliche Relevanz: Anstellung überlappt den abgefragten Gültigkeitszeitraum, oder (falls keine Anstellung am Stichtag aktiv ist) die nächste zukünftige Anstellung hat customIstLehrperson = true

  • Kann mehrere Anstellungen parallel haben, wird aber nur einmal als Teacher geliefert

  • Staff (Personal, TypCode 219)

  • Person mit aktivem Personaldossier, die nicht als Teacher qualifiziert ist

  • Dies umfasst: Personen ohne Anstellung, Personen mit Anstellung ohne customIstLehrperson, Verwaltungspersonal

  • Custodian (Bezugspersonen, TypCode 999)

  • Bezugsperson mit Sorgerecht eines gelieferten Schülers
  • Wird aus den Beziehungen der Schüler extrahiert (nicht direkt abgefragt)
  • Deduplizierung: Wenn eine Person bereits als Teacher oder Staff geliefert wird, erscheint sie nicht zusätzlich als Custodian. Die Zuordnung Student -> gesetzlicher Vertreter bleibt über gv1Fk/gv2Fk/gv3Fk am Student-Datensatz erhalten

Gemeinsame Felder

  • ID (GUID): Eindeutige, unveränderliche Identifikation der Person
  • Typ: Definiert die Rolle und verfügbaren Funktionen im System
  • Name, Vorname: Werden für Anzeige und Sortierung verwendet
  • Geburtsdatum: Wird für Altersberechnungen und Validierungen benötigt
  • AHV-Nummer: Schweizer Sozialversicherungsnummer, muss Format 756.XXXX.XXXX.XX entsprechen
  • CustomVoiceEnabled: Steuert Zugriff auf Voice-Funktionen in angrenzenden Systemen von BKO
  • SGID: Schulgemeinde-Id, steuert die Abrechnung in angrenzenden Systemen von BKO
  • Kontaktdaten: E-Mail und Telefon können jeweils geschäftlich und privat hinterlegt werden

Validierungsregeln

  • AHV-Nummern
  • Format muss exakt 756.XXXX.XXXX.XX entsprechen
  • Erste drei Stellen sind immer "756" (Schweizer Landeskennzeichen)

  • Prüfziffer wird nach Modulo-11 Verfahren validiert

  • Gebietszuordnung

  • Jede Person muss einer aktiven Schuleinheit zugeordnet sein
  • Gebietscode des Gebiets mit Gebietstyp "Schule" (Code 14) haben

  • Zeitliche Überlappungen von Gebietszuordnungen sind nicht erlaubt

  • Bezugspersonen

  • Maximal zwei aktive Hauptbezugspersonen pro Lernenden (gv1Fk, gv2Fk)
  • Bezugsperson kann nicht sich selbst als Bezugsperson haben

  • Keine zirkulären Bezugsperson-Beziehungen erlaubt

  • Systemvalidierungen

  • SGID muss auf existierende Schuleinheit verweisen
  • PLZ muss im PLZ-Verzeichnis existieren
  • Alle Datumswerte müssen im Format YYYY-MM-DDT00:00:00 vorliegen

Besonderheiten

Basierend auf der Code-Analyse beschreibe ich die wichtigsten Eigenschaften und speziellen Verhaltensweisen des /export/personen Endpunkts:

Typen-Behandlung (TypCode)

  • Eine Person kann in mehreren Gruppen erscheinen (z.B. als Student und als Custodian)
  • Teacher/Staff-Zuordnung basiert auf dem KPF-Feld customIstLehrperson auf der Anstellungsfunktion (Stammdaten)
  • Wenn eine Person als Teacher oder Staff qualifiziert ist, wird sie nicht zusätzlich als Custodian geliefert (Deduplizierung)
  • Mindestens eine Anstellung mit customIstLehrperson = true -> Teacher (keine Doppellieferung als Teacher + Staff)

Datums-Behandlung

  1. Gültigkeitszeiträume

  2. Unterschiedliche Quellen für Start-/Enddaten je nach Personentyp:

- Student: Verwendet Lernendedossier-Daten - Teacher: Verwendet Personaldossier-Daten - Staff: Verwendet Personaldossier-Daten - Custodian: Verwendet Beziehungs-Daten

  • Falls keine spezifischen Daten gefunden werden, wird das Erstellungsdatum der Person verwendet

  • Modified-Feld in der Response

  • Das Feld modified enthält das neueste Änderungsdatum aus Person-Objekt, Dossier(s) und Adresse(n)

  • Damit ist das Feld konsistent mit dem Updated-Filter, der ebenfalls auf alle drei Ebenen reagiert

Bezugspersonen-Behandlung

  • Jede Person kann bis zu drei Bezugspersonen haben (gv1Fk, gv2Fk, gv3Fk)
  • Sortierung: Rechnungsempfänger (KPF-Feld) -> Vater -> Mutter -> weitere
  • Wenn keine Bezugspersonen existieren, werden die Werte auf "0" gesetzt

Adress-Behandlung

  • Gibt nur die "Hauptadresse" zurück, wenn verfügbar
  • Adressformat: strasse + ", " + plz + " " + ort
  • Wenn keine Hauptadresse existiert, wird ein leerer String zurückgegeben

Geschlecht-Mapping

- Male: Für GeschlechtCode.MALE
- Female: Für GeschlechtCode.FEMALE
- Legal: Für GeschlechtCode.JURIDICAL_PERSON
- Undefined: Für alle anderen Fälle

Anrede-Mapping

- HERR: Für "herr" (Groß-/Kleinschreibung egal)
- FRAU: Für "frau" (Groß-/Kleinschreibung egal)
- FIRMA: Für "firma" (Groß-/Kleinschreibung egal)
- null: Für alle anderen Fälle

Schulgemeinde-ID

  • Versucht die ID aus Gebiete.Code zu parsen
  • Gibt 0 zurück, wenn das Parsen fehlschlägt oder kein Code existiert

NEST-ID-Behandlung

  • Parst aus Fremdkey-String
  • Gibt 0 zurück, wenn das Parsen fehlschlägt oder kein Fremdkey existiert

Personen-Filterung

  • Verwaltet eindeutige Personen mit GUID als Schlüssel
  • Verhindert Duplikate in der Antwort
  • Behandelt Beziehungs-Mapping für Lernende und deren Bezugspersonen

2. Personen-Klassen-Semester (/export/pks)

Beschreibung

Verwaltet die zeitliche Zuordnung von Personen zu Klassen.

Request

Endpoint: GET /export/pks

Parameter

Response

[
  {
    "svid": "b696f7b709914c63b97b97f31cb6adcc",
    "von": "2024-08-01T00:00:00",
    "bis": "2025-07-31T00:00:00",
    "schuleinheitId": "c534edee397c47ea8719097594d93e10",
    "schuljahrId": "25023823504e449a8fbf8794bb29e893",
    "semesterId": "119103a739944da1b5f17baec8b80c5b",
    "klasseId": "6a99381efcd94351a1dc96c1986e4179",
    "klassenplanId": "3552cbf5cd654c2d961fd96ad208c5df",
    "teilklasseId": "fa41094e90d8484ab7d1df4e4888bd18",
    "teilklassenplanId": "7459f4a8055d428397589183ca17ef68"
  },
  {
    "svid": "be5dca900e274341bdfcf9645bbcb315",
    "von": "2024-08-01T00:00:00",
    "bis": "2025-07-31T00:00:00",
    "schuleinheitId": "c534edee397c47ea8719097594d93e10",
    "schuljahrId": "25023823504e449a8fbf8794bb29e893",
    "semesterId": "119103a739944da1b5f17baec8b80c5b",
    "klasseId": "6a99381efcd94351a1dc96c1986e4179",
    "klassenplanId": "3552cbf5cd654c2d961fd96ad208c5df",
    "teilklasseId": "fa41094e90d8484ab7d1df4e4888bd18",
    "teilklassenplanId": "7459f4a8055d428397589183ca17ef68"
  }, 
  // weitere
]
Struktur
[
  {
    "klasseId": "<string>",
    "schuleinheitId": "<string>",
    "schuljahrId": "<string>",
    "semesterId": "<string>",
    "svid": "<string>",
    "teilklasseId": "<string>",
    "von": "<dateTime>",
    "bis": "<dateTime>",
    "klassenplanId": "<string>",
    "teilklassenplanId": "<string>"
  },
  {
    "klasseId": "<string>",
    "schuleinheitId": "<string>",
    "schuljahrId": "<string>",
    "semesterId": "<string>",
    "svid": "<string>",
    "teilklasseId": "<string>",
    "von": "<dateTime>",
    "bis": "<dateTime>",
    "klassenplanId": "<string>",
    "teilklassenplanId": "<string>"
  }
]

Besonderheiten

  • Schuljahrperioden → Semester → Schulklassen → Teilklassen → Personenzuteilungen
  • Jede Zuteilung hat einen definierten Gültigkeitszeitraum:
  • von: Startdatum der Zuteilung (Pflichtfeld)
  • bis: Enddatum der Zuteilung (optional)
    • Falls kein Startdatum vorhanden ist, wird DateTime.MinValue verwendet
  • Unterscheidet zwischen Klassenplan und Teilklassenplan:
  • klassenplanId: Identifiziert das Klassengefäss
  • teilklassenplanId: Identifiziert das Teilklassengefäss
  • Die Plan-IDs bleiben pro Stufe und Schulträger konstant
  • Unterstützt Mehrfachzuteilungen (eine Lehrperson kann mehreren Klassen zugeordnet sein)
  • Berücksichtigt Schuljahres- und Semesterwechsel
  • Ermöglicht die Abbildung von Klassenstrukturen mit mehreren Teilklassen
  • Validiert die Konsistenz zwischen Klassen- und Teilklassenplänen
Datenstruktur
  • Klassenzuordnung
  • Person-ID (GUID)
  • Klassen-ID (GUID)
  • Teilklassen-ID (GUID, optional)

  • Gültigkeitszeitraum (Von-Bis)

  • Semesterzuordnung

  • Schuljahr-ID
  • Semester-ID
  • Gültigkeitszeitraum
Validierungsregeln
  • Teilklassenplan ist Pflichtfeld
  • Gültige Zeiträume (keine Überlappungen)
  • Korrekte Schuljahres-/Semesterwechsel

3. Schulklassen (/export/schulklassen)

Beschreibung

Verwaltet die Schulklassenstruktur und deren Zuordnungen.

Request

Endpoint: GET /export/schulklassen

Parameter

Response

[
  {
    "schuleinheitId": "70890e3310bd4ed5bc8e5a937a984ff5",
    "schuleinheit": "Brülisau",
    "stufe": "Primary5",
    "klasseId": "330bce56c2f246c180d21aafc5aa41fa",
    "klasse": "Primarschule PS5, 2024/25, Brülisau",
    "klassenplanId": "f1abbc4ff75f4be98ebed99e6e04a7b4",
    "klassenplan": "Primarschule PS5, , Brülisau",
    "teilklasseId": "17736aee99874245aa6b99540280f3e1",
    "teilklasse": "PS5",
    "teilklassenplanId": "cdcf9844a3444c13a7dffe5d7636111b",
    "teilklassenplan": "PS5"
  },
  {
    "schuleinheitId": "70890e3310bd4ed5bc8e5a937a984ff5",
    "schuleinheit": "Brülisau",
    "stufe": "Kindergarten1",
    "klasseId": "44e7dc9f425f4394ab2fe0c5a45fe5df",
    "klasse": "Kindergarten KG1, 2024/25, Brülisau",
    "klassenplanId": null,
    "klassenplan": null,
    "teilklasseId": "924ae87734cb43e998dd00812873c900",
    "teilklasse": "KG1",
    "teilklassenplanId": null,
    "teilklassenplan": null
  }
]
Struktur
[
  {
    "klasse": "<string>",
    "klasseId": "<string>",
    "schuleinheit": "<string>",
    "schuleinheitId": "<string>",
    "stufe": "SmallClass3",
    "teilklasse": "<string>",
    "teilklasseId": "<string>",
    "klassenplanId": "<string>",
    "klassenplan": "<string>",
    "teilklassenplanId": "<string>",
    "teilklassenplan": "<string>"
  },
  {
    "klasse": "<string>",
    "klasseId": "<string>",
    "schuleinheit": "<string>",
    "schuleinheitId": "<string>",
    "stufe": "Gymnasium1",
    "teilklasse": "<string>",
    "teilklasseId": "<string>",
    "klassenplanId": "<string>",
    "klassenplan": "<string>",
    "teilklassenplanId": "<string>",
    "teilklassenplan": "<string>"
  }
]

Besonderheiten

  • Die Abfrage filtert auf das aktuelle Schuljahr wenn kein valid parameter angegeben wird
  • SchulklassenplanId identifiziert das Klassengefäss pro Stufe und bleibt pro Schulträger und Stufe immer dieselbe.
  • TeilklassenplanId identifiziert das Teilklassengefäss pro Klasse und bleibt pro Schulträger und Klasse immer dieselbe.
  • Schulklassen können mehrere Teilklassen haben
  • Jede Teilklasse hat einen eigenen Lehrplan mit Stufenzuordnung

Klassentypen

  • Regelklassen
  • Primarschule (PS1-PS6)
  • Sekundarschule (Sek1-Sek3)
  • Realschule (Real1-Real3)

  • Gymnasium (Gym1-Gym6)

  • Spezialklassen

  • ADL (Altersdurchmischtes Lernen)
  • Basisstufe (KG-2.Primar)

  • Kleinklassen (KK3-6)

  • Kindergarten

  • KG1
  • KG2

Validierungsregeln

  • Pflichtfeld Teilklassenplan
  • Korrekte Stufenzuordnung
  • Gültige Klassenstruktur

4. Schuljahre (/export/schuljahre)

Beschreibung

Verwaltet die zeitliche Struktur des Schulbetriebs.

Request

Endpoint: GET /export/schuljahre

Parameter

Response

[
  {
    "schuljahr": {
      "id": "25023823504e449a8fbf8794bb29e893",
      "bezeichnung": "2024/25",
      "von": "2024-08-01T00:00:00",
      "bis": "2025-07-31T00:00:00"
    },
    "semester": {
      "id": "8c666d8b8192461da620171e582a0060",
      "bezeichnung": "2. Semester",
      "von": "2025-02-01T00:00:00",
      "bis": "2025-07-31T00:00:00"
    }
  }
]
Struktur
[
  {
    "schuljahr": {
      "bezeichnung": "<string>",
      "bis": "<dateTime>",
      "id": "<string>",
      "von": "<dateTime>"
    },
    "semester": {
      "bezeichnung": "<string>",
      "bis": "<dateTime>",
      "id": "<string>",
      "von": "<dateTime>"
    }
  },
  {
    "schuljahr": {
      "bezeichnung": "<string>",
      "bis": "<dateTime>",
      "id": "<string>",
      "von": "<dateTime>"
    },
    "semester": {
      "bezeichnung": "<string>",
      "bis": "<dateTime>",
      "id": "<string>",
      "von": "<dateTime>"
    }
  }
]

Besonderheiten

  • Es werden immer alle Semester eines Schuljahres geliefert.
  • Semester: August bis Januar

  • Semester: Februar bis Juli

  • Die Bezeichnungen folgen dem Format:

  • Schuljahr: "2024/25"
  • Semester: "1. Semester", "2. Semester"

Datenstruktur

  • Schuljahr
  • ID
  • Bezeichnung

  • Gültigkeitszeitraum

  • Semester

  • ID
  • Bezeichnung

  • Gültigkeitszeitraum

  • Perioden

  • ID
  • Typ
  • Gültigkeitszeitraum

Validierungsregeln

  • Korrekte Schuljahreswechsel (31.07/01.08)
  • Korrekte Semesterwechsel (31.01/01.02)
  • Gültige Zeiträume

5. PLZ (/export/plz)

Beschreibung

Stellt das Ortschaftsverzeichnis für Adressdaten bereit.

Request

Endpoint: GET /export/plz

Parameter

Keine Filterparameter.

Response

[
  {
    "plzId": 1702358695,
    "plz": "(leer)",
    "ort": "(leer)",
    "kanton": "?",
    "land": "(leer)",
    "zusatzziffer": "(leer)"
  },
  {
    "plzId": 9749811271,
    "plz": "9108",
    "ort": "Gontenbad",
    "kanton": "AI",
    "land": "CH",
    "zusatzziffer": "02"
  },
  // weitere 
]
Struktur
[
  {
    "plz": "<string>",
    "plzId": "<long>",
    "ort": "<string>",
    "kanton": "<string>",
    "land": "<string>",
    "zusatzziffer": "<string>"
  },
  {
    "plz": "<string>",
    "plzId": "<long>",
    "ort": "<string>",
    "kanton": "<string>",
    "land": "<string>",
    "zusatzziffer": "<string>"
  }
]

Besonderheiten

  • Wenn keine Daten vorhanden sind, werden Standardwerte zurückgegeben:
  • Kanton: "?"
  • Ort: "(leer)"
  • Land: "(leer)"
  • PLZ: "(leer)"

  • Zusatzziffer: "(leer)"

  • Die plzId wird automatisch aus den Komponenten Ort, PLZ und Zusatzziffer generiert

  • Ländercodes werden im ISO 3166 ALPHA-2 Format zurückgegeben (z.B. "CH" für Schweiz)
  • Kantonskürzel sind zweistellig (z.B. "AI" für Appenzell Innerrhoden)

Datenstruktur

  • PLZ (4-stellig)
  • Ortsbezeichnung
  • Kantonskürzel (2-stellig)
  • Länderkennzeichen (2-stellig)

Validierungsregeln

  • Gültige PLZ-Formate
  • Korrekte Ländercodes
  • Eindeutige PLZ-IDs

AiAddress API

1. Personen (/aiaddress/persons)

  • Grundlegende Personendaten
  • CustomVoice-Konfiguration
  • Beziehungsinformationen

2. Adressen (/aiaddress/addresses)

  • Adressdaten (In-/Ausland)
  • PLZ-Validierung
  • Gültigkeitszeiträume

3. Kontakte (/aiaddress/contacts)

  • Kontakttypen
  • Kontaktdaten
  • Validierungsregeln

Integration API

1. Personen (/integration/persons)

  • Systemübergreifende Personendaten
  • Erweiterte Attribute
  • Beziehungsinformationen

2. Lernendedossiers (/integration/lernendedossiers)

  • Dokumentenverwaltung
  • Lernendendaten
  • Klassenzuordnungen

3. Schulklassendossiers (/integration/schulklassendossiers)

  • Klassendokumentation
  • Teilnehmerverwaltung
  • Periodenzuordnungen

Mapping der Felder

Die folgenden Tabellen dokumentieren pro Endpunkt, woher aus CMI jede exportierte Eigenschaft stammt.

Konventionen in der Spalte «Herkunft in CMI»:

  • TypDefinition.FeldKey -- Feld der genannten TypDefinition.
  • (System) -- technisches Basisfeld (guid, creationdate, modificationdate)
  • (KPF) -- Kundenprojektfeld

Person (/export/personen)

Basistyp Person (abstrakt). Die Datumsfelder stammen je nach Personentyp aus Lernendedossier/Personaldossier bzw. aus der Beziehung (Custodian).

Exportierte Eigenschaft Herkunft in CMI Hinweise
svid Person (System-Guid) string; eindeutige UUID der Person
anredeCd Person.Anrede (String -> Enum HERR/FRAU/FIRMA) enum; siehe AnredeCode
sexCd Person.Geschlecht -> Geschlecht.eCHCode enum; siehe SexCode
typCd Berechnet: Lernendedossier -> Student; Personaldossier mit Anstellungsfunktion.customIstLehrperson=true (KPF) -> Teacher, sonst Staff; aus Beziehung -> Custodian enum; siehe TypCode
sgid Person.Gebiete -> Gebiet.Code, nur Gebiet mit Gebiet.Gebietstyp -> Gebietstyp.Code=14 («Schule») integer; ID der zugehörigen Schuleinheit; int-parse, sonst 0
name Person.Name string; Nachname der Person
vorname Person.Vorname string; Vorname der Person
adresse Hauptadresse (Adresse mit Adresse.Adressart.Bezeichnung = «Hauptadresse») string; kombiniert als Strasse + Zeilenumbruch + PLZ + « » + Ort; leer, wenn keine Hauptadresse
plzFk Generiert aus der Hauptadresse (SHA256 über Ort+PLZ+Zusatzziffer) long; Fremdschlüssel auf PLZ-Datensatz, identisch zu plzId in /export/plz; 0 wenn keine Adresse
gebDat Person.Geburtsdatum datetime; Format YYYY-MM-DDT00:00:00
ahv Person.SozialversNr string; Format 756.XXXX.XXXX.XX
eMailGeschaeft Person.Email string; geschäftliche E-Mail; Modell-Anzeigename dieses Felds: «E-Mail Geschäft»
eMailPrivat Person.Email2 string; private E-Mail; Modell-Anzeigename dieses Felds: «E-Mail Privat»
telPrivat Person.TelefonPrivat string; private Telefonnummer
telGeschaeft Person.TelefonGeschaeft string; geschäftliche Telefonnummer
created Frühestes Beginn: Student -> Lernendedossier.Beginn; Teacher/Staff -> Personaldossier.Beginn; Custodian -> Beziehung.Dauer (von) datetime; Erstellungs-/Eintrittsdatum
gueltigVon Identisch zu created datetime; Startdatum der Gültigkeit
gueltigBis Spätestes Ende: Lernende-/Personaldossier.Ende bzw. Beziehung.Dauer (bis) datetime; Enddatum der Gültigkeit; offen, wenn ein Dossier kein Ende hat
modified Neuestes (System-modificationdate) aus Person, allen Dossiers und allen Adresse datetime; konsistent zum Updated-Filter
gv1Fk / gv2Fk / gv3Fk Person.BeziehungenA -> Beziehung.PersonB (System-Guid der Bezugsperson); sortiert nach customRechnungsempfaenger (KPF) -> Beziehungsart.IstVater -> Beziehungsart.IstMutter string; ID der 1./2./3. Bezugsperson; «0» wenn keine
nestid Person.Fremdkey (Teil nach =) integer; Personen-ID in NEST; int-parse, sonst 0
voiceEnabled customVoiceEnabled (KPF) auf Kontakt boolean; Flag für Voice-Aktivierung

PKS (/export/pks)

Struktur: Schuljahrperiode (deutscher Typname «Semester») -> Schuljahr -> Schulklassendossier -> Teilklasse -> KlassenzuteilungLernende/KlassenzuteilungLehrperson.

Exportierte Eigenschaft Herkunft in CMI Hinweise
svid Person (System-Guid) -- via KlassenzuteilungLernende.Schullaufbahn.Lernendedossier.Person, bzw. KlassenzuteilungLehrperson.Personalanstellung.Personaldossier.Person string; eindeutige UUID der Person
von KlassenzuteilungLernende.VonBis bzw. KlassenzuteilungLehrperson.VonBis (Feld-Key VonBis, Anzeigename «Dauer»), Start datetime; Startdatum der Zuteilung; DateTime.MinValue falls leer
bis dito, Ende der VonBis-Dauer datetime; Enddatum der Zuteilung (optional)
modified Klassenzuteilung… (System-modificationdate) datetime; Modifikationsdatum der Zuteilung
schuleinheitId Schulklassenplan.Schuleinheit (System-Guid) string
schuljahrId Schuljahr (System-Guid) string
semesterId Schuljahrperiode (System-Guid) string
klasseId Schulklassendossier (System-Guid) string; ID der Hauptklasse
klassenplanId Schulklassenplan (System-Guid) (via Schulklassendossier.Schulklassenplan) string; Klassenplan der Hauptklasse (analog /export/schulklassen)
teilklasseId Teilklasse (System-Guid) string
teilklassenplanId Teilklasse.Teilklassenplan (System-Guid) string; kann null sein

Schulklassen (/export/schulklassen)

Struktur: OrganisationseinheitSchule (Schuleinheit) -> Schulklassendossier -> Teilklasse.

Exportierte Eigenschaft Herkunft in CMI Hinweise
schuleinheitId Organisationseinheit (Schuleinheit) (System-Guid) string
schuleinheit Organisationseinheit.Name string; Bezeichnung der Schuleinheit
stufe Teilklasse.Klassenlehrplan -> Klassenlehrplan.Klassenstufe (Numeric) + Klassenlehrplan.Schulart -> Schulart.Kurzbezeichnung, umgesetzt via LevelCodeConverter enum; siehe LevelCode
klasseId Schulklassendossier (System-Guid) string; ID der Hauptklasse
klasse Schulklassendossier.Titel string; Bezeichnung der Klasse
klasseCreated Schulklassendossier (System-creationdate) datetime; Erstellungsdatum der Klasse
klasseFrom Schulklassendossier.Beginn datetime; Beginn der Klasse
klasseEnd Schulklassendossier.Ende datetime; Ende der Klasse
klasseModified Schulklassendossier (System-modificationdate) datetime; letzte Änderung der Klasse
klassenplanId Schulklassenplan (System-Guid) (via Teilklasse.Teilklassenplan -> Teilklassenplan.Schulklassenplan) string; kann null sein
klassenplan Schulklassenplan.Bezeichnung string; kann null sein
teilklasseId Teilklasse (System-Guid) string
teilklasse Teilklasse.Titel string; Bezeichnung der Teilklasse
teilklasseCreated Teilklasse (System-creationdate) datetime; Erstellungsdatum der Teilklasse
teilklasseModified Teilklasse (System-modificationdate) datetime; letzte Änderung der Teilklasse
teilklassenplanId Teilklassenplan (System-Guid) string; kann null sein
teilklassenplan Teilklassenplan.Bezeichnung string; kann null sein

Schuljahre (/export/schuljahre)

Struktur: Schuljahr + Schuljahrperiode. Der Typ Schuljahrperiode trägt den deutschen Anzeigenamen «Semester»; einen eigenen TypDefinition «Semester» gibt es nicht.

Exportierte Eigenschaft Herkunft in CMI Hinweise
schuljahr.id Schuljahr (System-Guid) string
schuljahr.bezeichnung Schuljahr.Bezeichnung string; z. B. «2024/25»
schuljahr.von Schuljahr.VonBis (Anzeigename «Dauer»), Start datetime; Beginn des Schuljahres
schuljahr.bis Schuljahr.VonBis, Ende datetime; Ende des Schuljahres
schuljahr.modified Schuljahr (System-modificationdate) datetime
semester.id Schuljahrperiode (System-Guid) string
semester.bezeichnung Schuljahrperiode.Bezeichnung string; z. B. «1. Semester», «2. Semester»
semester.von Schuljahrperiode.DauerVonBis (Anzeigename «Dauer»), Start datetime; Beginn des Semesters
semester.bis Schuljahrperiode.DauerVonBis, Ende datetime; Ende des Semesters
semester.modified Schuljahrperiode (System-modificationdate) datetime

PLZ (/export/plz)

Quelle: Adresse (in CMI erfasste Adressen), angereichert mit dem lokalen Ortsverzeichnis (CSV AMTOVZ_CSV_WGS84.csv).

Exportierte Eigenschaft Herkunft in CMI Hinweise
plzId Generiert: SHA256 über Ort+PLZ+Zusatzziffer long; 1 wenn alle Segmente leer; ein Leer-Eintrag steht immer an Position 0
plz Adresse.PLZ string; (leer) als Fallback
ort Adresse.Ort (Fallback: Ortsverzeichnis-CSV) string; (leer) als Fallback
kanton Lokales Ortsverzeichnis-CSV (nicht IMDA), aufgelöst über PLZ/Ort string; 2-stelliges Kürzel; ? als Fallback
land Adresse.Land -> Land.Kuerzel string; ISO 3166 ALPHA-2; (leer) als Fallback
zusatzziffer Lokales Ortsverzeichnis-CSV (nicht IMDA) string; (leer) als Fallback

TypCode

Mapping in PersonMappingProfileFilter:

  • Student: Wird für Lernende gesetzt
  • Teacher: Wird für Lehrpersonen gesetzt
  • Staff: Wird für Personalanstellungen gesetzt
  • Custodian: Wird für aktive Bezugspersonen gesetzt (nicht in der Vergangenheit liegende Beziehungen)

SexCode

Mapping in PersonResponseMapper:

  • Male: Wenn GeschlechtCode.MALE
  • Female: Wenn GeschlechtCode.FEMALE
  • Legal: Wenn GeschlechtCode.JURIDICAL_PERSON
  • Undefined: In allen anderen Fällen

AnredeCode

Mapping in PersonResponseMapper basierend auf String-Vergleich (case-insensitive):

  • Herr: Wenn Anrede "herr"
  • Frau: Wenn Anrede "frau"
  • Firma: Wenn Anrede "firma"
  • null: In allen anderen Fällen

LevelCode

Mapping in LevelCodeConverter basierend auf Schulart und Klassenstufe:

  • Primar (PS, Primar, Primarschule):
  • Stufen 1-6 -> Primary1 bis Primary6
  • Sekundar (Sek, Int OS, etc.):
  • Stufen 1-3,7-9 -> Secondary1 bis Secondary3
  • Gymnasium (Gym, G):
  • Stufen 1-6 -> Gymnasium1 bis Gymnasium6
  • Real (Real, R):
  • Stufen 1-3,7-9 -> Real1 bis Real3
  • Vorschule (VSK, KG etc.):
  • Stufen 1-2 -> Kindergarten1/2
  • Kleinklasse:
  • Stufen 1-9 -> SmallClass1 bis SmallClass9
    1. Schuljahr:
  • Stufe 250 -> Voluntary10
  • Privatschule:
  • Stufen 850,99,998 -> SpecialClass1
  • Fallback: Other

Performance-Anforderungen

Antwortzeiten

  • Personen API: < 5000ms
  • PKS API: < 5000ms
  • PLZ API: < 3000ms
  • Schuljahre API: < 100ms
  • Schulklassen API: < 200ms

Weitere Details