Aktionen

API

Aus TW-Sportsoft Wiki (Online-Dokumentation)

Version vom 3. Juli 2023, 13:44 Uhr von Timoweigert (Diskussion | Beiträge)

(Unterschied) ← Nächstältere Version | Aktuelle Version (Unterschied) | Nächstjüngere Version → (Unterschied)

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

  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 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
KZ_ZIELANKUNFT
KZ_PARC_FERME
KZ_AUSWERTUNG_DNF
KZ_AUSWERTUNG_DNC
KZ_AUSWERTUNG_DIS

 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

Abgerufen von „https://www.tw-sportsoft-wiki.de/index.php?title=API&oldid=2322“