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

Person

Feld Datenquelle Typ Beschreibung
svid Person.Guid string Eindeutige UUID der Person
nestid NestId integer Interne Referenz-ID
sgid Person.Gebiete.Code integer ID der zugehörigen Schuleinheit
typCd PersonMappingProfileFilter enum siehe TypCode
sexCd GeschlechtCode enum siehe SexCode
anredeCd Anrede enum siehe AnredeCode
name Nachname string Nachname der Person
vorname Vorname string Vorname der Person
gebDat Geburtsdatum datetime Format: YYYY-MM-DDT00:00:00
ahv AHV-Nummer string Format: 756.XXXX.XXXX.XX
adresse Adressdaten string Kombinierte Adressfelder: Strasse, Hausnummer, PLZ, Ort
plzFk PLZ long Fremdschlüssel auf PLZ-Datensatz
eMailGeschaeft GeschaeftlicheEmail string Geschäftliche E-Mail-Adresse
eMailPrivat PrivateEmail string Private E-Mail-Adresse
telGeschaeft GeschaeftlicheTelefon string Geschäftliche Telefonnummer
telPrivat PrivateTelefon string Private Telefonnummer
gueltigVon GueltigVon datetime Startdatum der Gültigkeit
gueltigBis GueltigBis datetime Enddatum der Gültigkeit
gv1Fk Erziehungsberechtigter1 string ID der ersten Bezugsperson (0 wenn keine)
gv2Fk Erziehungsberechtigter2 string ID der zweiten Bezugsperson (0 wenn keine)
voiceEnabled VoiceEnabled boolean Flag für Voice-Aktivierung

PKS

Feld Datenquelle Typ Beschreibung
svid Person.Guid string Eindeutige UUID der Person
schuleinheitId Schuleinheit.Guid string ID der Schuleinheit
schuljahrId Schuljahr.Guid string ID des Schuljahres
semesterId Semester.Guid string ID des Semesters
klasseId Schulklassendossier.Guid string ID der Hauptklasse
klassenplanId KlassenPlan.Guid string ID des Klassenplans (kann null sein)
teilklasseId Teilklasse.Guid string ID der Teilklasse
teilklassenplanId TeilklassenPlan.Guid string ID des Teilklassenplans (kann null sein)
von Zuteilung.GueltigVon datetime Startdatum der Klassenzuteilung (Format: YYYY-MM-DDT00:00:00)
bis Zuteilung.GueltigBis datetime Enddatum der Klassenzuteilung (Format: YYYY-MM-DDT00:00:00)

Schulklassen

Feld Datenquelle Typ Beschreibung
svid Person.Guid string Eindeutige UUID der Person
schuleinheitId Schuleinheit.Guid string ID der Schuleinheit
stufe Teilklasse.Klassenlehrplan enum siehe LevelCode Schuleinheit
schuljahrId Schuljahr.Guid string ID des Schuljahres
semesterId Semester.Guid string ID des Semesters
klasseId Klasse.Guid string ID der Hauptklasse
klassenplanId KlassenPlan.Guid string ID des Klassenplans (kann null sein)
teilklasseId Teilklasse.Guid string ID der Teilklasse
teilklassenplanId TeilklassenPlan.Guid string ID des Teilklassenplans (kann null sein)
von Zuteilung.GueltigVon datetime Startdatum der Klassenzuteilung (Format: YYYY-MM-DDT00:00:00)
bis Zuteilung.GueltigBis datetime Enddatum der Klassenzuteilung (Format: YYYY-MM-DDT00:00:00)

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