Aktionen

API: Unterschied zwischen den Versionen

Aus TW-Sportsoft Wiki (Online-Dokumentation)
 
(70 dazwischenliegende Versionen desselben Benutzers werden nicht angezeigt)
Zeile 1: Zeile 1:
 
== Einleitung ==
 
== Einleitung ==
−
Über die TW-Sportsoft API (Gateway-Schnittstelle) können externe Systeme angeschlossen werden.
+
Über die TW-Sportsoft API (offene Schnittstelle) können externe Systeme angeschlossen werden.  
−
 
 
−
Extern anfallende Daten z.B. aus dem Bereich Auswertung/Zeitnahme (Startartzeiten, Zielzeiten, Fahrzeiten, Strafzeiten, Meldungen etc.) müssen somit nicht manuell erfasst werden, sondern könnten automatisch über diese Schnittstelle in das System übertragen 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 ==
 
== Voraussetzungen ==
  
 
# Es muss eine Installation des Veranstaltungssystems mit den Modulen „Online-Nennung“ und „Auswertung“ vorhanden sein.
 
# Es muss eine Installation des Veranstaltungssystems mit den Modulen „Online-Nennung“ und „Auswertung“ vorhanden sein.
−
# Alle Teilnehmer-Daten müssen mit Startnummern, Wertungsgruppen/Klassen und ggf. Prädikatszuordnungen angelegt sein.
+
# Alle [[Nennungen Teilnehmer|Teilnehmer-Daten]] müssen mit Startnummern oder Transpondernummern, Wertungsgruppen/Klassen angelegt sein.
−
# Das Gateway muss über den Systemparameter im Administrationsbereichs der Veranstaltung geöffnet werden.
+
# Das Gateway für die API muss über den Systemparameter im Administrationsbereich (Menüpunkt [[Parameter Auswertung|Parameter->Auswertung]]) der Veranstaltung geöffnet werden.
−
# Die eindeutige Veranstaltungsid muss bekannt sein. Ersichtlich auf der Startseite (Cockpit) des Admin-Bereiches des Veranstaltungssystems.
+
# Ein API-Key im Administrationsbereich unter dem (Menüpunkt [[Parameter Auswertung|Parameter->Auswertung]]) hinterlegt werden. Ohne API-Key kann mit der API nicht kommuniziert werden.
−
 
+
<br />
−
Rechtzeitig vor der Veranstaltung sollten entsprechende Tests und eine Probe-Auswertung mit dem Veranstaltungssystem durchgeführt 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|Parameter->Global]] im Veranstaltungssystem. Achten Sie auf die korrekte Groß-/Kleinschreibung.<br />
 +
'''Status-Code'''<br/>
 +
401: API-Key nicht korrekt oder API inaktiv. Parameter -> Auswertung im Veranstaltungssystem pruefen.<br/>
  
 
== Technik ==
 
== Technik ==
Zeile 24: Zeile 27:
 
<nowiki>//Daten</nowiki><br />
 
<nowiki>//Daten</nowiki><br />
 
<nowiki>var data = {</nowiki><br />
 
<nowiki>var data = {</nowiki><br />
−
<nowiki>            ACTION: 'WP_ZEIT_SPEICHERN',</nowiki><br />
+
<nowiki>            API_KEY: 'gb8kme29swDpCd9Axd',</nowiki><br />
−
<nowiki>            VERANSTALTUNG_ID: '123456789',</nowiki><br />
+
<nowiki>            ACTION: 'ZEIT_SPEICHERN',</nowiki><br />
−
<nowiki>            WP_NR: '1',</nowiki><br />
+
<nowiki>            WP_LAUF_NR: '1',</nowiki><br />
 
<nowiki>            ART: 'FAHRZEIT',</nowiki><br />
 
<nowiki>            ART: 'FAHRZEIT',</nowiki><br />
 
<nowiki>            ZEIT: '320.6',</nowiki><br />
 
<nowiki>            ZEIT: '320.6',</nowiki><br />
 
<nowiki>            STARTNUMMER: '5'</nowiki><br />
 
<nowiki>            STARTNUMMER: '5'</nowiki><br />
 
<nowiki>            };</nowiki><br />
 
<nowiki>            };</nowiki><br />
−
<nowiki>//Request an Gateway senden</nowiki><br />
+
<nowiki>//Request an API senden</nowiki><br />
 
<nowiki>$.ajax({</nowiki><br />
 
<nowiki>$.ajax({</nowiki><br />
−
<nowiki>        url: 'https://www.tw-sportsoft.de/GATEWAY/index.php',</nowiki><br />
+
<nowiki>        url: 'https://www.tw-sportsoft.de/MUSTER_VERANSTALTUNG/api.php',</nowiki><br />
 
<nowiki>        type: 'POST',</nowiki><br />
 
<nowiki>        type: 'POST',</nowiki><br />
 
<nowiki>        data: data</nowiki><br />
 
<nowiki>        data: data</nowiki><br />
Zeile 40: Zeile 43:
 
<nowiki></script></nowiki><br />
 
<nowiki></script></nowiki><br />
  
−
=== Gateway ===  
+
=== API-URL (Gateway) ===  
−
 
 
−
Die Daten sind an folgende Gateway-URL (Systemherkunft TW-Sportsoft) zu senden:
 
−
https://www.tw-sportsoft.de/GATEWAY/index.php 
 
  
−
Die Daten sind an folgende Gateway-URL (Systemherkunft DMSB) zu senden:  
+
Die Daten sind an folgende API-URL (Systemherkunft TW-Sportsoft) zu senden:  
−
https://www.dmsb-sport.de/GATEWAY/index.php   
+
https://www.tw-sportsoft.de/MUSTER_VERANSTALTUNG/api.php   
  
−
Die Daten sind an folgende Gateway-URL (Systemherkunft ADAC Sportabteilung) zu senden:  
+
Die Daten sind an folgende API-URL (Systemherkunft ADAC Sportabteilung) zu senden:  
−
https://www.adac-sport.com/GATEWAY/index.php   
+
https://www.adac-sport.com/MUSTER_VERANSTALTUNG/api.php   
  
 +
Den URL-Teil '''MUSTER_VERANSTALTUNG''' durch den Verzeichnisnamen der Veranstaltung ersetzen.
  
 
== Requests ==
 
== Requests ==
Zeile 57: Zeile 58:
  
 
Über diese Funktion werden Zeiten oder Status-Kennzeichen an das System gesendet.
 
Über diese Funktion werden Zeiten oder Status-Kennzeichen an das System gesendet.
−
Hinweis: Wird eine Zeit zu gleicher Veranstaltung, WP/Lauf-Nummer und Startnummer nochmals gesendet, so wird die vorherige Zeit automatisch überschrieben. Darüber können eventuelle Fehleingaben korrigiert werden.
+
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.
  
 
{| class="wikitable"
 
{| class="wikitable"
Zeile 63: Zeile 64:
 
! Datenfeld !! Standard-Wert!! Beispiel-Wert(e)!! Datentyp!! Pflichtfeld!! Beschreibung
 
! Datenfeld !! Standard-Wert!! Beispiel-Wert(e)!! Datentyp!! Pflichtfeld!! Beschreibung
 
|-
 
|-
−
| ACTION|| WP_ZEIT_SPEICHERN|| WP_ZEIT_SPEICHERN|| VARCHAR|| ja|| Angabe, welche Aktion ausgeführt wird
+
| API_KEY|| || gb8kme29swDpCd9Axd|| VARCHAR|| ja|| API-Key zur Autorisierung gegenüber der API
 
|-
 
|-
−
| VERANSTALTUNG_ID || ||4711 ||INTEGER || ja|| Eindeutige Veranstaltungsid
+
| ACTION|| ZEIT_SPEICHERN|| ZEIT_SPEICHERN|| VARCHAR|| ja|| Angabe, welche Aktion ausgeführt wird
 
|-
 
|-
−
| WP_NR || ||1||INTEGER || ja|| Nummer der WP/Lauf  
+
| WP_LAUF_NR || ||1||INTEGER || ja|| Nummer der WP/Lauf  
 
|-
 
|-
−
| LAP || ||1||INTEGER || nein|| Rundenzahl  
+
| LAP || ||1||INTEGER || nein|| Rundenzahl
 
|-
 
|-
−
| ART || ||START, ZIEL, FAHRZEIT ||VARCHAR || ja|| Art der gesendeten Zeit. Startzeit, Zielzeit oder Fahrzeit
+
| ART || ||START, <br />ZIEL,<br />FAHRZEIT, <br />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.  
+
| STATUS || Folgende Status-Werte können übermittelt werden. <br />1=DNS <br />2=DNF <br />3=DNC <br />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  
 
| ZEIT || ||43591.862 ||DECIMAL(9,3) || ja|| Die Zeit in Sekunden mit Nachkommastellen  
 
|-
 
|-
−
| STARTNUMMER || ||15||INTEGER|| ja|| Startnummer des Teilnehmers  
+
| 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'''<br/>
 +
201: Zeit erfolgreich gespeichert.<br/>
 +
500: Zeit konnte nicht gespeichert werden.<br/>
  
 
=== Request: Zeiten löschen===
 
=== Request: Zeiten löschen===
Zeile 89: Zeile 94:
 
! Datenfeld !! Standard-Wert!! Beispiel-Wert(e)!! Datentyp!! Pflichtfeld!! Beschreibung
 
! Datenfeld !! Standard-Wert!! Beispiel-Wert(e)!! Datentyp!! Pflichtfeld!! Beschreibung
 
|-
 
|-
−
| ACTION|| WP_ZEIT_LOESCHEN|| WP_ZEIT_LOESCHEN|| VARCHAR|| ja|| Angabe, welche Aktion ausgeführt wird
+
| 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
 
|-
 
|-
−
| WP_NR || ||1||INTEGER || ja|| Nummer der WP/Lauf
+
| ART || ||START, ZIEL, FAHRZEIT, STATUS  ||VARCHAR || ja|| Art der gesendeten Zeit. Startzeit, Zielzeit oder Fahrzeit
 
|-
 
|-
−
| ART || ||START, ZIEL, FAHRZEIT ||VARCHAR || ja|| Art der gesendeten Zeit. Startzeit, Zielzeit oder Fahrzeit
+
| STARTNUMMER || ||15||INTEGER|| ja|| Startnummer des Teilnehmers , sofern keine Transpondernummer übermittelt wird
−
|-
 
−
| ZEIT || ||43591.862 ||DECIMAL(9,3) || ja|| Die Zeit in Sekunden mit Nachkommastellen
 
 
|-
 
|-
−
| STARTNUMMER || ||15||INTEGER|| ja|| Startnummer des Teilnehmers  
+
| TRANSPONDERNR|| ||15||VARCHAR|| ja|| Transpondernummer des Teilnehmers, sofern keine Startnummer übermittelt wird
 
|}
 
|}
−
 
+
'''Status-Codes'''<br/>
 +
201: Zeit erfolgreich geloescht.<br/>
 +
500: Zeit konnte nicht geloescht werden.<br/>
  
 
=== Request: Strafzeiten speichern ===
 
=== Request: Strafzeiten speichern ===
  
 
Über diese Funktion werden Strafzeiten an das System gesendet.  
 
Über diese Funktion werden Strafzeiten an das System gesendet.  
−
Hinweis: Wird eine Strafzeiten zu gleicher Veranstaltung, WP/Lauf-Nummer und Startnummer nochmals gesendet, so wird die vorherige automatisch überschrieben. Darüber können eventuelle Fehleingaben korrigiert werden.  
+
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.  
  
 
{| class="wikitable"
 
{| class="wikitable"
Zeile 114: Zeile 119:
 
| ACTION|| STRAFZEIT_SPEICHERN || STRAFZEIT_SPEICHERN || VARCHAR|| ja|| Angabe, welche Aktion ausgeführt wird
 
| 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  
−
|-
 
−
| WP_NR || ||1||INTEGER || ja|| Nummer der WP/Lauf  
 
 
|-
 
|-
 
| ZEIT || ||10.0 ||DECIMAL(6,3) || ja|| Die Zeit in Sekunden mit Nachkommastellen  
 
| ZEIT || ||10.0 ||DECIMAL(6,3) || ja|| Die Zeit in Sekunden mit Nachkommastellen  
Zeile 122: Zeile 125:
 
| GRUND|| ||Frühstart ||VARCHAR(50)  || nein||Grund für die Strafzeit  
 
| GRUND|| ||Frühstart ||VARCHAR(50)  || nein||Grund für die Strafzeit  
 
|-
 
|-
−
| STARTNUMMER || ||15||INTEGER|| ja|| Startnummer des Teilnehmers  
+
| 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'''<br/>
 +
201: Strafzeit erfolgreich gespeichert.<br/>
 +
400: Strafzeit konnte nicht gespeichert werden. Pflichtfeld-Angaben fehlen.<br/>
 +
500: Strafzeit konnte nicht gespeichert werden.<br/>
  
 
=== Request: Strafzeiten löschen===
 
=== Request: Strafzeiten löschen===
Zeile 136: Zeile 144:
 
| ACTION|| STRAFZEIT_LOESCHEN  || STRAFZEIT_LOESCHEN  || VARCHAR|| ja|| Angabe, welche Aktion ausgeführt wird
 
| ACTION|| STRAFZEIT_LOESCHEN  || STRAFZEIT_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
 
|-
 
|-
−
| WP_NR || ||1||INTEGER || ja|| Nummer der WP/Lauf
+
| STARTNUMMER || ||15||INTEGER|| ja|| Startnummer des Teilnehmers , sofern keine Transpondernummer übermittelt wird
 
|-
 
|-
−
| ZEIT || ||10.0 ||DECIMAL(6,3) || ja|| Die Zeit in Sekunden mit Nachkommastellen
+
| TRANSPONDERNR|| ||15||VARCHAR|| ja|| Transpondernummer des Teilnehmers, sofern keine Startnummer übermittelt wird
−
|-
 
−
| STARTNUMMER || ||15||INTEGER|| ja|| Startnummer des Teilnehmers  
 
 
|}
 
|}
 +
'''Status-Codes'''<br/>
 +
201: Strafzeit erfolgreich geloescht.<br/>
 +
500: Strafzeit konnte nicht geloescht werden.<br/>
  
 
=== Request: Meldungen speichern===
 
=== Request: Meldungen speichern===
Zeile 154: Zeile 163:
 
|-
 
|-
 
| ACTION|| LEITSTELLE_MELDUNG_SPEICHERN || LEITSTELLE_MELDUNG_SPEICHERN || VARCHAR|| ja|| Angabe, welche Aktion ausgeführt wird
 
| 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  
 
| MELDUNGART_ID  || ||3||INTEGER || ja|| 1=Zeitstrafe 2=Unfall 3=Technischer Defekt 4=Information 5=Sonstiges  
Zeile 161: Zeile 168:
 
| MELDUNG  || ||Motorschaden ||VARCHAR(250) || ja|| Beschreibung der Meldung  
 
| MELDUNG  || ||Motorschaden ||VARCHAR(250) || ja|| Beschreibung der Meldung  
 
|-
 
|-
−
| WP_NR || ||1||INTEGER|| nein|| Nummer der WP/Lauf  
+
| WP_LAUF_NR || ||1||INTEGER|| nein|| Nummer der WP/Lauf  
 
|-
 
|-
−
| STARTNUMMER || ||15||INTEGER|| nein|| Startnummer des Teilnehmers  
+
| STARTNUMMER || ||15||INTEGER|| nein|| Startnummer des Teilnehmers , sofern keine Transpondernummer übermittelt wird
 
|-
 
|-
−
| KZ_OEFFENTLICH || ||0||INTEGER|| ja|| Kennzeichen, ob die Meldung öffentlich angezeigt werden soll oder nur eine interne Information an die Leitstelle ist
+
| 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 <br/> 0=nur eine interne Information an die Leitstelle
 
|-
 
|-
 
| MELDUNG_ID || ||12345||INTEGER|| nein|| Externe ID der gesendeten Meldung  
 
| MELDUNG_ID || ||12345||INTEGER|| nein|| Externe ID der gesendeten Meldung  
 
|}
 
|}
  
 +
'''Status-Codes'''<br/>
 +
201: Meldung erfolgreich gespeichert.<br/>
 +
400: Meldung konnte nicht gespeichert werden. Pflichtfeld-Angaben fehlen.<br/>
 +
500: Meldung konnte nicht gespeichert werden.<br/>
  
 
=== Request: Meldungen löschen===
 
=== 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.  
+
Ü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.  
  
 
{| class="wikitable"
 
{| class="wikitable"
Zeile 181: Zeile 194:
 
| ACTION|| LEITSTELLE_MELDUNG_LOESCHEN  || LEITSTELLE_MELDUNG_LOESCHEN  || VARCHAR|| ja|| Angabe, welche Aktion ausgeführt wird
 
| ACTION|| LEITSTELLE_MELDUNG_LOESCHEN  || LEITSTELLE_MELDUNG_LOESCHEN  || VARCHAR|| ja|| Angabe, welche Aktion ausgeführt wird
 
|-
 
|-
−
| VERANSTALTUNG_ID || ||4711 ||INTEGER || ja|| Eindeutige Veranstaltungsid
+
| MELDUNG_ID || ||12345||INTEGER|| ja|| Externe ID der gesendeten Meldung
 +
|}
 +
'''Status-Codes'''<br/>
 +
201: Meldung Externe ID erfolgreich geloescht.<br/>
 +
400: Meldung Externe ID konnte nicht geloescht werden. Pflichtfeld-Angaben fehlen.<br/>
 +
500: Meldung Externe ID konnte nicht geloescht werden.<br/>
 +
 
 +
=== Request: Dokumente (virtueller Aushang) speichern===
 +
 
 +
Über diese Funktion werden Dokumente für den virtuellen Aushang an das System gesendet.
 +
 
 +
{| class="wikitable"
 
|-
 
|-
−
| MELDUNGART_ID  || ||3||INTEGER || ja|| 1=Zeitstrafe 2=Unfall 3=Technischer Defekt 4=Information 5=Sonstiges
+
! 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 <br/> 0=Dokument nicht für die Zeitnahme relevant
 +
|-
 +
| KZ_GELDSTRAFE|| ||0||INTEGER|| nein|| 1=Dokument beinhaltet eine Geldstrafe <br/> 0=Dokument beinhaltet keine Geldstrafe
 +
|-
 +
| GELDSTRAFE_BETRAG|| ||0||DECIMAL(15,2)|| nein|| Betrag der Geldstrafe
 
|-
 
|-
−
| WP_NR || ||1||INTEGER|| ja/nein|| Nummer der Wertungsprüfung
+
| KZ_OEFFENTLICH || ||0||INTEGER|| ja|| 1=Kennzeichen, ob die Meldung öffentlich angezeigt werden soll <br/> 0=nur eine interne Information an die Leitstelle
 
|-
 
|-
−
| STARTNUMMER || ||15||INTEGER|| ja/nein|| Startnummer des Teilnehmers 
+
| EMAIL_TEILNEHMER_SENDEN|| ||1||INTEGER|| nein|| Kennzeichen für automatischen Versand des Dokumentes an den zugeordneten Teilnehmer
 
|-
 
|-
−
| MELDUNG_ID || ||12345||INTEGER|| ja/nein|| Externe ID der gesendeten Meldung
+
| KZ_PUSH_NOTIFICATION_SENDEN|| ||1||INTEGER|| nein|| Kennzeichen für automatischen Versand des Dokumentes an die App
 
|}
 
|}
 +
'''Status-Codes'''<br/>
 +
201: Dokument Externe ID erfolgreich gespeichert.<br/>
 +
400: Dokument konnte nicht gespeichert werden. Pflichtfeld-Angaben fehlen.<br/>
 +
500: Dokument  konnte nicht gespeichert werden.<br/>
 +
 +
 +
=== Request: Dokumente (virtueller Aushang) löschen===
  
 +
Um Dokumente löschen zu können, muss eine eindeutige externe ID zum Dokument übergeben werden.
 +
 +
{| class="wikitable"
 +
|-
 +
! 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'''<br/>
 +
201: Dokument Externe ID erfolgreich geloescht.<br/>
 +
400: Dokument Externe ID konnte nicht geloescht werden. Pflichtfeld-Angaben fehlen.<br/>
 +
500: Dokument Externe ID konnte nicht geloescht werden.<br/>
  
 
=== Request: Kennzeichen setzen===
 
=== 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.  
 
Über diese Funktion können entsprechende Kennzeichen der Teilnehmer gesetzt werden. Dabei werden die bestehenden Kennzeichen immer durch den aktuellen Wert überschrieben.  
−
 
  
 
{| class="wikitable"
 
{| class="wikitable"
Zeile 204: Zeile 286:
 
| ACTION|| KENNZEICHEN_SETZEN  || KENNZEICHEN_SETZEN  || VARCHAR|| ja|| Angabe, welche Aktion ausgeführt wird
 
| 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<br /> KZ_TECHN_ABNAHME_ERLEDIGT<br /> KZ_STARTBERECHTIGT <br />
−
|-
+
KZ_GESTARTET <br />
−
| 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  
+
KZ_ZIELANKUNFT <br />
 +
KZ_PARC_FERME <br />
 +
KZ_AUSWERTUNG_DNF<br />
 +
KZ_AUSWERTUNG_DNC<br />
 +
KZ_AUSWERTUNG_DIS<br />
 +
||VARCHAR|| ja|| Art des Kennzeichens, welches gesetzt werden soll  
 
|-
 
|-
−
| KENNZEICHEN_WERT  || ||1||INTEGER || || 1=Kennzeichen setzen 0=Kennzeichen entfernen Besonderheit bei KZ_AUSWERTUNG_STATUS:
+
| KENNZEICHEN_WERT  || ||1||INTEGER || ja || 1=Kennzeichen setzen <br/>0=Kennzeichen entfernen
−
1= DNS 2= DNF 3=DNC 4=DIS
 
 
|-
 
|-
−
| WP_NR || ||1||INTEGER|| ja/nein|| Nummer der Wertungsprüfung/Lauf, sofern Zuordnung möglich. Z.B. Ausfall nach WP2
+
| STARTNUMMER || ||15||INTEGER|| ja|| Startnummer des Teilnehmers , sofern keine Transpondernummer übermittelt wird
 
|-
 
|-
−
| STARTNUMMER || ||15||INTEGER|| ja/nein|| Startnummer des Teilnehmers
+
| TRANSPONDERNR|| ||15||VARCHAR|| ja|| Transpondernummer des Teilnehmers, sofern keine Startnummer übermittelt wird
 
|}
 
|}
 +
'''Status-Codes'''<br/>
 +
201: Kennzeichen-Art bei Teilnehmer-ID erfolgreich gespeichert.<br/>
 +
400: Kennzeichen-Art konnte nicht gespeichert werden. Kennzeichen-Art unbekannt.<br/>
 +
400: Kennzeichen-Art konnte nicht gespeichert werden. Pflichtfeld-Angaben fehlen.<br/>
 +
500: Kennzeichen-Art konnte nicht gespeichert werden.<br/>
 +
 +
== 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

Aktuelle Version vom 3. Juli 2023, 13:44 Uhr

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“