API
Aus TW-Sportsoft Wiki (Online-Dokumentation)
Inhaltsverzeichnis
Einleitung
Über die TW-Sportsoft API (Gateway-Schnittstelle) können externe Systeme angeschlossen werden.
Extern anfallende Daten z.B. aus dem Bereich Auswertung/Zeitnahme (Startzeiten, Zielzeiten, Fahrzeiten, Strafzeiten, Meldungen etc.) 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->Global) der Veranstaltung geöffnet werden.
- Ein API-Key muss über den Systemparameter im Administrationsbereich (Menüpunkt Parameter->Global) der Veranstaltung geöffnet werden.
- Die eindeutige Veranstaltungsid muss bekannt sein. Ersichtlich auf der Startseite (Cockpit) des Admin-Bereiches des Veranstaltungssystems.
Rechtzeitig vor der Veranstaltung sollten entsprechende Tests und eine Probe-Auswertung 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.
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',
VERANSTALTUNG_ID: '123456789',
WP_LAUF_NR: '1',
ART: 'FAHRZEIT',
ZEIT: '320.6',
STARTNUMMER: '5'
};
//Request an API senden
$.ajax({
url: 'https://www.tw-sportsoft.de/API/index.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/api/api.php
Die Daten sind an folgende API-URL (Systemherkunft DMSB) zu senden: https://www.dmsb-sport.de/api/api.php
Die Daten sind an folgende API-URL (Systemherkunft ADAC Sportabteilung) zu senden: https://www.adac-sport.com/api/api.php
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 |
| VERANSTALTUNG_ID | 4711 | INTEGER | ja | Eindeutige Veranstaltungsid | |
| WP_LAUF_NR | 1 | INTEGER | ja | Nummer der WP/Lauf | |
| LAP | 1 | INTEGER | nein | Rundenzahl | |
| ART | START, ZIEL, FAHRZEIT | VARCHAR | ja | Art der gesendeten Zeit. Startzeit, Zielzeit oder Fahrzeit | |
| 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 |
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 |
| VERANSTALTUNG_ID | 4711 | INTEGER | ja | Eindeutige Veranstaltungsid | |
| WP_LAUF_NR | 1 | INTEGER | ja | Nummer der WP/Lauf | |
| ART | START, ZIEL, FAHRZEIT | VARCHAR | ja | Art der gesendeten Zeit. Startzeit, Zielzeit oder Fahrzeit | |
| 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 |
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 |
| VERANSTALTUNG_ID | 4711 | INTEGER | ja | Eindeutige Veranstaltungsid | |
| 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 |
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 |
| VERANSTALTUNG_ID | 4711 | INTEGER | ja | Eindeutige Veranstaltungsid | |
| WP_NR | 1 | INTEGER | ja | Nummer der WP/Lauf | |
| ZEIT | 10.0 | DECIMAL(6,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 |
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 |
| VERANSTALTUNG_ID | 4711 | INTEGER | ja | Eindeutige Veranstaltungsid | |
| 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 | Kennzeichen, ob die Meldung öffentlich angezeigt werden soll oder nur eine interne Information an die Leitstelle ist | |
| MELDUNG_ID | 12345 | INTEGER | nein | Externe ID der gesendeten Meldung |
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 |
| VERANSTALTUNG_ID | 4711 | INTEGER | ja | Eindeutige Veranstaltungsid | |
| MELDUNGART_ID | 3 | INTEGER | ja | 1=Zeitstrafe 2=Unfall 3=Technischer Defekt 4=Information 5=Sonstiges | |
| 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 | |
| MELDUNG_ID | 12345 | INTEGER | ja/nein | Externe ID der gesendeten Meldung |
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 |
| VERANSTALTUNG_ID | 4711 | INTEGER | ja | Eindeutige Veranstaltungsid | |
| 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 | 1=Kennzeichen setzen 0=Kennzeichen entfernen
| ||
| WP_LAUF_NR | 1 | INTEGER | ja/nein | Nummer der Wertungsprüfung/Lauf, sofern Zuordnung möglich. Z.B. Ausfall nach Lauf 2 | |
| STARTNUMMER | 15 | INTEGER | nein | Startnummer des Teilnehmers , sofern keine Transpondernummer übermittelt wird | |
| TRANSPONDERNR | 15 | VARCHAR | nein | Transpondernummer des Teilnehmers, sofern keine Startnummer übermittelt wird |