Für Ligen und Verbände

Verbands-API

Die öffentliche Schnittstelle, mit der Ligen und Verbände Spielpläne in Team Manager einspeisen und den Planungsstand ihrer Mannschaften abrufen. Ergebnisse, Tabellen und Statistiken gehören ausdrücklich nicht dazu.

openapi.json Zurück zur Übersicht

Grundlagen

Basis-URL: https://teammanagerapp.de/api/v1/league
Authentifizierung: Authorization: Bearer tma_live_…
Content-Type: application/json
Zeichensatz: UTF-8
Zeitangaben: UTC, ISO 8601 — reine Daten als YYYY-MM-DD
Version: v1 · jede Antwort trägt X-League-Api-Version

Jeder API-Key gehört zu genau einem Verband; sämtliche Endpunkte arbeiten ausschließlich auf dessen Daten. Keys legt der Verbandsadmin in der Verbandskonsole unter Einstellungen an. Sandbox-Verbände verwenden Keys mit dem Präfix tma_sbx_; ein vertauschter Key wird abgewiesen, statt still Daten zu verschieben.

Tragende Regeln

Idempotenz. Alle schreibenden Endpunkte sind Upserts über externalId — eurer ID für das jeweilige Objekt. Ein wiederholter Aufruf mit denselben Daten ändert nichts. Die IDs müssen pro Verband über alle Saisons hinweg eindeutig sein; trifft ein Upsert auf einen Datensatz aus einer anderen Saison, antwortet die API mit 409 und schreibt nichts. Wer Spielplan-IDs pro Saison neu vergibt, stellt ihnen die Saison voran, etwa 2026-27/F-0421.

Teilweiser Erfolg. Bulk-Endpunkte validieren jeden Datensatz einzeln und melden ihn einzeln. Der Status ist 200 bei vollem Erfolg und 207, sobald mindestens ein Datensatz fehlgeschlagen ist.

Zeiten. Anstoß und Dauer sind optional. Fehlen sie, gilt der Zeitraum des Spieltags und das Team terminiert selbst — das ist der Regelfall. kickoffAt ist ein ISO-8601-Zeitpunkt mit Offset oder Z und damit eindeutig; kickoffLocalTime wird über die Zeitzone des Wettbewerbs sommerzeitfest umgerechnet. Beide schließen sich aus. Antworten liefern immer UTC.

Absagen. Sie laufen ausschließlich über den Status, nie über Löschen — sonst gingen die Rückmeldungen der Spieler verloren.

Datenschutz. Der Rückkanal ist lesend und enthält keine personenbezogenen Daten: keine Namen, keine Rückmeldungen, keine Kaderdaten — nur Status, Zeiten und IDs.

Endpunkte

get	/seasons	Saisons abrufen
post	/seasons	Saisons anlegen oder aktualisieren
get	/competitions	Wettbewerbe abrufen
post	/competitions	Wettbewerbe anlegen oder aktualisieren
get	/teams	Ligateams abrufen
post	/teams	Ligateams anlegen oder aktualisieren
get	/rounds	Spieltage abrufen
post	/rounds	Spieltage anlegen oder aktualisieren
get	/fixtures	Begegnungen samt Planungsstand abrufen
post	/fixtures	Begegnungen anlegen, aktualisieren oder absagen
get	/fixtures/{id}	Einzelne Begegnung samt Planungsstand abrufen
post	/fixtures/csv	Begegnungen als CSV einspeisen
post	/schedule	Kompletten Spielplan in einem Aufruf einspeisen
get	/suspensions	Sperren und Rückzüge abrufen
post	/suspensions	Sperre oder Rückzug setzen
delete	/suspensions/{id}	Sperre vorzeitig aufheben oder Rückzug zurücknehmen
get	/meta	Version, Serverzeit, Rate-Limits und Enum-Werte
get	/openapi.json	Diese Beschreibung als OpenAPI-Dokument
post	/sandbox/seed	Beispielsaison in der Sandbox anlegen
post	/sandbox/reset	Sandbox-Daten löschen
post	/sandbox/fixtures/{id}/planning	Planungsstatus einer Seite simulieren

get/seasons

Saisons abrufen

Rate-Limit: 60 Anfragen pro 60 Sekunden.

Parameter

limit (query) Seitengröße. Standard 50, Maximum 200.
cursor (query) Interne ID des letzten Datensatzes der Vorseite (nextCursor).

Antworten

200 Saisons des Verbands.
401 Kein oder ungültiger API-Key.
403 Key widerrufen, Verband inaktiv oder Modul deaktiviert.
429 Rate-Limit überschritten.

post/seasons

Saisons anlegen oder aktualisieren

Nimmt ein Objekt oder ein Array entgegen. Upsert über externalId.

Rate-Limit: 60 Anfragen pro 60 Sekunden.

Rumpf — ein Objekt oder ein Array davon

Feld	Typ	Beschreibung
externalId*	string	ID der Saison im System des Verbands. Muss pro Verband über alle Saisons hinweg eindeutig sein. (min. 1 Zeichen, max. 190 Zeichen)
name*	string	Anzeigename, z. B. „Saison 2026/27“. (min. 1 Zeichen, max. 200 Zeichen)
startsOn*	string	Erster Tag der Saison. (Muster ^\d{4}-\d{2}-\d{2}$)
endsOn*	string	Letzter Tag der Saison. (Muster ^\d{4}-\d{2}-\d{2}$)
previousSeasonExternalId	string	externalId der Vorsaison. Grundlage dafür, bestehende Verknüpfungen in die neue Saison zu übernehmen. (min. 1 Zeichen, max. 190 Zeichen)

Antworten

200 Alle Datensätze verarbeitet.
207 Gemischtes Ergebnis — mindestens ein Datensatz ist fehlgeschlagen.
400 Validierungsfehler.
401 Kein oder ungültiger API-Key.
403 Key widerrufen, Verband inaktiv oder Modul deaktiviert.
409 Konflikt, z. B. externalId gehört zu einer anderen Saison.
422 Fachlich unzulässig, z. B. Upsert in eine archivierte Saison.
429 Rate-Limit überschritten.

get/competitions

Wettbewerbe abrufen

Rate-Limit: 60 Anfragen pro 60 Sekunden.

Parameter

limit (query) Seitengröße. Standard 50, Maximum 200.
cursor (query) Interne ID des letzten Datensatzes der Vorseite (nextCursor).
season (query) Auf eine Saison einschränken (externalId).

Antworten

200 Wettbewerbe des Verbands.
401 Kein oder ungültiger API-Key.
403 Key widerrufen, Verband inaktiv oder Modul deaktiviert.
429 Rate-Limit überschritten.

post/competitions

Wettbewerbe anlegen oder aktualisieren

Nimmt ein Objekt oder ein Array entgegen. Upsert über externalId.

Rate-Limit: 60 Anfragen pro 60 Sekunden.

Rumpf — ein Objekt oder ein Array davon

Feld	Typ	Beschreibung
externalId*	string	ID des Wettbewerbs im System des Verbands. (min. 1 Zeichen, max. 190 Zeichen)
seasonExternalId*	string	externalId der Saison, zu der der Wettbewerb gehört. (min. 1 Zeichen, max. 190 Zeichen)
name*	string	Anzeigename, z. B. „Bezirksliga Herren“. (min. 1 Zeichen, max. 200 Zeichen)
type	LEAGUE \| CUP \| FRIENDLY	Art des Wettbewerbs. (Standard "LEAGUE")
sport	string	Sportart, z. B. „Handball“. (max. 100 Zeichen)
ageGroup	string	Altersklasse, z. B. „Herren“. (max. 100 Zeichen)
timezone	string	IANA-Zeitzone. Sie hängt am Wettbewerb, nicht am Verband, weil Wettbewerbe regional verortet sind. (min. 1 Zeichen, max. 100 Zeichen, Standard "Europe/Berlin")
defaultKickoffTime	string	Standard-Anstoß als Ortszeit, wenn eine Begegnung keinen eigenen trägt. (Muster ^([01]\d\|2[0-3]):[0-5]\d$)
defaultDurationMinutes	integer	Standarddauer in Minuten, wenn eine Begegnung keine eigene trägt. (max. 600)

Antworten

200 Alle Datensätze verarbeitet.
207 Gemischtes Ergebnis — mindestens ein Datensatz ist fehlgeschlagen.
400 Validierungsfehler.
401 Kein oder ungültiger API-Key.
403 Key widerrufen, Verband inaktiv oder Modul deaktiviert.
409 Konflikt, z. B. externalId gehört zu einer anderen Saison.
422 Fachlich unzulässig, z. B. Upsert in eine archivierte Saison.
429 Rate-Limit überschritten.

get/teams

Ligateams abrufen

Rate-Limit: 60 Anfragen pro 60 Sekunden.

Parameter

limit (query) Seitengröße. Standard 50, Maximum 200.
cursor (query) Interne ID des letzten Datensatzes der Vorseite (nextCursor).

Antworten

200 Ligateams des Verbands.
401 Kein oder ungültiger API-Key.
403 Key widerrufen, Verband inaktiv oder Modul deaktiviert.
429 Rate-Limit überschritten.

post/teams

Ligateams anlegen oder aktualisieren

Nimmt ein Objekt oder ein Array entgegen. Upsert über externalId.

Rate-Limit: 60 Anfragen pro 60 Sekunden.

Rumpf — ein Objekt oder ein Array davon

Feld	Typ	Beschreibung
externalId*	string	ID der Mannschaft im System des Verbands. (min. 1 Zeichen, max. 190 Zeichen)
name*	string	Name der Mannschaft, z. B. „SV Donnerblitz II“. (min. 1 Zeichen, max. 200 Zeichen)
clubName	string	Name des Vereins, z. B. „SV Donnerblitz e.V.“. (max. 200 Zeichen)
shortName	string	Kurzform für enge Darstellungen. (max. 50 Zeichen)
homeVenueName	string	Name der Heimspielstätte. (max. 200 Zeichen)
homeVenueAddress	string	Anschrift der Heimspielstätte. (max. 300 Zeichen)

Antworten

200 Alle Datensätze verarbeitet.
207 Gemischtes Ergebnis — mindestens ein Datensatz ist fehlgeschlagen.
400 Validierungsfehler.
401 Kein oder ungültiger API-Key.
403 Key widerrufen, Verband inaktiv oder Modul deaktiviert.
409 Konflikt, z. B. externalId gehört zu einer anderen Saison.
422 Fachlich unzulässig, z. B. Upsert in eine archivierte Saison.
429 Rate-Limit überschritten.

get/rounds

Spieltage abrufen

Rate-Limit: 60 Anfragen pro 60 Sekunden.

Parameter

limit (query) Seitengröße. Standard 50, Maximum 200.
cursor (query) Interne ID des letzten Datensatzes der Vorseite (nextCursor).
competition (query) Auf einen Wettbewerb einschränken (externalId).

Antworten

200 Spieltage des Verbands.
401 Kein oder ungültiger API-Key.
403 Key widerrufen, Verband inaktiv oder Modul deaktiviert.
429 Rate-Limit überschritten.

post/rounds

Spieltage anlegen oder aktualisieren

Nimmt ein Objekt oder ein Array entgegen. Upsert über externalId.

Rate-Limit: 60 Anfragen pro 60 Sekunden.

Rumpf — ein Objekt oder ein Array davon

Feld	Typ	Beschreibung
externalId*	string	ID des Spieltags im System des Verbands. (min. 1 Zeichen, max. 190 Zeichen)
competitionExternalId*	string	externalId des Wettbewerbs, zu dem der Spieltag gehört. (min. 1 Zeichen, max. 190 Zeichen)
name*	string	Anzeigename, z. B. „1. Spieltag“. (min. 1 Zeichen, max. 200 Zeichen)
number	integer	Laufende Nummer des Spieltags. (max. 9007199254740991)
periodStart*	string	Erster Tag des Zeitraums, in dem der Spieltag ausgetragen wird. (Muster ^\d{4}-\d{2}-\d{2}$)
periodEnd*	string	Letzter Tag des Zeitraums. Ohne festen Anstoß terminieren die Teams innerhalb dieses Zeitraums. (Muster ^\d{4}-\d{2}-\d{2}$)

Antworten

200 Alle Datensätze verarbeitet.
207 Gemischtes Ergebnis — mindestens ein Datensatz ist fehlgeschlagen.
400 Validierungsfehler.
401 Kein oder ungültiger API-Key.
403 Key widerrufen, Verband inaktiv oder Modul deaktiviert.
409 Konflikt, z. B. externalId gehört zu einer anderen Saison.
422 Fachlich unzulässig, z. B. Upsert in eine archivierte Saison.
429 Rate-Limit überschritten.

get/fixtures

Begegnungen samt Planungsstand abrufen

Der Rückkanal ist lesend — ein Planungsstatus ändert niemals Ligadaten. Unterstützt ETag und If-None-Match und antwortet mit 304, wenn sich nichts geändert hat.

Rate-Limit: 60 Anfragen pro 60 Sekunden.

Parameter

limit (query) Seitengröße. Standard 50, Maximum 200.
cursor (query) Interne ID des letzten Datensatzes der Vorseite (nextCursor).
status (query) Auf einen Begegnungsstatus einschränken.
competition (query) Auf einen Wettbewerb einschränken (externalId).
matchday (query) Auf einen Spieltag einschränken (externalId).

Antworten

200 Begegnungen mit Planungsblock.
304 Unverändert seit dem mitgeschickten ETag.
401 Kein oder ungültiger API-Key.
403 Key widerrufen, Verband inaktiv oder Modul deaktiviert.
429 Rate-Limit überschritten.

post/fixtures

Begegnungen anlegen, aktualisieren oder absagen

Nimmt ein Objekt oder ein Array entgegen. Eine Absage ist ein Upsert mit status = CANCELLED, kein Löschen.

Rate-Limit: 60 Anfragen pro 60 Sekunden.

Rumpf — ein Objekt oder ein Array davon

Feld	Typ	Beschreibung
externalId*	string	ID der Begegnung im System des Verbands. (min. 1 Zeichen, max. 190 Zeichen)
roundExternalId	string	externalId des Spieltags, zu dem die Begegnung gehört. (min. 1 Zeichen, max. 190 Zeichen)
homeTeamExternalId	string	externalId der Heimmannschaft. (min. 1 Zeichen, max. 190 Zeichen)
awayTeamExternalId	string	externalId der Gastmannschaft. (min. 1 Zeichen, max. 190 Zeichen)
venueName	string	Spielstätte, falls abweichend von der Heimspielstätte. (max. 200 Zeichen)
venueAddress	string	Anschrift der abweichenden Spielstätte. (max. 300 Zeichen)
status	SCHEDULED \| CANCELLED	Absagen laufen ausschließlich über den Status, nie über Löschen — sonst gingen die Rückmeldungen der Spieler verloren. VOID wird nicht gesetzt, sondern ergibt sich aus einer Sperre.
kickoffAt	string (date-time)	Anstoß als ISO-8601-Zeitpunkt mit Offset oder Z — eindeutig, empfohlen. Schließt kickoffLocalTime aus.
kickoffLocalTime	string	Anstoß als Ortszeit HH:mm; wird über die Zeitzone des Wettbewerbs und das Datum des Spieltags sommerzeitfest in UTC umgerechnet. Schließt kickoffAt aus. (Muster ^([01]\d\|2[0-3]):[0-5]\d$)
durationMinutes	integer	Dauer in Minuten. Fehlt sie, greift der Standardwert des Wettbewerbs, danach der des Teams. (max. 600)
note	string	Freitext, z. B. der Grund einer Absage. (max. 500 Zeichen)

Antworten

200 Alle Datensätze verarbeitet.
207 Gemischtes Ergebnis — mindestens ein Datensatz ist fehlgeschlagen.
400 Validierungsfehler.
401 Kein oder ungültiger API-Key.
403 Key widerrufen, Verband inaktiv oder Modul deaktiviert.
409 Konflikt, z. B. externalId gehört zu einer anderen Saison.
422 Fachlich unzulässig, z. B. Upsert in eine archivierte Saison.
429 Rate-Limit überschritten.

get/fixtures/{id}

Einzelne Begegnung samt Planungsstand abrufen

Rate-Limit: 60 Anfragen pro 60 Sekunden.

Parameter

id (path, Pflicht) Interne ID der Begegnung (id aus der Upsert-Antwort).

Antworten

200 Die Begegnung.
304 Unverändert seit dem mitgeschickten ETag.
401 Kein oder ungültiger API-Key.
403 Key widerrufen, Verband inaktiv oder Modul deaktiviert.
404 Objekt existiert nicht in diesem Verband.
429 Rate-Limit überschritten.

post/fixtures/csv

Begegnungen als CSV einspeisen

Gleiche Spalten wie das JSON-Feld, erste Zeile ist die Kopfzeile. Jede Zeile wird einzeln validiert und einzeln gemeldet.

Rate-Limit: 10 Anfragen pro 60 Sekunden.

Antworten

200 Alle Datensätze verarbeitet.
207 Gemischtes Ergebnis — mindestens ein Datensatz ist fehlgeschlagen.
400 Validierungsfehler.
401 Kein oder ungültiger API-Key.
403 Key widerrufen, Verband inaktiv oder Modul deaktiviert.
409 Konflikt, z. B. externalId gehört zu einer anderen Saison.
422 Fachlich unzulässig, z. B. Upsert in eine archivierte Saison.
429 Rate-Limit überschritten.

post/schedule

Kompletten Spielplan in einem Aufruf einspeisen

Saison, Wettbewerb, Ligateams, Spieltage und Begegnungen zusammen — der Hauptweg für die Erstbefüllung. Verarbeitung ist teilweise erfolgreich.

Rate-Limit: 10 Anfragen pro 60 Sekunden.

Rumpf

Feld	Typ	Beschreibung
season*	object	Saison, in die eingespeist wird. Wird angelegt oder aktualisiert.
season.externalId*	string	ID der Saison im System des Verbands. Muss pro Verband über alle Saisons hinweg eindeutig sein. (min. 1 Zeichen, max. 190 Zeichen)
season.name*	string	Anzeigename, z. B. „Saison 2026/27“. (min. 1 Zeichen, max. 200 Zeichen)
season.startsOn*	string	Erster Tag der Saison. (Muster ^\d{4}-\d{2}-\d{2}$)
season.endsOn*	string	Letzter Tag der Saison. (Muster ^\d{4}-\d{2}-\d{2}$)
season.previousSeasonExternalId	string	externalId der Vorsaison. Grundlage dafür, bestehende Verknüpfungen in die neue Saison zu übernehmen. (min. 1 Zeichen, max. 190 Zeichen)
competition*	object	Wettbewerb. Die Saisonzuordnung ergibt sich aus dem Feld season.
competition.externalId*	string	ID des Wettbewerbs im System des Verbands. (min. 1 Zeichen, max. 190 Zeichen)
competition.name*	string	Anzeigename, z. B. „Bezirksliga Herren“. (min. 1 Zeichen, max. 200 Zeichen)
competition.type	LEAGUE \| CUP \| FRIENDLY	Art des Wettbewerbs. (Standard "LEAGUE")
competition.sport	string	Sportart, z. B. „Handball“. (max. 100 Zeichen)
competition.ageGroup	string	Altersklasse, z. B. „Herren“. (max. 100 Zeichen)
competition.timezone	string	IANA-Zeitzone. Sie hängt am Wettbewerb, nicht am Verband, weil Wettbewerbe regional verortet sind. (min. 1 Zeichen, max. 100 Zeichen, Standard "Europe/Berlin")
competition.defaultKickoffTime	string	Standard-Anstoß als Ortszeit, wenn eine Begegnung keinen eigenen trägt. (Muster ^([01]\d\|2[0-3]):[0-5]\d$)
competition.defaultDurationMinutes	integer	Standarddauer in Minuten, wenn eine Begegnung keine eigene trägt. (max. 600)
teams	object[]	Ligateams des Wettbewerbs. (Standard [])
teams[].externalId*	string	ID der Mannschaft im System des Verbands. (min. 1 Zeichen, max. 190 Zeichen)
teams[].name*	string	Name der Mannschaft, z. B. „SV Donnerblitz II“. (min. 1 Zeichen, max. 200 Zeichen)
teams[].clubName	string	Name des Vereins, z. B. „SV Donnerblitz e.V.“. (max. 200 Zeichen)
teams[].shortName	string	Kurzform für enge Darstellungen. (max. 50 Zeichen)
teams[].homeVenueName	string	Name der Heimspielstätte. (max. 200 Zeichen)
teams[].homeVenueAddress	string	Anschrift der Heimspielstätte. (max. 300 Zeichen)
rounds	object[]	Spieltage. Die Wettbewerbszuordnung ergibt sich aus dem Feld competition. (Standard [])
rounds[].externalId*	string	ID des Spieltags im System des Verbands. (min. 1 Zeichen, max. 190 Zeichen)
rounds[].name*	string	Anzeigename, z. B. „1. Spieltag“. (min. 1 Zeichen, max. 200 Zeichen)
rounds[].number	integer	Laufende Nummer des Spieltags. (max. 9007199254740991)
rounds[].periodStart*	string	Erster Tag des Zeitraums, in dem der Spieltag ausgetragen wird. (Muster ^\d{4}-\d{2}-\d{2}$)
rounds[].periodEnd*	string	Letzter Tag des Zeitraums. Ohne festen Anstoß terminieren die Teams innerhalb dieses Zeitraums. (Muster ^\d{4}-\d{2}-\d{2}$)
fixtures	object[]	Begegnungen des Spielplans. (Standard [])
fixtures[].externalId*	string	ID der Begegnung im System des Verbands. (min. 1 Zeichen, max. 190 Zeichen)
fixtures[].roundExternalId	string	externalId des Spieltags, zu dem die Begegnung gehört. (min. 1 Zeichen, max. 190 Zeichen)
fixtures[].homeTeamExternalId	string	externalId der Heimmannschaft. (min. 1 Zeichen, max. 190 Zeichen)
fixtures[].awayTeamExternalId	string	externalId der Gastmannschaft. (min. 1 Zeichen, max. 190 Zeichen)
fixtures[].venueName	string	Spielstätte, falls abweichend von der Heimspielstätte. (max. 200 Zeichen)
fixtures[].venueAddress	string	Anschrift der abweichenden Spielstätte. (max. 300 Zeichen)
fixtures[].status	SCHEDULED \| CANCELLED	Absagen laufen ausschließlich über den Status, nie über Löschen — sonst gingen die Rückmeldungen der Spieler verloren. VOID wird nicht gesetzt, sondern ergibt sich aus einer Sperre.
fixtures[].kickoffAt	string (date-time)	Anstoß als ISO-8601-Zeitpunkt mit Offset oder Z — eindeutig, empfohlen. Schließt kickoffLocalTime aus.
fixtures[].kickoffLocalTime	string	Anstoß als Ortszeit HH:mm; wird über die Zeitzone des Wettbewerbs und das Datum des Spieltags sommerzeitfest in UTC umgerechnet. Schließt kickoffAt aus. (Muster ^([01]\d\|2[0-3]):[0-5]\d$)
fixtures[].durationMinutes	integer	Dauer in Minuten. Fehlt sie, greift der Standardwert des Wettbewerbs, danach der des Teams. (max. 600)
fixtures[].note	string	Freitext, z. B. der Grund einer Absage. (max. 500 Zeichen)

Antworten

200 Alle Datensätze verarbeitet.
207 Gemischtes Ergebnis — mindestens ein Datensatz ist fehlgeschlagen.
400 Validierungsfehler.
401 Kein oder ungültiger API-Key.
403 Key widerrufen, Verband inaktiv oder Modul deaktiviert.
409 Konflikt, z. B. externalId gehört zu einer anderen Saison.
422 Fachlich unzulässig, z. B. Upsert in eine archivierte Saison.
429 Rate-Limit überschritten.

get/suspensions

Sperren und Rückzüge abrufen

Rate-Limit: 60 Anfragen pro 60 Sekunden.

Parameter

limit (query) Seitengröße. Standard 50, Maximum 200.
cursor (query) Interne ID des letzten Datensatzes der Vorseite (nextCursor).

Antworten

200 Sperren und Rückzüge des Verbands.
401 Kein oder ungültiger API-Key.
403 Key widerrufen, Verband inaktiv oder Modul deaktiviert.
429 Rate-Limit überschritten.

post/suspensions

Sperre oder Rückzug setzen

Entfernt die betroffenen Begegnungen bei beiden Mannschaften. Der Grund ist verbandsintern und wird nie an Teams ausgeliefert.

Rate-Limit: 60 Anfragen pro 60 Sekunden.

Rumpf

Feld	Typ	Beschreibung
leagueTeamExternalId*	string	externalId der betroffenen Mannschaft. (min. 1 Zeichen, max. 190 Zeichen)
seasonExternalId*	string	externalId der betroffenen Saison. (min. 1 Zeichen, max. 190 Zeichen)
kind	SUSPENSION \| WITHDRAWAL	SUSPENSION ist befristet und verlangt endsOn. WITHDRAWAL ist ein Rückzug und gilt ohne endsOn für den Rest der Saison. (Standard "SUSPENSION")
startsOn*	string	Erster Tag der Sperre bzw. Tag des Rückzugs. (Muster ^\d{4}-\d{2}-\d{2}$)
endsOn	string	Letzter Tag der Sperre. Pflichtfeld bei kind = SUSPENSION, entfällt bei WITHDRAWAL. (Muster ^\d{4}-\d{2}-\d{2}$)
reason*	string	Begründung. Verbandsintern — wird niemals an Teams ausgeliefert. (min. 1 Zeichen, max. 1000 Zeichen)

Antworten

201 Sperre angelegt.
400 Validierungsfehler.
401 Kein oder ungültiger API-Key.
403 Key widerrufen, Verband inaktiv oder Modul deaktiviert.
404 Objekt existiert nicht in diesem Verband.
422 Fachlich unzulässig, z. B. Upsert in eine archivierte Saison.
429 Rate-Limit überschritten.

delete/suspensions/{id}

Sperre vorzeitig aufheben oder Rückzug zurücknehmen

Betroffene Begegnungen kehren auf SCHEDULED zurück — und zwar genau die, die diese Sperre entfallen ließ.

Rate-Limit: 60 Anfragen pro 60 Sekunden.

Parameter

id (path, Pflicht) Interne ID der Sperre.

Antworten

200 Sperre aufgehoben.
401 Kein oder ungültiger API-Key.
403 Key widerrufen, Verband inaktiv oder Modul deaktiviert.
404 Objekt existiert nicht in diesem Verband.
422 Fachlich unzulässig, z. B. Upsert in eine archivierte Saison.
429 Rate-Limit überschritten.

get/meta

Version, Serverzeit, Rate-Limits und Enum-Werte

Damit eine Anbindung sich selbst prüfen kann.

Rate-Limit: 60 Anfragen pro 60 Sekunden.

Antworten

200 Selbstauskunft.
401 Kein oder ungültiger API-Key.
403 Key widerrufen, Verband inaktiv oder Modul deaktiviert.
429 Rate-Limit überschritten.

get/openapi.json

Diese Beschreibung als OpenAPI-Dokument

Öffentlich, ohne API-Key — die Beschreibung muss lesbar sein, bevor ein Key vorliegt.

Rate-Limit: 60 Anfragen pro 60 Sekunden. Ohne API-Key erreichbar.

Antworten

200 Das OpenAPI-Dokument.
404 Das Ligamodul ist auf dieser Installation nicht eingeschaltet.
429 Rate-Limit überschritten.

post/sandbox/seed

Beispielsaison in der Sandbox anlegen

Legt zwei Wettbewerbe, acht Ligateams, Spieltage und einen kompletten Spielplan an, damit die GET-Endpunkte sofort gegen realistische Daten testbar sind.

Rate-Limit: 10 Anfragen pro 60 Sekunden.

Antworten

200 Beispieldaten angelegt.
401 Kein oder ungültiger API-Key.
403 Key widerrufen, Verband inaktiv oder Modul deaktiviert.
404 Objekt existiert nicht in diesem Verband.
429 Rate-Limit überschritten.

post/sandbox/reset

Sandbox-Daten löschen

Löscht Saisons, Wettbewerbe, Ligateams, Spieltage, Begegnungen, Sperren und Zustellprotokolle. Der Verband selbst, seine Mitglieder und seine API-Keys bleiben bestehen.

Rate-Limit: 10 Anfragen pro 60 Sekunden.

Antworten

200 Sandbox zurückgesetzt.
401 Kein oder ungültiger API-Key.
403 Key widerrufen, Verband inaktiv oder Modul deaktiviert.
404 Objekt existiert nicht in diesem Verband.
429 Rate-Limit überschritten.

post/sandbox/fixtures/{id}/planning

Planungsstatus einer Seite simulieren

Setzt den Planungsstatus direkt und löst denselben Webhook aus wie ein echter Teamvorgang — damit lässt sich die gesamte Anbindung durchspielen, ohne dass ein Verein etwas davon merkt.

Rate-Limit: 60 Anfragen pro 60 Sekunden.

Parameter

id (path, Pflicht) Interne ID der Begegnung.

Rumpf

Feld	Typ	Beschreibung
side*	HOME \| AWAY	Seite der Begegnung, deren Planungsstatus gesetzt wird.
status*	OPEN \| IN_POLL \| SCHEDULED \| CANCELLED	Zielstatus. NOT_LINKED fehlt bewusst: eine einmal simulierte Seite bleibt verknüpft, wie ein echter TeamLink auch.
confirmedDate	string	Terminierter Tag, sinnvoll bei status = SCHEDULED. (Muster ^\d{4}-\d{2}-\d{2}$)
kickoffAt	string (date-time)	Anstoß als ISO-8601-Zeitpunkt mit Offset oder Z.
durationMinutes	integer	Dauer in Minuten. (max. 600)

Antworten

200 Neuer Planungsstand der Begegnung.
400 Validierungsfehler.
401 Kein oder ungültiger API-Key.
403 Key widerrufen, Verband inaktiv oder Modul deaktiviert.
404 Objekt existiert nicht in diesem Verband.
429 Rate-Limit überschritten.

Fehler und Rate-Limits

Fehler folgen dem Format der App: ein einziger error-Schlüssel, etwa { "error": "season.externalId: Pflichtfeld" }.

400	Validierungsfehler.
401	Kein oder ungültiger API-Key.
403	Key widerrufen, Verband inaktiv oder Modul deaktiviert.
404	Objekt existiert nicht in diesem Verband.
409	Konflikt, z. B. externalId gehört zu einer anderen Saison.
422	Fachlich unzulässig, z. B. Upsert in eine archivierte Saison.
429	Rate-Limit überschritten.

Standard 60 Anfragen pro Minute und Key, Bulk-Endpunkte 10 pro Minute. Bei Überschreitung 429 mit Retry-After in Sekunden.

Webhooks

Alternativ zum Abruf könnt ihr eine URL hinterlegen. Events: fixture.planning_updated und fixture.cancelled. Header: X-Webhook-Event, X-Webhook-Id, X-Webhook-Timestamp und X-Webhook-Signature (HMAC-SHA256 über den rohen Body, hex). Event-ID und Zeitstempel stehen zusätzlich im Body und sind damit von der Signatur gedeckt.

Die Zustellung ist at-least-once: bei Fehlern wird mit exponentiellem Backoff bis zu sechsmal erneut zugestellt. Empfänger müssen deduplizieren — die eventId ist dafür der Schlüssel.

import { createHmac, timingSafeEqual } from "node:crypto";

function verify(rawBody, signatureHeader, secret) {
  const expected = createHmac("sha256", secret).update(rawBody).digest("hex");
  const a = Buffer.from(signatureHeader, "hex");
  const b = Buffer.from(expected, "hex");
  return a.length === b.length && timingSafeEqual(a, b);
}

function verify(string $rawBody, string $signature, string $secret): bool {
    $expected = hash_hmac('sha256', $rawBody, $secret);
    return hash_equals($expected, $signature);
}

Wichtig in beiden Fällen: über den rohen Body signieren, nicht über das erneut serialisierte JSON.

Sandbox

Eine Sandbox ist ein eigener Verband mit eigenen Keys tma_sbx_…. Endpunktumfang und Validierung sind identisch — was in der Sandbox durchgeht, geht auch live durch. Verknüpfungen zu echten Teams sind dort nicht möglich; stattdessen lässt sich der Planungsstatus direkt setzen, was dieselben Webhooks auslöst wie ein echter Teamvorgang. So ist die gesamte Anbindung durchspielbar, ohne dass ein Verein etwas davon merkt.

Versionierung

/api/v1/… ist der stabile Vertrag. Additive Änderungen sind jederzeit ohne Ankündigung möglich: neue Endpunkte, neue optionale Felder im Request, neue Felder in der Antwort. Clients müssen unbekannte Antwortfelder ignorieren.

Brechend sind: ein Feld entfernen oder umbenennen, den Typ ändern, ein bisher optionales Feld zur Pflicht machen, die Bedeutung eines Wertes ändern. Solche Änderungen erscheinen unter /api/v2/…; v1 bleibt danach mindestens 12 Monate bedienbar. Eine abgekündigte Version liefert zusätzlich Deprecation und Sunset.

GET /meta liefert Version, Serverzeit, Rate-Limits und die unterstützten Enum-Werte — damit eine Anbindung sich selbst prüfen kann.