# GPS Devices


This documentation helps GPS Providers to send their data to Zarv's platform.

Check here how to authenticate

# API Fields

Field Type Description
device.id required String Device IMEI
device.status required String Command status ENUM
device.gsm_signal required Number GSM RSSI Signal Value Description
device.gps_satellites Number Total availability GPS satellites
vehicle.vin required String Vehicle VIN Description
vehicle.license_plate String Vehicle's License Plate
vehicle.engine_status required String Engine status (ON/OFF)
vehicle.speed required Number Speed value in Km/h
vehicle.odometer required Number Vehicle odomether in Km
vehicle.battery.system required Number Vehicle battery voltage
vehicle.battery.device Number Device battery voltage
vehicle.battery.device_percentage Number Device battery percentage
vehicle.location.elevation Number Vehicle elevation in meters
vehicle.location.heading Number Vehicle heading in degrees
vehicle.location.location required Array [longitude, latitude]
vehicle.behavior String One of available behaviours
received_at String Date of the event received by the platform in UTC ISO
created_at required String Date of the event in UTC ISO

# Available API Enums

# Vehicle VIN

  • The NIV - Número de Identificação do Veículo, or VIN - Vehicle Identification Number, is the universal registration system for automotive vehicles that are produced.

# Gsm RSSI

RSSI Signal strength Description
-70 dBm to -85 dBm Good Strong signal with good data speeds
-86 dBm to -100 dBm Fair Fair but useful, fast and reliable data speeds may be attained, but marginal data with drop-outs is possible
< -100 dBm Poor Performance will drop drastically
-110 dBm No signal Disconnection
Status Description
LOCKED Vehicle is locked
OPERATIONAL Vehicle is unlocked and working well
SETUP Device not installed
SOFT_LOCK_RECEIVED Soft lock command received by the device
SOFT_LOCK_APPLYING Applying to device soft lock command
SOFT_LOCK_CONFIRMED Device soft lock command finished
HARD_LOCK_RECEIVED Hard lock command received by the device
HARD_LOCK_APPLYING Applying to device hard lock command
HARD_LOCK_CONFIRMED Device hard lock command finished
UNLOCK_RECEIVED Unlock command received by the device
UNLOCK_APPLYING Applying to device unlock command
UNLOCK_CONFIRMED Device unlock command finished
Status Description
DEVICE_POWER_ON Power return to the device
DEVICE_VOIDED Device voided, light sensor activated or device moved detected
DEVICE_VIOLATED_ENERGY Device voided, voltage readings of vehicle battery or device battery tempered
ENGINE_ON Ignition on
ENGINE_OFF Ignition off
SOFT_ACCELERATION Light Acceleration
HARD_ACCELERATION Sharp Acceleration
SOFT_BREAK Light braking
HARD_BREAK Hard braking
SOFT_TURN Light turn
HARD_TURN Hard turn
TOKEN_EXPIRED Expired driver token
TRIP_START Beginning of route
TRIP_END End of route

# Payload Example

  "device": {
    "status": "OPERATIONAL",
    "gsm_signal": -72,
    "gps_satellites": 8
  "vehicle": {
    "vin": "4Y1SL65848Z411430",
    "license_plate": "ZRV2A23",
    "behavior": "ENGINE_ON",
    "engine_status": "ON",
    "speed": 12,
    "odometer": 124,
    "battery": {
      "system": 12.707,
      "device": 4.166,
      "device_percentage": 100
    "location": {
      "elevation": 143,
      "heading": 24,
      "location": [-27.607124, -48.5752832]
  "received_at": "2023-01-02T12:23:02Z",
  "created_at": "2023-01-02T12:23:02Z"

# Responses for successful requests

Status code: 202

  "status": "success",
  "stage": "prod"

# Responses for non successful requests

Status code: 400


  "contract": "gps",
  "validations": [
			"instancePath": "/vehicle",
			"schemaPath": "#/properties/vehicle/required",
			"keyword": "required",
			"params": {
				"missingProperty": "X"
			"message": "deve ter a propriedade obrigatória X"