Versions Compared

Old Version 2

changes.mady.by.user YellowFox R&D

Saved on

compared with

New Version Current

changes.mady.by.user YellowFox R&D

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Sv translation
languagede

Grundlegende Telematikfunktionen von YellowFox

...

werden externen Programmen zugänglich gemacht

...

.

Panel
titleInhaltsverzeichnis

Table of Contents
 

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

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:
    • 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: 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.

Sv translation
languageen

Goal of this application is to provide the basic tracking functionality of YellowFox to third party software.

Panel
titleIndex

Table of Contents
 

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

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. You can find possible error codes  here.

...

 Fehlerwerte

Bei der Rückgabe "ERROR:Text" enthält "Text" die Fehlerbeschreibung. Mögliche Fehler:

Abarbeitungsfehler

 

  • ERROR_$Parameter (Parameter ist nicht korrekt)
  • ERROR_MISSING_$Parameter (Parameter fehlt)
  • ERROR_MISSING_COMPANY (Key zur Authentifizierung der Firma fehlt)
  • ERROR_MISSING_SESSIONKEY|VEHICLE|GROUP (Es wurde keiner von 3 möglichen Parametern übergeben)
  • ERROR_MISSING_SESSIONKEY (Der Parmater "sessionkey" fehlt)
  • ERROR_MISSING_VEHICLE (Der Parameter "vehicle" fehlt)
  • ERROR_MISSING_GROUP (Der Parameter "group" fehlt)
  • ERROR_MISSING_DISTANCE (Der Parameter "distance" fehlt)
  • ERROR_MISSING_CYCLE (Der Parameter "cycle" fehlt)
  • ERROR_MISSING_RADIUS (Der Parameter "radius" fehlt)
  • ERROR_MISSING_CUSTOMORDERID - Eigene Auftragsnummer fehlt
  • ERROR_MISSING_ORDERTEXT - Auftragstext fehlt
  • ERROR_ORDER_NUMBER_TOO_LONG(MAX_20_CHARS) - Eigene Auftragsnummer zu lang, maximal 20 Zeichen
  • ERROR_STREET_TOO_LONG(MAX_100_CHARS) - Straßenname zu lang, maximal 100 Zeichen
  • ERROR_HOUSENUMBER_TOO_LONG(MAX_100_CHARS) - Hausnummer zu lang, maximal 100 Zeichen
  • ERROR_ZIPCODE_TOO_LONG(MAX_10_CHARS)- Postleitzahl zu lang, maximal 10 Zeichen
  • ERROR_CITY_TOO_LONG(MAX_100_CHARS) - Stadt zu lang, maximal 100 Zeichen
  • ERROR_COUNTRY_TOO_LONG(MAX_100_CHARS) - Land zu lang, maximal 3 Zeichen
  • ERROR_LATITUDE_MISSING - Latitude Wert wurde nicht angegeben
  • ERROR_LONGITUDE_MISSING - Longitude Wert wurde nicht angegeben
  • ERROR_LATITUDE_NOT_NUMERIC - Latitude Wert muss eine Zahl sein
  • ERROR_LONGITUDE_NOT_NUMERIC - Longitude Wert muss eine Zahl sein
  • ERROR_LATITUDE_NOT_IN_VALID_RANGE(-90_TO_90) - Latitude muss im Bereich von -90 bis +90 liegen
  • ERROR_LONGITUDE_NOT_IN_VALID_RANGE(-90_TO_90) - Longitude muss im Bereich von -90 bis +90 liegen
  • ERROR_TARGET_TIME_IS_INVALID - Angegebens Datum hat nicht die richtige Länge
  • ERROR_TARGET_TIME_IS_NOT_A_DATE - Angegebenes Datum ist kein richtiges Datum
  • ERROR_FORMULAR_NOT_ALLOCATED_BY_VEHICLE - Angegebenes Formular wurde der Hardware nicht zugeordnet
  • ERROR_FORMULAR_NOT_SUPPORTED_BY_HARDWARE - Hardware unterstützt keine Aufträge mit angehängten benutzerdef. Formularen
  • ERROR_ORDER_TEXT_TOO_LONG(MAX_300_CHARS) - Auftragstext ist zu lang, maximal 300 Zeichen (ACHTUNG: Bei Garmins wird die erwartete Ankunftszeit und die Adresse an den Anfang der Nachricht gesetzt, dies verringert die maximale Anzahl der Zeichen für den Auftragstext)
  • ERROR_COMPANY (Authentifizierung der Firma fehlerhaft)
  • ERROR_VEHICLE (Es wurde eine ungültige Fahrzeugkennung übergeben)
  • ERROR_GROUP (Es wurde eine ungültige Fahrzeuggruppe übergeben)
  • ERROR_DISTANCE (Der Parameter "distance" ist fehlerhaft)
  • ERROR_CYCLE (Der Parameter "cycle" ist fehlerhaft)
  • ERROR_RADIUS (Der Parameter "radius" ist fehlerhaft)
  • ERROR_DUPLICATE_CUSTOMORDERID (Auftragsnummer mehrfach vorhanden, Aktion nicht ausführbar)
  • ERROR_ORDER_NOT_FOUND (Der Angeforderte Auftrag konnte nicht gefunden werden)
  • ERROR_TEXT_TOO_LONG (Auftragstext und eigene Auftragsnummer überschreiten die maximale Länge).
  • ERROR_GROUP_NOMEMBER (Die abgefragte Fahrzeuggruppe enthält keinerlei Fahrzeuge)
  • ERROR_MAINTENANCE (aus Wartungsgründen nicht verfügbar)
  • REQUEST_NOT_FOUND (interner Fehler)
  • ERROR_NOT_SUPPORTED_BY_HARDWARE (Die Hardware im Fahrzeug unterstützt diese Aktion nicht)

 

Serverfehler

...