Grundlegende Telematikfunktionen von YellowFox werden externen Programmen zugänglich gemacht.

Allgemein

Der Nutzer der Schnittstelle wird einen Befehl an den Webserver senden und erhält dabei eine Antwort zurück. Die Übertragung der Nutzdaten erfolgt über das Protokoll http bzw. https, so dass normalerweise keinerlei Anpassungen im IT-Equipment des Kunden notwendig sind. Das Remote Tracking Interface (RTI) erhält dabei eine speziell formatierte Anfrage und beantwortet diese mit dem Ergebnis des auf die Anfrage hin ausgeführten Befehls. Das RTI agiert dabei immer nur auf eine Anfrage. Es kann weder Daten von selber versenden noch ohne Zutun des Kunden von allein tätig werden.

Das RTI lässt sich z.B. für folgende Dinge nutzen:

• Abfrage von Fahrzeugstandorten
• Änderung von trackingeinstellungen
• Konfiguration von Hardwarezubehör wie Displays
• Versenden von Aufträgen
• Empfangen von Auftragsstatusmeldungen
• Versenden und Empfangen von Textnachrichten

Die Funktionen des RTI können auf einfachste Weise mit Anwendungen wie Google Earth getestet werden.

Aktivierung

Das RTI wird durch den Support bzw. Innendienst freigeschaltet. Kontaktieren Sie uns einfach an um dieses Modul für sich freizuschalten. Im Portal können Sie dann unter Extras -> RTI (Schnittstelle) RTI Schlüssel für Ihre Firma und den zugehörigen Fuhrpark erzeugen. Diese dienen dann als Authentifizierung.

Basisadressierung

Basisadresse für alle Abfragen ist http://map.yellowfox.de/rti/ bzw https://map.yellowfox.de/rti/

Beschreibung der Funktionsweise

Folgende Parameter sind für die Anmeldung an YellowFox wichtig:

Die Authentifizierung an der RTI Schnittstelle erfolgt über RTI Schlüssel. Diese finden Sie im Portal unter Extras → RTI Schnittstelle. Ihr Zugang besitzt zwei zentrale Schlüssel: den Firmenschlüssel und den Importschlüssel. Weiterhin können Sie für jedes Fahrzeug und jede Fahrzeuggruppe einen eigenen Schlüssel erzeugen. Je nach RTI Funktion benötigen Sie eine bestimmte Kombi an Schlüsseln. Informationen dazu finden Sie in der Beschreibung der jeweiligen Funktion. Die Schlüssel sind pro Firma eindeutig.

Bei RTI Schlüsseln handelt es sich um einen Hexadezimal Schlüssel. Dieser wird zufällig generiert und kann beliebig oft neu erstellt werden. Für Fahrzeuge haben Sie optional auch die Möglichkeit eigene RTI Idents zu vergeben. Diese sind jedoch ausschließlich in einer 2-stufigen Authentifizierung nutzbar.

RTI Schlüssel müssen bei jeder Anfrage mitgegeben werden, Sie sind jedoch nicht in der jeweiligen Antwort enthalten. 

Folgende Schlüssel sind für die Anmeldung an YellowFox wichtig:

• company: Dieser Schlüssel muss immer angegeben werden und identifiziert Ihren Firmenzugang.
• import: Hierbei handelt es sich um eine Art Universalschlüssel. Dieser kann genutzt werden um neue Daten über die Schnittstelle einzupflegen oder auch um Daten zu allen Fahrzeugen abzurufen.
• vehicle: Identifiziert ein einzelnes Fahrzeug. Kann auf unterschiedliche Art und Weisen angegeben werden:
• company, als HEXadezimalKey auszuführen, kann vom Kunden selber neu generiert werden. Dieser Key wird in jeder Anfrage mitgesendet. Antworten enthalten diesen Key nicht. Der Key dient zur Authentifizierung. Dieser Key wird pro Kunde generiert und enthält unter anderem die Firmenid
• vehicle, als HEXadezimalKey auszuführen, kann vom Kunden selber neu generiert werden. Dieser Key wird bei Anfragen die Fahrzeuge betreffen mitgesendet. Antworten enthalten diesen Key nicht. Der Key dient als Fahrzeugkennung. Dieser Key wird pro Fahrzeug generiert.
• RTI Ident Authentifizierung vehicle Parameter mit folgendem JSON Aufbau vehicle=
  • als Standard RTI Schlüssel
  • per RTI Ident: Hierbei handelt es sich um eine 2-stufige Authentifizierung. Zusätzlich muss ein passender Fahrzeuggruppenschlüssel angegeben werden.
    • Format: 
  • • {"type":"car_ident","groupKey": "RTI_GROUP_KEY","ident": "RTI_IDENT"}

• group, als HEXadezimalKey auszuführen, kann vom Kunden selber neu generiert werden. Dieser Key wird bei Anfragen die Fahrzeuggruppen betreffen mitgesendet. Antworten enthalten diesen Key nicht. Der Key dient als Fahrzeugkennung oder Gruppenkennung. Dieser Key wird pro Gruppe generiert.: Identifiziert eine Fahrzeuggruppe und alle darin enthaltenen Fahrzeuge, welche selbst einen RTI Schlüssel besitzen. Wenn Sie einen Gruppenschlüssel verwenden, stellen Sie sicher, dass jedes Fahrzeug dieser Gruppe auch einen Fahrzeugschlüssel hat! 

• Datumsstempel, um Caching der Befehlsanfrage zu vermeiden.

Ausführung als ?company=HEXKEY&vehicle=HEXKEY2

Fehlerwerte

Bei der Rückgabe "ERROR:Text" enthält "Text" die Fehlerbeschreibung. Mögliche Fehlercodes finden Sie hier.

Goal of this application is to provide the basic tracking functionality of YellowFox to third party software. Easy use and strong security were scopes during development.

Common

Goal of this application is to provide the basic tracking functionality of YellowFox to third party software. Easy use and strong security were scopes during development. The user send commands via http to servers and receives the answers, positions, maps via the same way.

RTI can be used for example to:

• Query of vehicle positions
• change of tracking settings
• configuration of displays
• send orders and messages
• receive order states

Activation

RTI must be activated from our support. Please feel free to contact them. You can then access the rti interface settings via extras → rti interface. There you are able to generate the needed keys for authentication.

Base address

http://map.yellowfox.de/rti/ or https://map.yellowfox.de/rti/

Description of functioning

Following paramater are mandatory to authentificate with YellowFox:

The authentication at rti interface is realized by rti keys. You can find these in the user portal via extras → rti interface. Your access owns two central keys: the company key and the import key. Furthermore you are able to generate an own key for each vehicle and vehicle group. Depending on the rti function, you will need a specific combination of keys. You can find information about that in the documentation of the respective function. The keys are distinct per company.

A rti key is a hexadecimal key. It will be generated at random and can be re-generated as often as you want. For vehicles you might also generate a custom rti ident, but these can only be used via 2-step authentication.

Rti keys have to be send with each request. They are not included in the responses.

Following keys are important to login via YellowFox:

• company: This key is always mandatory. It identifies your company.
• import: This is kind of an universal key. It can be used to insert new data via the interface or access data of all vehicles.
• vehicle: Identifies a single vehicle. Can be given in multiple formats:
  • as basic rti key
  • as rti ident: This is a 2-step authentication. Additionally you have to add a matching group key.
    • format: 

• • • {"type":"car_ident","groupKey": "RTI_GROUP_KEY","ident": "RTI_IDENT"}
• group: Identifies a vehicle group and all vehicles assigned to it,

• as far as they own a rti key themselves. If you use a group key

• make sure that all vehicles you want to access have a rti key!

• Date, to prevent caching

Execute as ?company=HEXKEY&vehicle=HEXKEY2

Error codes

If "ERROR:Text" is returned. "Text" contains the error description. Possible error codes ca you find You can find possible error codes  here.