API

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.) müssen somit nicht manuell erfasst werden, sondern könnten automatisch über diese Schnittstelle an das System übertragen werden.

Voraussetzungen

1. Es muss eine Installation des Veranstaltungssystems mit den Modulen „Online-Nennung“ und „Auswertung“ vorhanden sein.
2. Alle Teilnehmer-Daten müssen mit Startnummern oder Transpondernummern, Wertungsgruppen/Klassen angelegt sein.
3. Das Gateway für die API muss über den Systemparameter im Administrationsbereich (Menüpunkt Parameter->Auswertung) der Veranstaltung geöffnet werden.
4. 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 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',
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 DMSB) zu senden: https://www.dmsb-sport.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	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
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
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
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
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
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
KENNZEICHEN_ART		KZ_DOKU_ABNAHME_ERLEDIGT KZ_TECHN_ABNAHME_ERLEDIGT KZ_STARTBERECHTIGT KZ_GESTARTET KZ_ZIELANKUNFT KZ_PARC_FERME KZ_AUSWERTUNG_STATUS	VARCHAR	ja	Art des Kennzeichens, welches gesetzt werden soll
KENNZEICHEN_WERT		1	INTEGER		1=Kennzeichen setzen 0=Kennzeichen entfernen Besonderheit bei KZ_AUSWERTUNG_STATUS: 1= DNS 2= DNF 3=DNC 4=DIS
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