Aktionen

API: Unterschied zwischen den Versionen

Aus TW-Sportsoft Wiki (Online-Dokumentation)
 
(66 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 (Startzeiten, 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 Administrationsbereich 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 />
 
<br />
 +
Rechtzeitig vor der Veranstaltung sollten entsprechende Tests mit dem Veranstaltungssystem durchgeführt 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|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 25: 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 41: 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 58: 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 64: 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 90: 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 115: 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 123: 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 137: 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 156: 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 163: 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 183: 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===
Zeile 205: 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“