API
Aus TW-Sportsoft Wiki (Online-Dokumentation)
Inhaltsverzeichnis
- 1 Einleitung
- 2 Voraussetzungen
- 3 Autorisierung
- 4 Technik
- 5 Requests
- 5.1 Request: Zeiten speichern
- 5.2 Request: Zeiten löschen
- 5.3 Request: Strafzeiten speichern
- 5.4 Request: Strafzeiten löschen
- 5.5 Request: Meldungen speichern
- 5.6 Request: Meldungen löschen
- 5.7 Request: Dokumente (virtueller Aushang) speichern
- 5.8 Request: Dokumente (virtueller Aushang) löschen
- 5.9 Request: Kennzeichen setzen
- 6 Sonstige Hinweise
- 7 Version
Einleitung
Über die TW-Sportsoft API (offene Schnittstelle) können externe Systeme angeschlossen werden.
Extern anfallende Daten z.B. aus dem Bereich Auswertung/Zeitnahme (Startzeiten, Zielzeiten, Fahrzeiten, Strafzeiten, Meldungen etc.) oder der Race-Control müssen somit nicht manuell erfasst werden, sondern könnten automatisch über diese Schnittstelle an das System übertragen werden.
Voraussetzungen
- Es muss eine Installation des Veranstaltungssystems mit den Modulen „Online-Nennung“ und „Auswertung“ vorhanden sein.
- Alle Teilnehmer-Daten müssen mit Startnummern oder Transpondernummern, Wertungsgruppen/Klassen angelegt sein.
- Das Gateway für die API muss über den Systemparameter im Administrationsbereich (Menüpunkt Parameter->Auswertung) der Veranstaltung geöffnet werden.
- Ein API-Key im Administrationsbereich unter dem (Menüpunkt Parameter->Auswertung) hinterlegt werden. Ohne API-Key kann mit der API nicht kommuniziert werden.
Rechtzeitig vor der Veranstaltung sollten entsprechende Tests mit dem Veranstaltungssystem durchgeführt werden.
Autorisierung
Den API-Key finden Sie unter dem Menüpunkt Parameter->Global im Veranstaltungssystem. Achten Sie auf die korrekte Groß-/Kleinschreibung.
Status-Code
401: API-Key nicht korrekt oder API inaktiv. Parameter -> Auswertung im Veranstaltungssystem pruefen.
Technik
Die Daten müssen als POST-Daten mittels einem Request versendet werden.
Beispiel – JavaScript
<script>
$(document).ready(function() {
//Daten
var data = {
API_KEY: 'gb8kme29swDpCd9Axd',
ACTION: 'ZEIT_SPEICHERN',
WP_LAUF_NR: '1',
ART: 'FAHRZEIT',
ZEIT: '320.6',
STARTNUMMER: '5'
};
//Request an API senden
$.ajax({
url: 'https://www.tw-sportsoft.de/MUSTER_VERANSTALTUNG/api.php',
type: 'POST',
data: data
});
});
</script>
API-URL (Gateway)
Die Daten sind an folgende API-URL (Systemherkunft TW-Sportsoft) zu senden: https://www.tw-sportsoft.de/MUSTER_VERANSTALTUNG/api.php
Die Daten sind an folgende API-URL (Systemherkunft ADAC Sportabteilung) zu senden: https://www.adac-sport.com/MUSTER_VERANSTALTUNG/api.php
Den URL-Teil MUSTER_VERANSTALTUNG durch den Verzeichnisnamen der Veranstaltung ersetzen.
Requests
Request: Zeiten speichern
Über diese Funktion werden Zeiten oder Status-Kennzeichen an das System gesendet. Hinweis: Wird eine Zeit zur gleichen Veranstaltung, WP/Lauf-Nummer und Startnummer nochmals gesendet, so wird die vorherige Zeit automatisch überschrieben. Darüber können eventuelle Fehleingaben korrigiert werden.
| Datenfeld | Standard-Wert | Beispiel-Wert(e) | Datentyp | Pflichtfeld | Beschreibung |
|---|---|---|---|---|---|
| API_KEY | gb8kme29swDpCd9Axd | VARCHAR | ja | API-Key zur Autorisierung gegenüber der API | |
| ACTION | ZEIT_SPEICHERN | ZEIT_SPEICHERN | VARCHAR | ja | Angabe, welche Aktion ausgeführt wird |
| WP_LAUF_NR | 1 | INTEGER | ja | Nummer der WP/Lauf | |
| LAP | 1 | INTEGER | nein | Rundenzahl | |
| ART | START, ZIEL, FAHRZEIT, STATUS |
VARCHAR | ja | Art der gesendeten Zeit. Startzeit, Zielzeit, Fahrzeit oder ein Status-Wert | |
| STATUS | Folgende Status-Werte können übermittelt werden. 1=DNS 2=DNF 3=DNC 4=DIS |
2 | INTEGER | nein | Eine ggf. gesendete Zeit wird dann ignoriert. |
| ZEIT | 43591.862 | DECIMAL(9,3) | ja | Die Zeit in Sekunden mit Nachkommastellen | |
| STARTNUMMER | 15 | INTEGER | ja | Startnummer des Teilnehmers , sofern keine Transpondernummer übermittelt wird | |
| TRANSPONDERNR | 15 | VARCHAR | ja | Transpondernummer des Teilnehmers, sofern keine Startnummer übermittelt wird |
Status-Codes
201: Zeit erfolgreich gespeichert.
500: Zeit konnte nicht gespeichert werden.
Request: Zeiten löschen
Über diese Funktion können Zeiten aus dem System entfernt werden.
| Datenfeld | Standard-Wert | Beispiel-Wert(e) | Datentyp | Pflichtfeld | Beschreibung |
|---|---|---|---|---|---|
| ACTION | ZEIT_LOESCHEN | ZEIT_LOESCHEN | VARCHAR | ja | Angabe, welche Aktion ausgeführt wird |
| WP_LAUF_NR | 1 | INTEGER | ja | Nummer der WP/Lauf | |
| ART | START, ZIEL, FAHRZEIT, STATUS | VARCHAR | ja | Art der gesendeten Zeit. Startzeit, Zielzeit oder Fahrzeit | |
| STARTNUMMER | 15 | INTEGER | ja | Startnummer des Teilnehmers , sofern keine Transpondernummer übermittelt wird | |
| TRANSPONDERNR | 15 | VARCHAR | ja | Transpondernummer des Teilnehmers, sofern keine Startnummer übermittelt wird |
Status-Codes
201: Zeit erfolgreich geloescht.
500: Zeit konnte nicht geloescht werden.
Request: Strafzeiten speichern
Über diese Funktion werden Strafzeiten an das System gesendet. Hinweis: Wird eine Strafzeit zu gleicher Veranstaltung, WP/Lauf-Nummer und Startnummer nochmals gesendet, so wird die vorherige automatisch überschrieben. Darüber können eventuelle Fehleingaben korrigiert werden.
| Datenfeld | Standard-Wert | Beispiel-Wert(e) | Datentyp | Pflichtfeld | Beschreibung |
|---|---|---|---|---|---|
| ACTION | STRAFZEIT_SPEICHERN | STRAFZEIT_SPEICHERN | VARCHAR | ja | Angabe, welche Aktion ausgeführt wird |
| WP_LAUF_NR | 1 | INTEGER | ja | Nummer der WP/Lauf | |
| ZEIT | 10.0 | DECIMAL(6,3) | ja | Die Zeit in Sekunden mit Nachkommastellen | |
| GRUND | Frühstart | VARCHAR(50) | nein | Grund für die Strafzeit | |
| STARTNUMMER | 15 | INTEGER | ja | Startnummer des Teilnehmers , sofern keine Transpondernummer übermittelt wird | |
| TRANSPONDERNR | 15 | VARCHAR | ja | Transpondernummer des Teilnehmers, sofern keine Startnummer übermittelt wird |
Status-Codes
201: Strafzeit erfolgreich gespeichert.
400: Strafzeit konnte nicht gespeichert werden. Pflichtfeld-Angaben fehlen.
500: Strafzeit konnte nicht gespeichert werden.
Request: Strafzeiten löschen
Über diese Funktion können Strafzeiten aus dem System entfernt werden.
| Datenfeld | Standard-Wert | Beispiel-Wert(e) | Datentyp | Pflichtfeld | Beschreibung |
|---|---|---|---|---|---|
| ACTION | STRAFZEIT_LOESCHEN | STRAFZEIT_LOESCHEN | VARCHAR | ja | Angabe, welche Aktion ausgeführt wird |
| WP_LAUF_NR | 1 | INTEGER | ja | Nummer der WP/Lauf | |
| STARTNUMMER | 15 | INTEGER | ja | Startnummer des Teilnehmers , sofern keine Transpondernummer übermittelt wird | |
| TRANSPONDERNR | 15 | VARCHAR | ja | Transpondernummer des Teilnehmers, sofern keine Startnummer übermittelt wird |
Status-Codes
201: Strafzeit erfolgreich geloescht.
500: Strafzeit konnte nicht geloescht werden.
Request: Meldungen speichern
Über diese Funktion werden Meldungen an das System gesendet.
| Datenfeld | Standard-Wert | Beispiel-Wert(e) | Datentyp | Pflichtfeld | Beschreibung |
|---|---|---|---|---|---|
| ACTION | LEITSTELLE_MELDUNG_SPEICHERN | LEITSTELLE_MELDUNG_SPEICHERN | VARCHAR | ja | Angabe, welche Aktion ausgeführt wird |
| MELDUNGART_ID | 3 | INTEGER | ja | 1=Zeitstrafe 2=Unfall 3=Technischer Defekt 4=Information 5=Sonstiges | |
| MELDUNG | Motorschaden | VARCHAR(250) | ja | Beschreibung der Meldung | |
| WP_LAUF_NR | 1 | INTEGER | nein | Nummer der WP/Lauf | |
| STARTNUMMER | 15 | INTEGER | nein | Startnummer des Teilnehmers , sofern keine Transpondernummer übermittelt wird | |
| TRANSPONDERNR | 15 | VARCHAR | nein | Transpondernummer des Teilnehmers, sofern keine Startnummer übermittelt wird | |
| KZ_OEFFENTLICH | 0 | INTEGER | ja | 1=Kennzeichen, ob die Meldung öffentlich angezeigt werden soll 0=nur eine interne Information an die Leitstelle | |
| MELDUNG_ID | 12345 | INTEGER | nein | Externe ID der gesendeten Meldung |
Status-Codes
201: Meldung erfolgreich gespeichert.
400: Meldung konnte nicht gespeichert werden. Pflichtfeld-Angaben fehlen.
500: Meldung konnte nicht gespeichert werden.
Request: Meldungen löschen
Über diese Funktion werden Meldungen an das System gesendet. Um Meldungen löschen zu können, muss eine eindeutige externe Meldungsid oder Startnummer mit WP-/Lauf-Nr. übergeben werden.
| Datenfeld | Standard-Wert | Beispiel-Wert(e) | Datentyp | Pflichtfeld | Beschreibung |
|---|---|---|---|---|---|
| ACTION | LEITSTELLE_MELDUNG_LOESCHEN | LEITSTELLE_MELDUNG_LOESCHEN | VARCHAR | ja | Angabe, welche Aktion ausgeführt wird |
| MELDUNG_ID | 12345 | INTEGER | ja | Externe ID der gesendeten Meldung |
Status-Codes
201: Meldung Externe ID erfolgreich geloescht.
400: Meldung Externe ID konnte nicht geloescht werden. Pflichtfeld-Angaben fehlen.
500: Meldung Externe ID konnte nicht geloescht werden.
Request: Dokumente (virtueller Aushang) speichern
Über diese Funktion werden Dokumente für den virtuellen Aushang an das System gesendet.
| Datenfeld | Standard-Wert | Beispiel-Wert(e) | Datentyp | Pflichtfeld | Beschreibung |
|---|---|---|---|---|---|
| ACTION | VIRTUELLER_AUSHANG_DOKUMENT_SPEICHERN | VIRTUELLER_AUSHANG_DOKUMENT_SPEICHERN | VARCHAR | ja | Angabe, welche Aktion ausgeführt wird |
| DOKUMENT_ID_EXTERN | 123 | INTEGER | ja | Eindeutige externe ID zum Dokument | |
| DOKUMENT_ART_ID | 5 | INTEGER | ja | Eindeutige ID der Art des Dokuments zur Gruppierung | |
| BEZEICHNUNG | Strafe | VARCHAR(150) | ja | Bezeichnung des Dokuments | |
| ZEITPUNKT | 2020-01-01 10:15:20 | DATETIME | nein | Zeitpunkt des Dokuments | |
| BESCHREIBUNG | Ausführliche Beschreibung | VARCHAR(250) | nein | Optionale ausführliche Beschreibung des Dokuments | |
| DOKUMENT_DATEI | FILE | nein | Dokument als PDF-Datei | ||
| KZ_SPRACHE | 1 | INTEGER | nein | Kennzeichen der Sprache | |
| WP_LAUF_NR | 1 | INTEGER | nein | Nummer der WP/Lauf | |
| TEILNEHMER_ID | 15 | INTEGER | nein | Eindeutige Zuordnung des Teilnehmers, sofern Startnummer oder Transpondernummer nicht eindeutig sind | |
| STARTNUMMER | 15 | INTEGER | nein | Startnummer des Teilnehmers , sofern keine Transpondernummer übermittelt wird | |
| TRANSPONDERNR | 15 | VARCHAR | nein | Transpondernummer des Teilnehmers, sofern keine Startnummer übermittelt wird | |
| PRAEDIKAT_ID | 3 | INTEGER | nein | Eindeutige ID des Prädikates zur Zuordnung | |
| PRAEDIKAT_BEZEICHNUNG_KURZ | 20 | VARCHAR | nein | Eindeutige Kurzbezeichnung des Prädikates zur Zuordnung, sofern eindeutige Prädikat-ID nicht bekannt ist | |
| WERTUNGSGRUPPE_ID | 3 | INTEGER | nein | Eindeutige ID der Wertungsgruppe zur Zuordnung | |
| WERTUNGSGRUPPE_BEZEICHNUNG_KURZ | 20 | VARCHAR | nein | Eindeutige Kurzbezeichnung der Wertungsgruppe zur Zuordnung, sofern eindeutige Wertungsgruppen-ID nicht bekannt ist | |
| KZ_ZEITNAHME | 0 | INTEGER | nein | 1=Dokument für die Zeitnahme relevant 0=Dokument nicht für die Zeitnahme relevant | |
| KZ_GELDSTRAFE | 0 | INTEGER | nein | 1=Dokument beinhaltet eine Geldstrafe 0=Dokument beinhaltet keine Geldstrafe | |
| GELDSTRAFE_BETRAG | 0 | DECIMAL(15,2) | nein | Betrag der Geldstrafe | |
| KZ_OEFFENTLICH | 0 | INTEGER | ja | 1=Kennzeichen, ob die Meldung öffentlich angezeigt werden soll 0=nur eine interne Information an die Leitstelle | |
| EMAIL_TEILNEHMER_SENDEN | 1 | INTEGER | nein | Kennzeichen für automatischen Versand des Dokumentes an den zugeordneten Teilnehmer | |
| KZ_PUSH_NOTIFICATION_SENDEN | 1 | INTEGER | nein | Kennzeichen für automatischen Versand des Dokumentes an die App |
Status-Codes
201: Dokument Externe ID erfolgreich gespeichert.
400: Dokument konnte nicht gespeichert werden. Pflichtfeld-Angaben fehlen.
500: Dokument konnte nicht gespeichert werden.
Request: Dokumente (virtueller Aushang) löschen
Um Dokumente löschen zu können, muss eine eindeutige externe ID zum Dokument übergeben werden.
| Datenfeld | Standard-Wert | Beispiel-Wert(e) | Datentyp | Pflichtfeld | Beschreibung |
|---|---|---|---|---|---|
| ACTION | VIRTUELLER_AUSHANG_DOKUMENT_LOESCHEN | VIRTUELLER_AUSHANG_DOKUMENT_LOESCHEN | VARCHAR | ja | Angabe, welche Aktion ausgeführt wird |
| DOKUMENT_ID_EXTERN | 123 | INTEGER | ja | Eindeutige externe ID zum Dokument |
Status-Codes
201: Dokument Externe ID erfolgreich geloescht.
400: Dokument Externe ID konnte nicht geloescht werden. Pflichtfeld-Angaben fehlen.
500: Dokument Externe ID konnte nicht geloescht werden.
Request: Kennzeichen setzen
Über diese Funktion können entsprechende Kennzeichen der Teilnehmer gesetzt werden. Dabei werden die bestehenden Kennzeichen immer durch den aktuellen Wert überschrieben.
| Datenfeld | Standard-Wert | Beispiel-Wert(e) | Datentyp | Pflichtfeld | Beschreibung |
|---|---|---|---|---|---|
| ACTION | KENNZEICHEN_SETZEN | KENNZEICHEN_SETZEN | VARCHAR | ja | Angabe, welche Aktion ausgeführt wird |
| KENNZEICHEN_ART | KZ_DOKU_ABNAHME_ERLEDIGT KZ_TECHN_ABNAHME_ERLEDIGT KZ_STARTBERECHTIGT KZ_GESTARTET |
VARCHAR | ja | Art des Kennzeichens, welches gesetzt werden soll | |
| KENNZEICHEN_WERT | 1 | INTEGER | ja | 1=Kennzeichen setzen 0=Kennzeichen entfernen | |
| STARTNUMMER | 15 | INTEGER | ja | Startnummer des Teilnehmers , sofern keine Transpondernummer übermittelt wird | |
| TRANSPONDERNR | 15 | VARCHAR | ja | Transpondernummer des Teilnehmers, sofern keine Startnummer übermittelt wird |
Status-Codes
201: Kennzeichen-Art bei Teilnehmer-ID erfolgreich gespeichert.
400: Kennzeichen-Art konnte nicht gespeichert werden. Kennzeichen-Art unbekannt.
400: Kennzeichen-Art konnte nicht gespeichert werden. Pflichtfeld-Angaben fehlen.
500: Kennzeichen-Art konnte nicht gespeichert werden.
Sonstige Hinweise
- Als LAP=0 kann eine Gesamt-Fahrzeit übermittelt werden
- Als LAP=1-n können einzelne Rundenzeiten übermittelt werden
- Der Status (z.B. 2=DNF) für einen Lauf ist der LAP=0 zuzuweisen
Version
1.4 | Stand: 03.07.2023