Setzt den Kilometerstand für ein Fahrzeug. Beschreibung vehicle_settings/set_odometer.php?company=COMPANY_RTIKEY&vehicle=VEHICLE_RTIKEY&odometer=ODOMETER
Bei dieser Funktion handelt es sich um einen zweistufigen Aufruf. Es muss zunächst der gewünschte Kilometerstand geschickt werden. Das System validiert daraufhin diese Eingabe und gibt den berechneten Korrekturfaktor und einen Hash zu Bestätigung zurück. Dieser Hash muss innerhalb der nächsten 5 Minuten zurückgeschickt werden, um die Änderung zu bestätigen und den Kilometerstand an die Box zu übermitteln. Voraussetzungen und BeschränkungenEin manuell gesetzter Kilometerstand wird grundlegend von allen Boxen unterstützt, die in der Lage sind, GPS-basiert einen Kilometerstand zu erfassen. Dazu gehören YellowTracker 100 bis 620, sowie auch der YellowTracker mobile Xtreme. Ausgeschlossen sind OEM Anbindungen oder auch Mobile Apps. Einige Boxen unterstützen auch eine Kilometerstandserfassung über Digitacho oder Squarell. Wurde bei solch einer Box die Kilometerstandsquelle auf etwas anderes als GPS gesetzt, so kann kein manueller Kilometerstand mehr gesetzt werdewerden. Prinzipiell sind diese Quellen für einen genauen Kilometerstand zu bevorzugen. Die Kilometerstandsquelle können Sie im Portal über die fahrzeugbezogenen Einstellungen setzen. Parameter| Parameter | Beschreibung | Typ | Hinweis | Pflicht |
|---|
| company | RTI Firmenschlüssel | string |
| ja | | vehicle | RTI Fahrzeugschlüssel | string |
| ja | | odometer | Kilometerstand | integer | Kilometerstand der gesetzt werden soll Pflicht für die erste Anfrage | (ja) | | hash | Hash zur Bestätigung der Anfrage | string | Pflicht für die zweite Anfrage zu Bestätigung des Kilometerstandes | (ja) |
RückgabeEs wird ein string zurückgegeben. Im Fehlerfall wird "ERROR:Beschreibung" zurückgegeben. Mögliche Fehlerwerte| Fehler | Beschreibung |
|---|
| MISSING_VEHICLE | Die Angabe des Fahrzeuges ist Pflicht. | | INVALID_FORMAT_ODOMETER | Es wurde ein Kilometerstand übermittelt, der nicht dem erwarteten Format entspricht. Der Kilometerstand muss eine Ganzzahl sein. | | CAN_NOT_PROCESS_HASH_AND_ODOMETER_AT_ONCE | Es wurde sowohl ein Hash, als auch ein Kilometerstand angegeben. Bitte geben Sie nur eines von beidem an. | | INCOMPLETE_REQUEST_PARAMS | Es wurde weder ein Hash, noch ein Kilometerstand angegeben. Bitte geben Sie eines von beiden mit. | | NOT_SUPPORTED_BY_VEHICLE | Das angegebene Fahrzeug unterstützt keine manuellen Kilometerstände. Das kann am Boxtyp liegen oder aber es ist eine andere Kilometerstandsquelle als GPS angegeben. | | LAST_SET_ODOMETER_LESS_THAN_10_MINUTES_AGO | Ein manueller Kilometerstand kann maximal alle 10 Minuten übermittelt werden. | | SET_COMMAND_ALREADY_IN_PROCESS | Ein manueller Kilometerstand befindet sich aktuell noch in der Warteschlange. Sie müssen warten, bis dieser Befehl verarbeitet wurde. | | INVALID_CURRENT_ODOMETER | Der aktuelle Kilometerstand des Fahrzeuges ist invalide. Das heißt, dass er niedriger ist, als die letzte manuelle Anpassung. Wahrscheinlich hat sich das Fahrzeug seitdem noch nicht wieder bewegt. Erst mit der ersten Positionsmeldung wurde der letzte Angleich vollständig verarbeitet. | | NEW_ODOMETER_CAN_NOT_BE_LESS_THAN_LAST_ODOMETER | Der neue Kilometerstand kann nicht niedriger als der letzte manuelle Kilometerstand sein. |
JSONErklärung der Felder| Feld | Beschreibung |
|---|
| status | Mögiche Werte: - NEED_COMMIT: Der Kilometerstand wurde angegeben und erfolgreich validiert. Er muss noch bestätigt werden.
- OK: Der Kilometerstand wurde bestätigt und an die Box übermittelt.
| | queryDate | Wann wurde diese Anfrage übermittelt? | | odometer | - current: Aktueller Kilometerstand laut Positionsmeldungen
- new: übermittelter Kilometerstand
| | correctionFactor | GPS Ortung als Quelle für den Kilometerstand kann zu Abweichungen gegenüber dem realen Kilometerstand führen. Der Korrekturfaktor gibt an, um viel der Kilometerstand automatisch gestreckt/gestaucht wird, um Abweichungen langfristig entgegen zu wirken. Jede Box besitzt einen festen Korrekturfaktor, welcher mit jeder Positionsmeldung verrechnet wird. Eine Anpassung des Kilometerstandes verrechnet die aufgezeichneten Kilometerstände ebenfalls mit einem Korrekturfaktor um die Meldungen gleichmäßig anzupassen. - current: fester Korrekturfaktor der Box
- calculated: berechneter Korrekturfaktor um alle betroffenen Positionsmeldungen auf den gewünschten aktuellen Kilometerstand anzupassen
- suggested: vorgeschlagener fester Korrekturfaktor auf Basis des aktuellen Faktors und des berechneten, um perspektivisch eine weitere Anpassung zu vermeiden
| | commandInfo | Infotext was passieren wird, wenn dieser Kilometerstand bestätigt wird. Es können 2 Fälle eintreten: - alle Meldungen zwischen der letzten und dieser Anpassung werden angepasst
- die letzte bekannte Meldung ist die letzte Anpassung - es müssen keine Positionsmeldungen angepasst werden, der Kilometerstand wird hart gesetzt
| | hash | Hash der übermittelt werden muss um die Anfrage zu bestätigen |
Beispiel| Rückgabe als JSON |
|---|
{ "status": "NEED_COMMIT | OK", "queryDate": "2023-05-24T09:16:47+0200", "odometer": { "current": 5015, "new": 6000 }, "correctionFactor": { "current": 1, "calculated": 1.1964107676969, "suggested": 1.1964107676969 }, "commandInfo": { "status": 2, "text": "Applying this odometer will change all position messages since last set odometer by the calculated correction factor." }, "hash": "6DFB2C5F9A552C014135CBDAFD09CE81" } |
BeispielaufrufeAnfrage 1: Angabe Kilometerstand| Code Block |
|---|
https://map.yellowfox.de/rti/vehicle_settings/set_odometer.php?company=COMPANY_RTIKEY&vehicle=VEHICLE_RTIKEY&odometer=12000
https://map.yellowfox.de/rti/vehicle_settings/set_odometer.php?company=COMPANY_RTIKEY&vehicle={"type":"car_ident","groupKey":"GROUP_RTIKEY","ident":"VEHICLE_IDENT"}&odometer=12000 |
Anfrage 2: Bestätigung des angegebenen Kilometerstands| Code Block |
|---|
https://map.yellowfox.de/rti/vehicle_settings/set_odometer.php?company=COMPANY_RTIKEY&vehicle=VEHICLE_RTIKEY&hash=3785678916
https://map.yellowfox.de/rti/vehicle_settings/set_odometer.php?company=COMPANY_RTIKEY&vehicle={"type":"car_ident","groupKey":"GROUP_RTIKEY","ident":"VEHICLE_IDENT"}&hash=3785678916 |
|