JSON- und Webservice-Import (Erweitert)

Zusätzlich zum CSV-Import kannst du Registrierungen auch per JSON-Datei oder direkt per Webservice (einer API-URL, die deine Daten automatisch liefert) importieren. Alle drei Quellen — CSV, JSON und Webservice — laufen durch denselben 6-Schritt-Assistenten.

🟣 Nur Veranstalter

Basis-Workflow ist bereits dokumentiert

Die Grundlagen des Assistenten — Feld-Zuordnung, Pflichtfelder, Wert-Zuordnung für Geschlecht, Gewichtsklassen-Zuordnung und die Vorschau — sind ausführlich auf der Seite CSV-Import beschrieben. Diese Seite hier ergänzt gezielt das, was beim JSON-Datei-Import und beim Import via Webservice (API-URL) anders läuft oder zusätzlich zu beachten ist.

Voraussetzungen

• Dein Turnier muss im Status Anmeldung sein.
• Mindestens eine Klassenzuordnung muss angelegt sein — ohne Wettkampfklassen bricht der Assistent mit dem Hinweis „Es sind keine Wettkampfklassen für dieses Turnier angelegt" ab.

Einstieg: Zwei Quellen im selben Dialog

Öffne in den Registrierungen deines Turniers den Button Importieren. Im ersten Schritt Konfiguration wählst du oben zwischen zwei Tabs:

• API URL — für den Import via Webservice
• Datei hochladen — für JSON- (und CSV-/Excel-)Dateien

JSON-Datei hochladen

1. Wechsle zum Tab Datei hochladen.
2. Ziehe deine .json-Datei per Drag & Drop in die markierte Fläche oder klicke darauf, um sie auszuwählen. Maximale Dateigröße: 10 MB.
3. Die Datei wird automatisch geparst — Feld-Erkennung und Wettkampfklassen werden im Anschluss automatisch geladen.

🔧 Erweitert: Erwartetes JSON-Format

Deine Datei muss eines von zwei Formaten haben:

• Ein reines Array von Objekten:

  [
    { "firstName": "Max", "lastName": "Mustermann", "...": "..." },
    { "firstName": "Maria", "lastName": "Musterfrau", "...": "..." }
  ]

• Ein Objekt mit einer Eigenschaft registrations, die ein Array enthält:

  { "registrations": [ { "firstName": "Max", "...": "..." } ] }

Jedes andere Format (z. B. ein einzelnes Objekt ohne registrations-Eigenschaft) führt zum Fehler „JSON muss ein Array von Registrierungen enthalten".

Ein Vorteil gegenüber CSV: Zahlen, Kommazahlen und Wahrheitswerte (true/false) bleiben in JSON als eigener Datentyp erhalten. Beim CSV-Import muss die Software Zahl/Text/Boolean erst aus reinem Text erraten — bei JSON entfällt dieser Schritt.

Über den Link JSON-Vorlage unterhalb der Upload-Fläche kannst du eine Beispieldatei mit zwei Musterdatensätzen herunterladen:

[
  {
    "firstName": "Max",
    "lastName": "Mustermann",
    "yearOfBirth": 2005,
    "gender": "m",
    "classId": "-60",
    "clubName": "JC Beispielstadt",
    "countryCodeIOC": "GER",
    "externalId": "",
    "hasPaid": false,
    "wasWeighed": false,
    "actualWeight": null
  },
  {
    "firstName": "Maria",
    "lastName": "Musterfrau",
    "yearOfBirth": 2006,
    "gender": "f",
    "classId": "-48",
    "clubName": "JC Beispielstadt",
    "countryCodeIOC": "GER",
    "externalId": "",
    "hasPaid": false,
    "wasWeighed": false,
    "actualWeight": null
  }
]

Tipp

Die Feldnamen in deiner eigenen Datei müssen nicht mit der Vorlage übereinstimmen — du ordnest sie im Schritt Feld-Mapping frei den Systemfeldern zu (siehe CSV-Import).

Import via Webservice (API-URL)

1. Wechsle zum Tab API URL.
2. Trage in das Feld API-URL die Adresse deines Webservices ein, z. B. https://api.beispiel.de/registrierungen.
3. Drücke Enter oder verlasse das Feld (Tab) — die Daten werden automatisch abgerufen.

Nach erfolgreichem Laden zeigt eine grüne Info-Box „X Datensätze geladen" und „Y Felder erkannt" an. Schlägt der Abruf fehl, erscheint ein rotes Fehlerbanner mit der HTTP-Fehlermeldung.

🔧 Erweitert: Erwartetes Antwortformat des Webservice

Wichtiger Unterschied zum Datei-Upload: Antwortet dein Webservice mit einem JSON-Array, wird jedes Element wie bei der Datei als ein Datensatz behandelt. Antwortet er dagegen mit einem einzelnen JSON-Objekt (kein Array), wird dieses eine Objekt als ein einzelner Datensatz interpretiert.

Anders als beim Datei-Upload gibt es beim Webservice keine automatische Erkennung einer umschließenden registrations-Eigenschaft. Liefert dein Endpunkt also { "registrations": [...] } zurück, entsteht daraus nur ein einziger (fehlerhafter) Datensatz mit dem wörtlichen Feld registrations statt der eigentlichen Liste. Achte deshalb darauf, dass dein Webservice direkt ein Array von Registrierungen zurückgibt — ohne umschließendes Objekt.

🔧 Erweitert: Erreichbarkeit des Webservice

Der Abruf erfolgt direkt aus dem Browser heraus als einfacher GET-Request auf die angegebene URL. Daraus ergeben sich zwei praktische Einschränkungen:

• CORS: Dein Webservice muss Anfragen von der Domain der Turniersoftware erlauben (entsprechende CORS-Header setzen), sonst blockiert der Browser die Antwort.
• Keine Authentifizierung: Es gibt aktuell kein Eingabefeld für API-Key, Bearer-Token oder Basic-Auth-Zugangsdaten. Dein Endpunkt muss also ohne Login öffentlich (oder z. B. über eine geheime, schwer zu erratende URL) erreichbar sein.

Automatische Feld-Erkennung

Sowohl bei der JSON-Datei als auch beim Webservice schlägt das System die Feld-Zuordnung im Schritt Feld-Mapping automatisch vor, indem es die erkannten Feldnamen gegen typische Muster prüft:

Systemfeld	Erkennt automatisch z. B.
Vorname	firstName, first_name, vorname, givenName
Nachname	lastName, surname, nachname, name
Geburtsjahr	birth, dob, geburt, jahrgang — bei erkanntem Datumsformat wird zusätzlich automatisch der Parser „Datum → Jahr" aktiviert
Geschlecht	gender, geschlecht, sex, m/w
Klasse	class, klasse, gewicht, weight, category (nicht, wenn „Altersklasse" gemeint ist)
Verein	club, verein, team
Land (IOC)	country, land, nation, ioc
Verband	association, verband, federation
Externe ID	externalId, barcode, scannerId, lfd.Nr
Ist-Gewicht	actualWeight, körpergewicht, realWeight
Gewogen	weigh…, gewogen, weighted
Bezahlt	paid, bezahlt, payment
Gürtelfarbe	obi, belt, gürtel, gurtfarbe

Findet keine der Regeln eine passende Spalte, greift zusätzlich ein einfacher Fallback, der Feldnamen sucht, die den Systemfeldnamen als Teilstring enthalten. Geprüfte Vorschläge kannst du in der Tabelle jederzeit manuell überschreiben.

🔧 Erweitert: Verschachtelte Felder (nur JSON/API)

Anders als beim flachen CSV-Format können JSON-Daten aus einer Datei oder einem Webservice verschachtelt sein, z. B.:

{ "athlete": { "firstName": "Max" }, "club": { "name": "JC Beispielstadt" } }

Solche Unterfelder werden automatisch aufgelöst und erscheinen im Feld-Mapping in Punktschreibweise, z. B. athlete.firstName oder club.name. Du wählst sie dort ganz normal wie jedes andere erkannte Feld aus.

Konstante hinzufügen

Falls ein Pflichtfeld in deinen Daten gar nicht als eigene Spalte existiert, aber für alle Datensätze denselben festen Wert hat (z. B. weil die Datei nur männliche Athleten enthält oder alle aus demselben Verein kommen), musst du die Spalte nicht künstlich ergänzen:

1. Klicke im Schritt Feld-Mapping unterhalb der Tabelle auf Konstante hinzufügen.
2. Wähle das betroffene Systemfeld aus dem Dropdown.
3. Trage den festen Wert ein, der für jeden importierten Datensatz gelten soll.

Ein Pflichtfeld gilt als erfüllt, sobald es entweder über das Feld-Mapping oder über eine Konstante gesetzt ist.

Auswirkung auf das Klassen-Mapping

Ob du Geschlecht und Altersklasse als Spalte zuordnest oder als Konstante festlegst, bestimmt direkt, wie die Klassen-Zuordnung in Schritt 4 aussieht — siehe nächster Abschnitt.

Wert- und Klassen-Mapping passen sich automatisch an

🔧 Erweitert: Warum die Klassen-Zuordnung mal eine, mal mehrere Tabellen zeigt

Der Assistent erkennt automatisch, ob Geschlecht und/oder Altersklasse als Spalte gemappt oder als Konstante gesetzt wurden, und wählt danach eine von vier Darstellungen für Schritt 4 (Klassen-Mapping):

Geschlecht	Altersklasse	Darstellung
Konstante	Konstante	Einfaches Mapping — eine Tabelle mit allen vorkommenden Gewichtswerten
Spalte gemappt	Konstante	Geschlechter-gruppiert — je eine Tabelle pro erkanntem Geschlecht
Konstante	Spalte gemappt	Altersklassen-gruppiert — je eine Tabelle pro erkannter Altersklasse
Spalte gemappt	Spalte gemappt	Vollständig gruppiert — je eine Tabelle pro Kombination aus Geschlecht und Altersklasse

Diese Automatik gilt unabhängig davon, ob deine Daten aus einer JSON-Datei oder einem Webservice stammen. Bei „Geschlechter-gruppiert" und „Vollständig gruppiert" ordnet der vorgelagerte Schritt Wert-Mapping außerdem die in deinen Daten vorkommenden Rohwerte (z. B. "M", "male") den vier Systemwerten männlich/weiblich/divers/gemischt zu — mit automatischem Vorschlag, erkennbar am Badge „Automatisch vorgeschlagen".

Die erkannten Gewichtswerte werden dabei automatisch sortiert: negative Werte (z. B. „bis 60 kg") stehen vor positiven Werten (z. B. „über 90 kg"), jeweils aufsteigend nach Betrag.

Vorschau, Testen und Import (Schritt 5)

Nach dem Klassen-Mapping ruft der Assistent eine Backend-Vorschau ab und zeigt Kacheln mit Gesamt, Gültig und Fehler sowie eine Liste der ersten 20 Datensätze inklusive Validierungsstatus (grün/rot) und, bei Fehlern, der konkreten Validierungsfehlermeldung. Über Alle X Datensätze anzeigen lässt sich die komplette Liste einblenden.

🔧 Erweitert: Test-Import (Simulation)

Der Button Test-Import (Simulation) führt den kompletten Import inklusive Anlegen der Registrierungen versuchsweise aus — in einer Datenbank-Transaktion, die am Ende automatisch zurückgerollt wird. Es wird also nichts dauerhaft gespeichert.

Dabei werden zusätzlich Duplikate erkannt und mit Badge markiert:

• Bereits registriert — der Athlet existiert bereits als Registrierung in der Datenbank.
• Duplikat in Datei — derselbe Athlet kommt mehrfach in deiner Import-Quelle vor.

Bei mehrfachen Treffern wird standardmäßig automatisch nur der zweite (spätere) Treffer zum Überspringen markiert — die Checkbox lässt sich pro Eintrag einzeln wieder aktivieren oder deaktivieren.

Achtung bei sich ändernden Webservices

Beim Datei-Import werden übersprungene Zeilen client-seitig herausgefiltert, bevor der eigentliche Import startet. Beim Webservice-Import dagegen wird beim endgültigen Import nur die Liste der zu überspringenden Positionen an das Backend geschickt — das Backend ruft deine API-URL dafür erneut ab. Ändert sich die Reihenfolge oder der Inhalt der Antwort deines Webservices zwischen Vorschau/Test-Import und dem endgültigen Jetzt importieren, kann es passieren, dass die falschen Datensätze übersprungen werden. Nutze eine stabile, für den Import fest eingefrorene Quelle (z. B. einen Datenbank-Export zu einem festen Zeitpunkt statt einer sich laufend ändernden Live-Abfrage).

Mit Jetzt importieren wird der Import endgültig ausgeführt. Das anschließende Protokoll zeigt Kacheln für Erstellt, Duplikate und Fehler sowie bei Bedarf ein Fehlerprotokoll — identisch zum CSV-Import (siehe CSV-Import: Schritt 6).

Häufige Probleme

„JSON muss ein Array von Registrierungen enthalten"

Deine Datei enthält weder ein Array auf oberster Ebene noch ein Objekt mit einer registrations-Eigenschaft. Prüfe die Struktur gegen die JSON-Vorlage weiter oben.

Der Webservice liefert nur einen Datensatz statt einer Liste

Dein Endpunkt gibt vermutlich ein Objekt mit umschließender registrations-Eigenschaft zurück (z. B. { "registrations": [...] }). Das wird beim Webservice-Import — anders als bei der Datei — nicht automatisch erkannt. Passe deinen Endpunkt so an, dass er direkt ein Array zurückgibt.

Die API-URL lädt keine Daten / Fehlermeldung „Fehler beim Laden der API-Daten"

• Prüfe, ob die URL öffentlich (ohne Login) erreichbar ist — der Import unterstützt keine Authentifizierung.
• Prüfe, ob dein Webservice CORS-Anfragen von der Turniersoftware-Domain erlaubt.
• Prüfe die HTTP-Fehlermeldung im Banner (z. B. HTTP 404 oder HTTP 500) und kontrolliere Tippfehler in der URL.

Tipp

Teste einen neuen Webservice zuerst mit einer kleinen Testantwort (5–10 Datensätze), bevor du ihn für den echten Import einer großen Teilnehmerliste verwendest.

Weitere Informationen

• Grundlagen des Assistenten (Feld-Mapping, Wert-Mapping, Pflichtfelder): CSV-Import
• Zurück zur Phase 2: Anmeldung
• Klassen einrichten in Phase 1: Einrichtung