servers: - url: https://api.astaraconnect.com description: Production API server - url: https://api-staging.astaraconnect.com description: Staging API server paths: /v1/vehicle/versions/motorizations: get: summary: Retrieves motorization types available. description: 'This endpoint allows you to retrieve details of the motorization types available. ' tags: - Vehicle Versions responses: '200': description: 'OK - The requested information has been retrieved successfully. ' content: application/json: schema: oneOf: - type: array items: $ref: '#/components/schemas/MotorizationSchema' /v1/vehicle/versions/fuel-types: get: summary: Retrieves fuel types available. description: 'This endpoint allows you to retrieve details of the fuel types available. ' tags: - Vehicle Versions responses: '200': description: 'OK - The requested information has been retrieved successfully. ' content: application/json: schema: oneOf: - type: array items: $ref: '#/components/schemas/FuelTypesSchema' /v1/vehicle/versions/create: post: summary: Creates a new vehicle version. description: "This endpoint allows you to register a new vehicle version with\ \ the specified details.\nThe following information is required:\n\n * name:\ \ The name of the vehicle version.\n * doors: Number of doors in the vehicle.\n\ \ * transmission: Type of transmission (e.g., manual, automatic).\n * engine_displacement:\ \ Engine displacement of the vehicle in cm3.\n * engine_power: Power output\ \ of the vehicle's engine in cv.\n * motorization: The motorization type\ \ name (e.g., ICE, MHEV, ePower, BEV, PHEV, FCEV, HEV).\n * fuel_types: A\ \ list of fuel type names associated with this vehicle version.\n * vehicle_models_makes_id:\ \ The ID of the associated vehicle model.\n\nEnsure that all required attributes\ \ are provided to avoid validation errors.\n" tags: - Vehicle Versions security: - BearerAuth: - write - ApiKeyAuth: - write requestBody: content: application/json: schema: $ref: '#/components/schemas/VehicleVersionSchema' examples: default: summary: Basic vehicle version creation. value: name: Model X doors: 4 transmission: automatic engine_displacement: 2000 engine_power: 150 motorization: ICE fuel_types: - gasoline vehicle_models_makes_id: 1234 responses: '201': description: 'OK - The vehicle version has been created successfully. ' content: application/json: schema: $ref: '#/components/schemas/VehicleVersionSchema' '400': description: 'Missing or invalid required parameters. ' content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' examples: missing_engine_displacement: value: msg: 'engine_displacement: is missing' err_code: 9901 error: 400 status: error '415': description: 'Incorrect data format in the request body. ' content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' example: incorrect_format: value: msg: attribute is incorrect err_code: 9900 error: 415 status: error '500': description: 'Internal server error during creation. ' content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' example: creation_failed: value: msg: Vehicle version could not be created err_code: 500 error: 500 status: error /v1/tracking-schedules/timezones: get: summary: Retrieve a list of timezones description: Return a JSON array of timezones. tags: - Tracking Schedules responses: '200': description: A list of timezone strings content: application/json: schema: type: array items: type: string example: - UTC - Europe/Madrid - America/New_York /v1/tracking-schedules/create: post: summary: Registers new schedule for a company. description: "A company can have got none, one or multiple schedules and this\ \ endpoint register new schedule for a company.\nThis schedules set in which\ \ timetable the tracker information is stored.\nRegister schedule with:\n\ \ * name\n * description\n * schedule\n * timezone\n * company_oid\n" tags: - Tracking Schedules security: - BearerAuth: - write - ApiKeyAuth: - write requestBody: content: application/json: schema: type: object properties: name: type: string description: type: string schedule: type: object properties: timetable: type: object properties: Mon: type: array Tue: type: array Wed: type: array Thu: type: array Fri: type: array Sat: type: array Sun: type: array exceptions: type: array timezone: type: string company_oid: type: string required: - schedule - timezone - name examples: Schedule with exceptions: description: Create the schedule with one exception value: timezone: Pacific/Niue schedule: timetable: Mon: - - '8:00' - '10:00' Tue: - - '8:00' - '10:00' - - '14:00' - '17:00' exceptions: - day: 1 month: 1 year: 2024 on_repeat: true company_oid: 71ecd9a1-51f0-4bb7-974b-f93feb300a49 name: Working hours description: Working hours responses: '200': description: The endpoint returns an object with the created schedule. content: application/json: schema: $ref: '#/components/schemas/TrackingSchedule' examples: Correct process: value: company_oid: 7ddcc805-4e22-4a6e-bb4c-c67170c5b085 description: Working hours name: Working hours oid: cd5d1cca-ef21-45d0-9fc8-25382683c60d schedule: exceptions: - day: 1 month: 1 on_repeat: true year: 2024 timetable: Mon: - - '8:00' - '10:00' Tue: - - '8:00' - '10:00' - - '14:00' - '17:00' timezone: Pacific/Niue '400': description: Required entity not specified. A required parameter is missed. content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' examples: Name parameter empty: value: err_code: 9901 error: 400 msg: 'name: is missing' status: error Schedule parameter empty: value: err_code: 9901 error: 400 msg: 'schedule: is missing' status: error Timezone parameter empty: value: err_code: 9901 error: 400 msg: 'timezone: is missing' status: error Timetable parameter empty: value: err_code: 9901 error: 400 msg: 'timezone: is missing' status: error Company_oid parameter empty: value: err_code: 9901 error: 400 msg: 'company_oid: is missing' status: error '403': description: You cannot create the schedule. This error is thrown when you don't have the necessary permissions assigned to create an schedule. content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' examples: Not allowed to register the schedule: value: error: 403 msg: You cannot create the schedule. err_code: 9902 /v1/telemetrics/trips: get: summary: Returns a list of trips for a given company or group. description: "This endpoint returns a list of all the trips which belong to\ \ the given company or group.\nThe call must include either the _company_oid_\ \ or the _group_oid_ as your identifier.\nOptionally, a call can include the\ \ following parameters:\n * _start_date_ and _end_date_. These parameters\ \ specify the time period of interest, i.e. only trips that fall in between\ \ these dates will be listed. If the _end_date_ is omitted, the list will\ \ include all the trips from the _start_date_ until now.\n If both dates\ \ are omitted, the list will include only today's trips.\n * _next_ and _previous_.\ \ These parameters provide the pagination functionality for browsing the returned\ \ list.\n Upon calling this endpoint for the first time without these parameters,\ \ it returns the first 10 elements of the list (ordered by date).\n If there\ \ are more than 10 elements, the returned file will include the parameter\ \ _next_ and/or _previous_.\n By passing this _next_ parameter into a second\ \ call of the same endpoint, the next 10 elements will be returned, together\ \ with a new _next_ (in case there are remaining elements).\n In the same\ \ way, by passing the _previous_ parameter, the previous 10 elements will\ \ be returned.\n * _tracker_id_. Adding this parameter to the call will restrict\ \ the response to the trips of this particular tracker.\n If omitted, the\ \ response will contain the trips of all trackers.\n" tags: - Telemetrics security: - BearerAuth: - read - ApiKeyAuth: - read parameters: - in: query name: group_oid required: false schema: type: string - in: query name: company_oid required: false schema: type: string - in: query name: start_date required: false schema: type: string format: date - in: query name: end_date required: false schema: type: string format: date - in: query name: next required: false schema: type: string - in: query name: previous required: false schema: type: string - in: query name: tracker_id required: false schema: type: string responses: '200': description: 'OK - The response includes a JSON file that contains a maximum of 10 list entries, plus the _next_ and _previous_ string for browsing the remaining entries. ' content: application/json: schema: type: array items: $ref: '#/components/schemas/Trips' '400': description: 'Either both _company_oid_ and _group_oid_ are missing, or the date format is wrong. ' content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' examples: Company OID or group OID is missing: value: msg: company_oid or group_oid is missing. error: 400 err_code: 9901 The date format is wrong: value: msg: Invalid date format error: 400 err_code: 9904 '403': description: 'The user does not have permission to see trips for this company or group. ' content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' examples: No permission for this company: value: msg: You cannot read_trips this company. error: 403 err_code: 9902 No permission for this group: value: msg: You cannot read_trips this group. error: 403 err_code: 9902 /v1/importers/html5: get: summary: Check if the server is up and running. description: 'This HTML5 endpoint checks if the server is up and running. ' tags: - Data Importers security: - ApiKeyAuth: - read responses: '200': description: The server is up and running. content: application/json: examples: The server is up and running: value: status: ok post: summary: Insert telemetry data from any provider. description: "Insert telemetry data, one at a time, from any provider. It can\ \ be used, for example, to inject a data point from a mobile through a web\ \ app, in which case the tracker would be the mobile itself. The data should\ \ contain the following parameters:\n\n * timestamp. It should be in milliseconds,\ \ otherwise the telemetry will not be added or can be added with a wrong datetime.\n\ \ * tracker_id\n * coords:\n - latitude\n - longitude\n" tags: - Data Importers security: - ApiKeyAuth: - write requestBody: content: application/json: schema: type: object properties: coords: type: object properties: latitude: type: number longitude: type: number timestamp: type: integer tracker_id: type: string required: - coords - timestamp - tracker_id examples: Valid format: value: coords: latitude: 40 longitude: -3.7 timestamp: 1681209983000 tracker_id: '529305476545970' responses: '200': description: Data successfully inserted. content: application/json: schema: $ref: '#/components/schemas/Html5Schema' examples: Correct process: value: data: - latitude: 40 longitude: -3.7 ts: '2023-04-11T10:46:23.000000+00:00' status: ok '415': description: Required entity not specified. A required parameter is missing. content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' examples: JSON data parameter empty: value: err_code: 202 error: 415 msg: JSON data is missing. status: error '403': description: Not allowed to use the tracker. content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' examples: Not allowed to use this tracker: value: err_code: 9902 error: 403 msg: You cannot use this tracker. status: error /v2/trackers/vehicles-guide: get: summary: List available vehicle makes and models. description: 'This endpoint lists vehicle makes and models available in our database. By default, it returns a list of all makes registered within our database. In order to display the models of a specific make, the make name has to be included as a query parameter. For display all manufacturers and models, the parameter ''all'' has to be included as a query parameter. ' tags: - Trackers security: - BearerAuth: - read - ApiKeyAuth: - read parameters: - in: query name: make required: false schema: type: string - in: query name: all required: false schema: type: boolean responses: '200': description: 'By default, this answer provides you a list of all registered makes within our database. Instead, if you have specified a make as an argument in the parameters, you will obtain all the models that belong to this make. ' content: application/json: schema: oneOf: - $ref: '#/components/schemas/VehicleModelMakeSchema' - $ref: '#/components/schemas/VehicleMakeSchema' discriminator: propertyName: make examples: Correct request: summary: Default request, get all makes. value: data: - name: Hyundai - name: Subaru - name: Mazda - name: BMW - name: Volkswagen - name: SsangYong - name: Toyota Get all models of one make: summary: Get all models of one make. value: data: - id: 1 name: Sprinter vehicle_type: van - id: 2 name: Vito vehicle_type: van Get all makes and models: summary: Get all makes and models. value: data: Mercedes-Benz: - Sprinter - Vito Volkswagen: - Tiguan '404': description: 'Make not found. All available makes can be listed by calling this endpoint without query parameter. ' content: application/json: schema: $ref: '#/components/schemas/ErrorSchema' examples: Make not found: value: msg: Make not found. error: 404 err_code: 105 /v2/trackers/vehicles-types: get: summary: List available vehicle types description: 'This endpoint retrieves a list of vehicle types available in the database. Vehicle types represent categories of vehicles, such as cars, bikes, trucks, etc. ' tags: - Trackers security: - BearerAuth: - read - ApiKeyAuth: - read responses: '200': description: 'Returns a list of vehicle types in the database. ' content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/VehicleTypeSchema' examples: Default response: summary: Default response, get all vehicle types. value: data: - name: car - name: van - name: other '404': description: 'The requested resource could not be found. ' content: application/json: schema: $ref: '#/components/schemas/ErrorSchema' examples: Resource not found: value: msg: The requested resource could not be found. error: 404 err_code: 40401 /v1/trackers/register: post: summary: Registers a tracker. description: "This endpoint allows you to register a tracker in a given company.\ \ The following information is required for the procedure:\n * company_oid:\ \ The universally unique identifier associated with your company. This company\ \ will hold the tracker and will pay the cost of maintaining the connection.\n\ \ * tracker_id: A unique identifier of the tracker. It can be a VIN, an IMEI,\ \ a license plate or the unique identifier that the data provider will use.\n\ \ * provider: The name of the data provider of your tracker.\n \ \ Current options are: Mercedes-Benz, BMW, Cartrack, HTML5, Targa, Stellantis.\n\ \ * type: The tracker's connection type.\n Current options are:\ \ oem, obd, CANbus.\n\nOptionally, the following information can be included:\n\ \ * group_oid: This parameter associates the newly registered tracker to\ \ a group.\n Trackers can be allocated to groups in order to organize them\ \ in a custom way.\n * vehicle_type: The type of vehicle to which the tracker\ \ is assigned.\n This allows filtering by vehicle type within our API.\ \ Examples: car, van, truck, motorcycle.\n * packages: This parameter specifies\ \ the data packages that you want to be operating on your tracker.\n Currently,\ \ it only works for the data provider *Mercedes-Benz* and necessitates the\ \ specification of an object_id when applying packages. There are two possible\ \ values for this parameter:\n\n * packages=['mercedesbenzmileage']:\ \ position and odometer data.\n * packages=['mercedesbenzelectrotest']:\ \ position, odometer, consumption, battery and velocity.\n * packages=['mercedesbenzextended']:\ \ position, odometer, ignition, consumption, battery, tires, velocity and\ \ binaries (windows, lights, doors).\n\n * object_id: This parameter details\ \ supplementary information about the vehicle to which the tracker is assigned,\ \ encompassing the Make, Model, VIN, and License plate of the vehicle.\n\n\ Registering a tracker within the provider's system may require that the corresponding\ \ provider credentials are linked to your company's account. Please refer\ \ to our [Docs](https://docs.astaraconnect.com/reference/post_v1-credentials-register).\n" tags: - Trackers security: - BearerAuth: - write - ApiKeyAuth: - write requestBody: content: application/json: schema: $ref: '#/components/schemas/RegisterTracker' examples: default: summary: A basic tracker registration. value: tracker_id: 0000ABC provider: HTML5 type: canbus company_oid: 6f6fc660-1ab4-4312-bcf3-1c7a4ac97cb3 tracker with packages: summary: A Mercedes-Benz tracker with a list of packages. value: tracker_id: JH4NA1150MT000683 provider: Mercedes-Benz type: oem company_oid: 6f6fc660-1ab4-4312-bcf3-1c7a4ac97cb3 packages: - mercedesbenzmileage object_id: make: mercedes-benz model: clase A tracker with group OID and tracker type: summary: A tracker with the required parameters plus group OID and tracker type. value: tracker_id: 505613925054389 provider: cartrack type: obd company_oid: 6f6fc660-1ab4-4312-bcf3-1c7a4ac97cb3 group_oid: c4d11ee3-6591-44e9-9e23-f617c82af739 vehicle_type: car responses: '200': description: "OK - The tracker has been registered, resulting in one of\ \ the following validation status:\n * **pending**: The tracker_id is\ \ correct and the tracker is ready for validation.\n * **wrong_tracker_id**:\ \ The tracker_id has been rejected by the provider. Use the _update_ endpoint\ \ to correct the ID and restart the verification procedure.\n" content: application/json: schema: $ref: '#/components/schemas/TrackerSchema' '400': description: 'This error is shown when one of the required arguments is missing or has a wrong value. ' content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' examples: company_oid is missing: value: msg: 'company_oid: is missing' err_code: 9901 error: 400 status: error tracker_id is missing: value: msg: 'tracker_id: is missing' err_code: 9901 error: 400 status: error provider is missing: value: msg: 'provider: is missing' err_code: 9901 error: 400 status: error vehicle_type is missing: value: msg: 'vehicle_type: is missing' err_code: 9901 error: 400 status: error '403': description: 'This error is shown when the tracker already exists in our database. ' content: application/json: schema: $ref: '#/components/schemas/ErrorSchema' example: Tracker already registered: value: msg: Tracker tracker_id already registered error: 403 '415': description: 'This is shown when one of the parameters passed in the body is not in the proper data format. ' content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' example: Data format incorrect in the request body: value: msg: attribute is incorrect err_code: 9900 error: 415 status: error '500': description: 'This error is shown when the tracker could not be created. ' content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' example: Tracker could not be created: value: msg: The tracker could not be created err_code: 500 error: 500 status: error /v1/trackers/validate: post: summary: Validates a previously registered tracker. description: "This endpoint validates a previously registered tracker within\ \ the data provider's system.\nIt will trigger an ownership verification which\ \ is necessary to retrieve data from the tracker.\nThe system won't import\ \ any data if the tracker is not successfully validated.\n\nIn the moment\ \ a new tracker is successfully registered in our system, its validation status\ \ is **pending**.\n\nNote: If the validation status is **wrong_tracker_id**,\ \ the tracker_id was rejected by the provider during the registration procedure.\n\ In this case, first use the v1/trackers/{oid}/update endpoint to correct the\ \ ID and then proceed with the validation.\n\nOnce it is **pending**, this\ \ endpoint will launch the tracker validation. The following information is\ \ required in the request body:\n\n * tracker_id\n * provider\n\nFor trackers\ \ using direct OEM connection with Mercedes-Benz, the request body must additionally\ \ contain the current odometer read-out from the vehicle:\n\n * odo_value\n\ \nA successful call will change the validation status from **pending** to\ \ **pending_validation**, and trigger the external validation procedure.\n\ This is an asynchronous process and its duration will vary depending on the\ \ specific case. We will update this documentation in the future and include\ \ provider-specific instructions.\n\nIf the external validation was successful,\ \ the validation status will switch to **pending_for_data**. Then, upon receiving\ \ the first location data from the tracker, the validation status will\nbe\ \ updated to **connected**. This last step is automatically done as soon as\ \ the vehicle is driven in an area with GPS signal.\n\nIn case that the validation\ \ procedure fails and results in an validation state which indicates an error,\ \ it can be executed again in order to restart the procedure.\nThe validation\ \ status can be checked via v1/trackers/{oid}/.\n" tags: - Trackers security: - BearerAuth: - write - ApiKeyAuth: - write requestBody: content: application/json: schema: $ref: '#/components/schemas/ValidateTracker' examples: default: summary: 'Standard tracker. ' value: tracker_id: 0000LLL provider: cartrack Mercedes-Benz tracker with odometer read-out validation: summary: 'Mercedes-Benz tracker. ' value: tracker_id: JH4NA1150MT000683 provider: mercedes-benz odo_value: 1000 responses: '200': description: 'OK - The tracker is passed to **pending_validation** status and the clearance procedure is triggered. ' content: application/json: schema: $ref: '#/components/schemas/TrackerSchema' '400': description: 'This error is returned when one of the required arguments is missing. ' content: application/json: schema: $ref: '#/components/schemas/ErrorSchema' examples: tracker_id is missing: value: msg: 'tracker_id: is missing' err_code: 9901 error: 400 status: error provider is missing: value: msg: 'provider: is missing' err_code: 9901 error: 400 status: error extra argument is missing: value: msg: tracker_id cannot be validated (missing arguments or provider service is unavailable) err_code: 102 error: 400 status: error '403': description: 'This error is returned when data provider credentials are needed but are incomplete or missing. ' content: application/json: schema: $ref: '#/components/schemas/ErrorSchema' example: Data provider credentials are incorrect: value: msg: provider credentials are required for registering the tracker error: 403 /v2/trackers/activity: get: summary: Retrieves trackers information with properties based on specified parameters. description: "This endpoint returns a number of parameters associated with a\ \ given tracker identifier tracker_oid or tracker_id,\na list of trackers\ \ for a given company identifier company_oid,\na list of trackers for a given\ \ company identifier and group identifier company_oid and group_oid,\na list\ \ of trackers for a given company identifier and group name company_oid and\ \ group_name,\na list of trackers for a given group identifier group_oid or\ \ a list of trackers for a given group name group_name.\nIf group_name = all,\ \ then returns a list of trackers grouped by company and groups.\nThe company_oid\ \ must be specified when group_name parameter is used.\n\nThe following parameters\ \ will be returned:\n\n * oid - The tracker's unique internal identifier.\n\ \ * tracker_id - The tracker_id is the tracker's unique identifier e.g. VIN,\ \ IMEI, license plate number...\n The format of this value depends of the\ \ provider of your tracker:\n * Option 1: for the HTML5 importer the tracker\ \ IDs can be customized. It is up to the owner to specify an identifier.\n\ \ * Option 2: for the regular data providers this is defined by each provider,\ \ as specified in the following list:\n * Mercedes-Benz: VIN\n \ \ * Cartrack: VIN\n * BMW: VIN\n * Targa: VIN\n * object_id -\ \ The object_id is a dictionary that contains information about the identity\ \ of the tracked object, such as the VIN, make, model, license plate number.\n\ \ * provider - The provider of the tracker, e.g. Mercedes-Benz, BMW...\n *\ \ type - The tracker type, e.g. OEM, OBD, ...\n * vehicle_type - The vehicle\ \ type, e.g. car, van, motorcycle...\n * start_date - The date when the tracker\ \ was registered on the platform.\n * end_date - The date when the tracker\ \ was deregistered on the platform.\n * heartbeat - Timestamp of the trackers'\ \ latest data.\n * validation_status - Tracker's current status within the\ \ validation chain. For example: pending, pending validation, error_access,\ \ connected.\n * external_validation_data - An optional parameter which contains\ \ validation information from third-party data providers.\n * foreign_tracker_id\ \ - The identity of the tracker on a third-party data provider platform.\n\ \ * company_oid - The unique identifier of the company to which the tracker\ \ belongs.\n * motorization - An optional parameter which specifies the motorization\ \ of the vehicle in which the tracker is installed. Options include gasoline,\ \ diesel, electric, hydrogen, PHEV and others.\n * position - The coordinates\ \ in WGS84-format of the last position received from the tracker.\n * properties\ \ - The tracker properties with their value and value information (unit, values,\ \ description).\n * gps_status - Indicates the GPS accuracy. Possible values:\ \ \"excellent\", \"good\", or \"bad\".\n * gsm_on - Indicates whether the\ \ tracker is properly reporting data (true) or not (false).\n" tags: - Tracker Activity security: - BearerAuth: - read - ApiKeyAuth: - read parameters: - in: query name: oid description: The OID of the tracker. schema: type: string example: cfd9e3bb-1158-40ab-b83f-4146d9e33447 required: true - in: query name: tracker_id description: The vehicle VIN. schema: type: string example: VNAB8888GRT888888 required: true - in: query name: company_oid description: Company OID. schema: type: string example: cfd9e3bb-1158-40ab-b83f-4146d9e33447 required: true - in: query name: group_oid description: Group OID. schema: type: string example: cfd9e3bb-1158-40ab-b83f-4146d9e33447 required: true - in: query name: group_name description: Group name. Use "all" to retrieve all groups. schema: oneOf: - type: string - type: string enum: - all examples: group_name: value: some_group all: value: all required: true responses: '200': description: List of trackers or tracker information based on specified parameters. content: application/json: schema: $ref: '#/components/schemas/TrackerSchema' examples: Tracker: value: end_date: null external_validation_data: null heartbeat: '2024-05-08T21:12:54.000000+00' motorization: null object_id: license_plate: 2859MKL make: Mitsubishi model: ASX vin: VF1RJB00971373525 oid: e8de8bac-8115-4d51-8956-7886310f9e7e properties: device.gps.odometer: info: category: - main - device code: KTM data_type: float description: The value represents the calculated vehicle odometer based on GPS coordinates. friendly_name: Device GPS Odometer group: - essentials icon: counter range: max: 1000000 min: 0 unit: km values: [] ts: '2024-05-08T21:12:54.000000+00' value: 34891 device.gps.speed: info: category: - device code: KMH data_type: float description: The value represents the calculated vehicle speed based on GPS coordinates. friendly_name: Device GPS Speed group: - essentials icon: speedometer range: max: 350 min: 0 unit: km/h values: [] ts: '2024-05-08T21:12:54.000000+00' value: 0 ignition.status: info: category: - main - status code: '' data_type: enum description: The value indicates the status of the ignition of the vehicle at the time of the data collection. friendly_name: Ignition Status group: - essentials icon: power-standby range: {} unit: '' values: - 'Off' - 'On' - Stand By ts: '2024-05-08T21:12:54.000000+00' value: 'On' position.latitude: info: category: - location code: DD data_type: float description: This value indicates the degree of latitude at which the vehicle was at the time of data collection. The degree of latitude could range from 0 (at the equator) to a maximum of +90 north or respectively -90 south of the equator. (WGS84 coordinates systems) friendly_name: Latitude group: - essentials icon: place range: max: 90 min: -90 unit: degrees values: [] ts: '2024-05-08T21:12:54.000000+00' value: 41.522444 position.longitude: info: category: - location code: DD data_type: float description: This value indicates the degree of longitude at which the vehicle was at the time of data collection. The degree of longitude could range from 0 (at the Greenwich meridian / Great Britain) to a maximum of +180 east or respectively -180 west of the meridian.(WGS84 coordinates systems) friendly_name: Longitude group: - essentials icon: place range: max: 180 min: -180 unit: degrees values: [] ts: '2024-05-08T21:12:54.000000+00' value: 0.336404 provider: cartrack start_date: '2023-10-26T08:46:25.555839+00' tracker_id: VF1RJB00971373525 type: canbus validation_status: connected vehicle_type: car '404': description: 'The given OID was not found. (tracker, company, group), or the given group name not found ' content: application/json: schema: $ref: '#/components/schemas/ErrorSchema' examples: Tracker not found: value: msg: not found error: 404 err_code: 101 Group not found: value: msg: Group not found error: 404 err_code: 500 Company not found: value: msg: not found error: 404 err_code: 10003 '415': description: 'This error is shown when the tracker OID has no valid UUID format. ' content: application/json: schema: $ref: '#/components/schemas/ErrorSchema' examples: OID string has no valid UUID format: value: msg: oid string has no valid UUID format. error: 415 err_code: 9900 /v2/trackers/html5: post: summary: Insert tracker properties data for storage. description: "This endpoint allows you to store tracker properties by providing\ \ a JSON payload with the following fields:\n\n- **tracker_id** (string, required):\ \ A unique identifier for the tracker, also known as VIN.\n- **properties**\ \ (array, required): A list of key-value pairs representing the properties\ \ of the tracker. Each item in the list should be an object with:\n - **key**:\ \ The name of the property (e.g., \"position.latitude\").\n - **value** (string,\ \ required): The value of the property (e.g., a numerical value or a string).\n\ \ - **ts** (string, required): A timestamp indicating when the property was\ \ recorded, in ISO 8601 format.\n\nExample properties might include latitude\ \ and longitude for location tracking.\n\nIf properties for 'position.latitude'\ \ and 'position.longitude' are included, they will also update the tracker's\ \ telemetry data, such as its geographic position and timestamp.\n\nProperties\ \ that do not match known database keys will be ignored, but will be included\ \ in the 'error_properties' field in the response.\n" tags: - Data Importers security: - ApiKeyAuth: - write requestBody: content: application/json: schema: type: object properties: tracker_id: type: string description: A unique identifier for the tracker. properties: type: array description: A list of tracker properties, where each property includes a key, a value, and a timestamp. items: type: object additionalProperties: type: object properties: ts: type: string format: date-time description: The timestamp when the property was recorded (ISO 8601). value: type: string description: The value of the property (e.g., a numeric or string value). required: - ts - value required: - tracker_id - properties examples: Valid format: value: tracker_id: '12345678901011' properties: - position.latitude: ts: '2024-11-22T11:27:45Z' value: 41.522444 - position.longitude: ts: '2024-11-22T11:27:45Z' value: 0.336404 responses: '200': description: Properties successfully processed and stored. If unknown properties were encountered, they are included in the 'error_properties' field. content: application/json: schema: type: object properties: tracker_id: type: string properties: type: array items: type: object additionalProperties: type: object properties: ts: type: string format: date-time value: type: string error_properties: type: array description: List of properties that were not found in the database. items: type: object additionalProperties: type: object properties: ts: type: string format: date-time value: type: string examples: Successful processing with unknown properties: value: tracker_id: '12345678901011' properties: - position.latitude: ts: '2024-11-22T11:27:45Z' value: 41.522444 error_properties: - unknown.property: ts: '2024-11-22T11:27:45Z' value: InvalidValue '400': description: Validation error in input data. content: application/json: schema: type: object properties: status: type: string error: type: string examples: Validation error: value: status: error error: Invalid payload format. '404': description: Tracker not found. content: application/json: schema: type: object properties: status: type: string error: type: string examples: Tracker not found: value: status: error error: Tracker with tracker_id 12345678901011 not found. /v2/trackers/list: get: summary: Retrieves basic trackers information based on specified parameters. description: "a list of trackers for a given company identifier company_oid,\n\ optionally filtered by a given validation_status: disconnected, connected,\ \ pending, pending_for_data, pending_validation, error\n\nThe following parameters\ \ will be returned:\n\n * oid - The tracker's unique internal identifier.\n\ \ * tracker_id - The tracker_id is the tracker's unique identifier e.g. VIN,\ \ IMEI, license plate number...\n The format of this value depends of the\ \ provider of your tracker:\n * Option 1: for the HTML5 importer the tracker\ \ IDs can be customized. It is up to the owner to specify an identifier.\n\ \ * Option 2: for the regular data providers this is defined by each provider,\ \ as specified in the following list:\n * Mercedes-Benz: VIN\n \ \ * Cartrack: VIN\n * BMW: VIN\n * Targa: VIN\n * provider -\ \ The provider of the tracker, e.g. Mercedes-Benz, BMW...\n * type - The tracker\ \ type, e.g. OEM, OBD, ...\n * start_date - The date when the tracker was\ \ registered on the platform.\n * end_date - The date when the tracker was\ \ deregistered on the platform.\n * validation_status - Tracker's current\ \ status within the validation chain. For example: pending, pending validation,\ \ error_access, connected.\n * asset_oid - The unique internal identifier\ \ of the asset where the tracker is installed\n" tags: - Trackers security: - BearerAuth: - read - ApiKeyAuth: - read parameters: - in: query name: company_oid description: Company OID. schema: type: string example: cfd9e3bb-1158-40ab-b83f-4146d9e33447 required: true - in: query name: validation_status description: Validation status filter. schema: type: string example: pending required: false responses: '200': description: List of trackers based on specified parameters. content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/TrackerSchema' examples: Tracker list: value: - oid: e8de8bac-8115-4d51-8956-7886310f9e7e tracker_id: VF1RJB00971373525 provider: cartrack type: canbus start_date: '2023-10-26T08:46:25.555839+00' end_date: null validation_status: connected asset_oid: null '404': description: 'The given OID was not found. ' content: application/json: schema: $ref: '#/components/schemas/ErrorSchema' examples: Company not found: value: msg: not found error: 404 err_code: 10003 '415': description: 'This error is shown when the company OID has no valid UUID format. ' content: application/json: schema: $ref: '#/components/schemas/ErrorSchema' examples: OID string has no valid UUID format: value: msg: oid string has no valid UUID format. error: 415 err_code: 9900 /v1/vehicle/versions: get: summary: Retrieves vehicle versions by the model ID. description: 'This endpoint allows you to retrieve details of the vehicle versions by its model ID. ' tags: - Vehicle Versions parameters: - name: model_id in: query required: true schema: type: integer description: 'The unique identifier for the model ID. ' responses: '200': description: 'OK - The requested vehicle versions has been retrieved successfully. ' content: application/json: schema: oneOf: - type: array items: $ref: '#/components/schemas/VehicleVersionSchema' examples: vehicle versions: summary: All vehicle versions by model ID value: - id: 1 name: Model A doors: 4 transmission: manual engine_displacement: 2000 engine_power: 150 motorization: name: ICE fuel_types: - name: gasoline vehicle_models_makes_id: 1234 - id: 2 name: Model B doors: 2 transmission: automatic engine_displacement: 1500 engine_power: 100 motorization: name: BEV fuel_types: - name: gasoline vehicle_models_makes_id: 1234 '400': description: Required entity not specified. A required parameter is missed. content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' examples: model_id parameter empty: value: err_code: 9901 error: 400 msg: 'model_id: is missing' status: error /v2/assets/order-install: post: summary: Send the installation order to an asset in draft status. description: "This endpoint allows you to install a new asset which is in draft\ \ status..\nParameters:\n * company_address_oid(required): Company Address\ \ OID, related to the address where the installation will be done, required\ \ if provider is Targa and installation_order True.\n * contact_person(required):\ \ information about the person to contact when doing the installation, required\ \ if provider is Targa and installation_order True.\n * id(required): A unique\ \ identifier of the vehicle. It should be a VIN.\n" tags: - Assets security: - BearerAuth: - write - ApiKeyAuth: - write requestBody: content: application/json: schema: type: object properties: company_address_oid: type: string contact_person: type: object properties: name: type: string email: type: string phone: type: string id: type: string responses: '200': description: 'The installation order was created and send successfully. ' content: application/json: schema: type: object properties: tracker_order: $ref: '#/components/schemas/TrackerOrderSchema' '400': description: 'Missing or invalid required parameters. ' content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' examples: id: value: msg: 'id: is missing' err_code: 9901 error: 400 status: error invalid UUID: value: msg: company_address_oid is not a valid UUID err_code: 9901 error: 400 status: error '404': description: Asset, Tracker or Company Address not found. content: application/json: schema: type: object properties: error: type: string example: 'The company_address with oid: 7c5b2c18-8432-42ae-bbef-4bba9246585e not found' status: type: string example: error '415': description: 'Incorrect data format in the request body. ' content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' '500': description: 'This error is shown when the tracker order or the order payload could not be created or updated. ' content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' example: Tracker could not be created: value: msg: The tracker could not be created err_code: 500 error: 500 status: error /v1/groups/register: post: summary: Register a new group. description: "Register a new group with the following parameters:\n * name:\ \ string parameter which identifies the group\n * slug: unique, human-readable\ \ identifier, alphanumeric character string without special characters or\ \ spaces.\n * company_oid: OID of the company at which the group belongs\n\ \ * webhook: url pointing to the group's webhook\n * email: email address\ \ to which notifications are sent\n\nWhen the group is created you can add\ \ trackers (See (#/Trackers)) to it.\n" tags: - Groups security: - BearerAuth: - write - ApiKeyAuth: - write requestBody: content: application/json: schema: properties: name: type: string slug: type: string company_oid: type: string webhook: type: string email: type: string required: - company_oid - name - slug examples: Valid data: value: name: ACME slug: acme company_oid: 871e7ddc-e171-4152-ab73-e5b58a0663b8 responses: '200': description: The group has been successfully created. content: application/json: schema: $ref: '#/components/schemas/GroupSchema' examples: Correct process: value: company: cif: None city: None country: None created_at: '2022-10-24T11:28:47.129422+00:00' delete_at_period_end: false deleted: false email: None fiscal_address: None has_accepted_contract: false has_accepted_privacy_policy: false has_accepted_terms_of_service: false has_apikey: false invoicing_email: None language: es-ES name: Acme LTD oid: 871e7ddc-e171-4152-ab73-e5b58a0663b8 owner_oid: 7b3822ee-7909-4874-a94c-9dc9d09e9204 phone: None postal_code: None slug: None update_at: '2022-10-24T11:28:47.129422+00:00' vat: None webhook: None description: None email: None name: ACME oid: ce839641-af31-480d-a839-65618ec034dc slug: acme webhook: None '403': description: You cannot create the group. This error is thrown when you don't have the necessary permissions assigned to register a group. content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' examples: Not allowed to register the group: value: error: 403 msg: You cannot create the group. err_code: 9902 status: error '400': description: A required parameter is missed, a group already exists with the selected slug or required entity not specified. A required parameter is missed. content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' examples: Slug not unique: value: error: 400 msg: slug not unique. err_code: 501 status: error Company OID parameter empty: value: err_code: 9901 error: 400 msg: 'company_oid: is missing' status: error Name parameter empty: value: err_code: 9901 error: 400 msg: 'name: is missing' status: error Slug parameter empty: value: err_code: 9901 error: 400 msg: 'slug: is missing' status: error /v2/assets/register: post: summary: Register a new asset. description: 'Register an asset and its tracker. Detailed business rules (Targa + installation order, Mercedes-Benz + odo_value), and credentialed registration (provider-specific ''credentials'') are documented at the component schema and completed by the spec patch. ' tags: - Assets security: - BearerAuth: - write - ApiKeyAuth: - write requestBody: required: true content: application/json: schema: type: object properties: asset_register: $ref: '#/components/schemas/AssetRegisterRequestSchema' responses: '200': description: Asset and tracker created; installation order sent when applicable. content: application/json: schema: type: object properties: asset: $ref: '#/components/schemas/AssetSchema' tracker: $ref: '#/components/schemas/TrackerSchema' tracker_order: $ref: '#/components/schemas/TrackerOrderSchema' '400': description: Missing or invalid required parameters. content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' examples: missing_id: value: msg: 'oid: is missing' err_code: 9901 error: 400 status: error invalid provider: value: msg: provider wrong value err_code: 9901 error: 400 status: error invalid UUID: value: msg: company_address_oid is not a valid UUID err_code: 9901 error: 400 status: error '404': description: Company address not found. content: application/json: schema: type: object properties: error: type: string example: 'The company_address with oid: 7c5b2c18-8432-42ae-bbef-4bba9246585e not found' status: type: string example: error '415': description: Incorrect data format in the request body. content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' '403': description: Tracker already exists in the database. content: application/json: schema: $ref: '#/components/schemas/ErrorSchema' example: Tracker already registered: value: msg: Tracker already registered error: 403 '409': description: Asset already exists in the database. content: application/json: schema: $ref: '#/components/schemas/ErrorSchema' example: Asset already registered: value: msg: Asset already registered error: 403 '500': description: Tracker/asset/order could not be created or updated. content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' example: Tracker could not be created: value: msg: The tracker could not be created err_code: 500 error: 500 status: error /v2/assets/eligible: post: summary: Check eligibility for registering an asset. description: 'Verifies if an asset is eligible to be registered in our system or in the OEM system based on its identifier and provider. Parameters must be sent in the JSON request body. ' tags: - Assets security: - BearerAuth: - read - ApiKeyAuth: - read requestBody: required: true content: application/json: schema: type: object required: - provider - asset_id - company_oid properties: provider: type: string enum: - bmw - ford - hyundai-kia - mercedes-benz - renault - stellantis - targa - toyota - volkswagen - volvo asset_id: type: string company_oid: type: string make: type: string description: Required when provider = "hyundai-kia". credentials: type: object description: Required when provider = "hyundai-kia, unless credentials_oid is provided.". properties: username: type: string password: type: string pin: type: string refresh_token: type: string required: - username - password - pin credentials_oid: type: string description: Optional. If provided, existing stored credentials will be used. examples: hyundai_kia: summary: Hyundai-Kia (requires make) value: provider: hyundai-kia asset_id: KNACS81FGP5069917 company_oid: 4e3b1d3a-1c4f-4f0f-9f6e-7e1b2c3d4a5f make: kia bmw: summary: BMW (VIN only) value: provider: bmw asset_id: WBA5R7C58KAJ86343 company_oid: 4e3b1d3a-1c4f-4f0f-9f6e-7e1b2c3d4a5f mercedes_benz: summary: Mercedes-Benz (VIN only) value: provider: mercedes-benz asset_id: WF0AXXWPMAJB43745MBBB company_oid: 4e3b1d3a-1c4f-4f0f-9f6e-7e1b2c3d4a5f stellantis: summary: Stellantis (VIN only) value: provider: stellantis asset_id: ZFAEFAA44PX137432 company_oid: 4e3b1d3a-1c4f-4f0f-9f6e-7e1b2c3d4a5f volkswagen: summary: Volkswagen (VIN only) value: provider: volkswagen asset_id: WVWZZZ1JZXW000001 company_oid: 4e3b1d3a-1c4f-4f0f-9f6e-7e1b2c3d4a5f ford: summary: Ford (VIN only) value: provider: ford asset_id: 1FAFP404XWF123456 company_oid: 4e3b1d3a-1c4f-4f0f-9f6e-7e1b2c3d4a5f renault: summary: Renault (VIN only) value: provider: renault asset_id: VF1AAAAA555555555 company_oid: 4e3b1d3a-1c4f-4f0f-9f6e-7e1b2c3d4a5f toyota: summary: Toyota (VIN only) value: provider: toyota asset_id: JTDKB20U793123456 company_oid: 4e3b1d3a-1c4f-4f0f-9f6e-7e1b2c3d4a5f volvo: summary: Volvo (VIN only) value: provider: volvo asset_id: YV1AAAAA555555555 company_oid: 4e3b1d3a-1c4f-4f0f-9f6e-7e1b2c3d4a5f responses: '200': description: Eligibility result with available packages. content: application/json: schema: type: object properties: eligible: type: boolean packages: type: array items: $ref: '#/components/schemas/PackageProviderSlimSchema' examples: eligible_mercedes: summary: Eligible (example with multiple packages) value: eligible: true packages: - description: mercedes_benz_basic info: friendly_name: Mercedes-Benz Basic Mileage, Position value: 5.0 - description: mercedes_benz_pro info: friendly_name: Mercedes-Benz Pro Mileage, Position, Consumption and Maintenance value: 7.0 not_eligible: summary: Not eligible value: eligible: false packages: [] '400': description: Missing or invalid required parameters. content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' '404': description: Provider not found in platform or credential_oid doesn't exist. content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' '409': description: Asset already registered. content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' '422': description: The asset is not eligible due to a provider validation error. content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' '500': description: Unexpected server error. content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' /v1/assets/create: post: summary: Creates a new asset. description: "This endpoint allows you to register a new asset with the specified\ \ details.\nThe following fields are optional unless otherwise stated:\n\n\ \ * id (required): The unique ID of the asset, For vehicles is the VIN.\n\ \ * license_plate: The license plate of the asset if is a vehicle.\n * model_year(required):\ \ The year of the vehicle model.\n * tank_size: The size of the fuel tank\ \ in liters for vehicles.\n * color: Color of the asset (as an enum value).\n\ \ * alias: A friendly name for the asset.\n * battery_size: Integer with\ \ the battery size expressed in kWh for electric vehicles.\n * external_validation_data:\ \ Json with external validation id to extract information from provider. Eg.\ \ value with which to extract the information in Cartrack provider.\n * version_id\ \ (required): The ID of the associated vehicle version.\n * company_oid (required):\ \ The OID of the associated company.\n * status(required): The asset status,\ \ available values are draft, processed, active and inactive.\n * registration_country(required):\ \ registration country code of the vehicle, it must be in format ISO 3166-1\ \ alpha-3.\n * registration_date: The asset's registration date.\n" tags: - Assets security: - BearerAuth: - write - ApiKeyAuth: - write requestBody: content: application/json: schema: $ref: '#/components/schemas/AssetSchema' examples: default: summary: Basic asset creation. value: id: VIN if the assets is a vehicle license_plate: ABC-1234 model_year: 2020 tank_size: 50 color: blue alias: My Car image_id: 42 battery_size: 70 external_validation_data: external_id: ABC-1234 version_id: 123 status: draft registration_country: ITA registration_date: '2024-01-01' responses: '201': description: 'The asset was created successfully. ' content: application/json: schema: $ref: '#/components/schemas/AssetSchema' '400': description: 'Missing or invalid required parameters. ' content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' examples: missing_id: value: msg: 'id: is missing' err_code: 9901 error: 400 status: error '415': description: 'Incorrect data format in the request body. ' content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' '403': description: You cannot create the asset. This error is thrown when you don't have the necessary permissions assigned to create an asset. content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' examples: No allow to create the asset: value: error: 403 msg: You cannot create the asset. err_code: 9902 /v1/pois/create: post: summary: Creates a POI from a GeoJSON FeatureCollection. description: 'This endpoint will create a new POI (Point of Interest) for each feature in the [GeoJSON FeatureCollection](https://www.rfc-editor.org/rfc/rfc7946#section-3.3) received in the request payload. The GeoJSON Features currently supported to create a POI are `Point`, `Polygon` and `MultiPolygon`. ' tags: - POIs security: - BearerAuth: - write - ApiKeyAuth: - write requestBody: content: application/json: schema: type: object properties: type: type: string enum: - FeatureCollection features: type: array items: type: object properties: type: type: string enum: - Feature properties: type: object properties: name: type: string info: type: object tags: type: array items: type: string public: type: boolean required: - name geometry: type: object properties: type: type: string enum: - Point - Polygon - MultiPolygon coordinates: type: array items: oneOf: - type: array items: type: number minItems: 2 maxItems: 2 - type: array items: type: array items: type: array items: type: number minItems: 2 maxItems: 2 - type: array items: type: array items: type: array items: type: array items: type: number minItems: 2 maxItems: 2 required: - type - coordinates required: - geometry required: - type - features examples: valid_data: summary: Creation of a POI from a one Feature FeatureCollection GeoJSON value: type: FeatureCollection features: - properties: null name: Gasolinera Repsol info: type: gas station brand: Repsol tags: - services - station public: true geometry: type: Point coordinates: - 41.3455 - 2.5356 parameters: - in: query name: company_oid description: 'Creates the POIs and assigns them to the specified company. Useful if the user making the request belongs to more than one company. If omitted, the default company for the user (usually the first they were assigned to or owned) will be used to create the POI. ' schema: type: string required: false responses: '200': description: POI created successfully. content: application/json: schema: $ref: '#/components/schemas/PoiSchema' example: company_oid: cfd9e3bb-1158-40ab-b83f-4146d9e33447 created_at: '2020-03-31T13:55: 08.132720+00: 00' geometry: type: Point coordinates: - 41.3455 - 2.5356 info: type: gas station brand: Repsol tags: - services - station oid: 1245215a-861f-4e2d-82f3-88d29e9474b3 name: Gasolinera Repsol public: true visible: true '415': description: Either the request payload is missing or it does not include a valid GeoJSON FeatureCollection. content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' examples: No FeatureCollection in data: value: error: 415 msg: The POI could not be created. You should send a GeoJSON FeatureCollection err_code: 803 http_code: 400 status: error No payload sent in the request: value: error: 415 msg: The POI could not be created because JSON data is missing err_code: 804 http_code: 400 status: error Missing fields in any GeoJSON features included in payload: value: error: 415 msg: 'Some of the following keys are missing: name, latitude, longitude' err_code: 9900 http_code: 400 status: error /v1/pois/public: get: summary: Get public POIs. description: Get public POIs. If no parameters are given, it will return *all* the public POIs available. The endpoint also admits filtering by `latitude`, `longitude`, `radius`, `info` and `tags`. tags: - POIs security: - BearerAuth: - read - ApiKeyAuth: - read parameters: - in: query name: latitude description: Must be used together with a `longitude` and, optionally, with a `radius`. It will filter POIs located around provided latitude and longitude, and within the given radius. schema: type: number required: false example: 40.4532 - in: query name: longitude description: Must be used together with a `latitude` and, optionally, with a `radius`. It will filter POIs located around provided latitude and longitude, and within the given radius. schema: type: number required: false example: 1.4532 - in: query name: tags description: Filter by tags schema: type: string required: false example: '["gas-station", "services"]' - in: query name: info description: Filter by info schema: type: string required: false example: city: Madrid - in: query name: radius description: Set radius, in meters, around the given coordinates where returned POIs will be located. Must be used together with `latitude` and `longitude`. Can be omitted, and will default to 30 (meters). schema: type: integer required: false example: 200 responses: '200': description: OK content: application/json: schema: type: array items: $ref: '#/components/schemas/PoiSchema' '415': description: Attribute missing. content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' example: latitude field missing: value: error: 415 msg: 'latitude: is missing' http_code: 415 err_code: 9901 longitude field missing: value: error: 415 msg: 'longitude: is missing' http_code: 415 err_code: 9901 Invalid JSON for tags or info fields: value: error: 415 msg: The POI could not be retrieved. Searching with incorrect tag or info field http_code: 415 err_code: 810 /v1/tracking-schedules/: get: summary: Return data related to schedules. description: 'A company can have got none, one or multiple schedules and this endpoint returns all the company''s data related to schedules by company oid or the data related to an specific schedule by schedule_oid. ' tags: - Tracking Schedules security: - BearerAuth: - read - ApiKeyAuth: - read parameters: - in: query name: schedule_oid description: Schedule OID. required: false schema: type: string example: 123e4567-e89b-12d3-a456-426614174000 format: uuid - in: query name: company_oid description: Company OID. required: false schema: type: string example: 123e4567-e89b-12d3-a456-426614174000 format: uuid responses: '200': description: This answer provides the data of an specific schedule or a list of a company schedules. content: application/json: schema: $ref: '#/components/schemas/TrackingSchedule' examples: Get an specific schedule data: value: company_oid: 2fe5dd0e-fc28-435f-995c-6d4c74529b35 description: Working hours name: Working hours oid: 6d54cf6b-34e0-4634-bd4e-d488cc3d2224 schedule: exceptions: - day: 1 month: 1 on_repeat: true year: 2024 timetable: Mon: - - '8:00' - '10:00' Tue: - - '8:00' - '10:00' - - '14:00' - '17:00' timezone: Pacific/Niue Get all the company schedules: value: - company_oid: 2fe5dd0e-fc28-435f-995c-6d4c74529b35 description: Working hours name: Working hours oid: 6d54cf6b-34e0-4634-bd4e-d488cc3d2224 schedule: exceptions: - day: 1 month: 1 on_repeat: true year: 2024 timetable: Mon: - - '8:00' - '10:00' Tue: - - '8:00' - '10:00' - - '14:00' - '17:00' timezone: Pacific/Niue '404': description: Company or Schedule not found. There is not a match with what is in the database for the company oid or the schedule oid. content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' examples: Company not found: value: error: 404 err_code: 10003 msg: company_oid not found. Schedule not found: value: error: 404 err_code: 10003 msg: schedule_oid not found. '415': description: Company or Schedule oid string has not a valid UUID format. content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' examples: Not valid UUID format for company oid: value: error: 415 err_code: 9901 msg: 'company oid: is incorrect.' Not valid UUID format for schedule oid: value: error: 415 err_code: 9901 msg: 'schedule oid: is incorrect.' '400': description: Required entity not specified. A required parameter is missed. content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' examples: schedule_id or company_oid parameter empty: value: err_code: 9901 error: 400 msg: At least one parameter (schedule_id or company_oid) must be added to the query. status: error /v1/trackers/: get: summary: Returns a list of trackers that belong to a company. description: "This endpoint allows you to get a list of trackers that belong\ \ to your company or to one of your groups. By default, all your company's\ \ trackers will be returned.\nIn order to limit the search results, the following\ \ optional query parameters can be specified:\n * group_oid: this limits\ \ the response to a specific group within your company.\n * filter_by: this\ \ limits the response to trackers with a specific validation status. Available\ \ values: connected, disconnected, error_access, error_not_available, error_revoked,\ \ pending, pending_for_data, pending_validation, wrong_tracker_id.\n" tags: - Trackers security: - BearerAuth: - read - ApiKeyAuth: - read parameters: - in: query name: company_oid required: true schema: type: string example: d1dfbac7-8729-4efc-bfd4-aaa8d8fccc23 - in: query name: group_oid required: false schema: type: string example: 87cc48f4-5ef3-484f-ac79-854bcf4861bb - in: query name: filter_by required: false schema: type: string enum: - pending - wrong_tracker_id - pending_for_data - error_data - connected example: connected responses: '200': description: 'OK - JSON file that contains a list of trackers that match the used filters. ' content: application/json: schema: type: array items: $ref: '#/components/schemas/TrackerSchema' examples: Trackers that are in validation_status "wrong_tracker_id": value: data: - end_date: null external_validation_data: null heartbeat: '2022-02-09T12:44:06.935617+00:00' motorization: null object_id: make: Mercedes-Benz vin: HJ4DC538X62021828 oid: 2214a635-5cc5-4f1c-b30a-b28fd61e2jan provider: mercedes-benz start_date: '2022-02-09T12:44:06.935612+00:00' tracker_id: HJ4DC538X62021828 type: oem validation_status: wrong_tracker_id vehicle_type: car Trackers that are in validation_status "connected": value: data: - end_date: null external_validation_data: null heartbeat: '2022-08-28T20:44:04.000000+00:00' motorization: null object_id: license_plate: 5006LPJ make: BMW model: X1 vin: BWA71AC0403N37625 oid: 4085a8e7-f71c-429b-93e3-62380e8c127e position: latitude: 38.253941 longitude: -2.894996 provider: bmw start_date: '2021-06-21T09:26:15.874161+00:00' tracker_id: BWA71AC0403N37625 type: oem validation_status: connected vehicle_type: car '400': description: 'Information provided in the query is incorrect o missing. ' content: application/json: schema: $ref: '#/components/schemas/ErrorSchema' examples: The specified filter_by is unavailable: value: msg: 'filter_by must be one of the following values: pending, wrong_tracker_id, pending_for_data, error_data, connected' err_code: 9900 error: 400 Company_OID was not provided: value: msg: 'company_oid: is missing' err_code: 9901 error: 400 '403': description: 'No permission to retrieve the required information. ' content: application/json: schema: $ref: '#/components/schemas/ErrorSchema' examples: Provided group_OID does not belong to your company: value: msg: You cannot read the trackers of this group. err_code: 9902 error: 403 '404': description: 'The given company OID or group OID was not found in the database. ' content: application/json: schema: $ref: '#/components/schemas/ErrorSchema' examples: Company not found: value: msg: company_oid not found. error: 404 err_code: 10003 Group not found: value: msg: group_oid not found. error: 404 err_code: 500 '415': description: 'This error is shown when the company OID or group OID string has no valid UUID format. ' content: application/json: schema: $ref: '#/components/schemas/ErrorSchema' examples: Company OID string has no valid UUID format: value: msg: oid string has not valid UUID format. error: 415 err_code: 9900 Group OID string has no valid UUID format: value: msg: oid string has not valid UUID format. error: 415 err_code: 9900 /v1/groups/: get: summary: Return a list of the groups. description: 'Returns a list of the groups. If the user does not belong to any group, the endpoint will return an empty array. ' tags: - Groups security: - BearerAuth: - read - ApiKeyAuth: - read responses: '200': description: List of user's groups. content: application/json: schema: type: array items: $ref: '#/components/schemas/GroupSchema' examples: User belongs to one or many groups: value: data: - company: cif: None city: None country: None created_at: '2022-10-24T10:52:28.337032+00:00' delete_at_period_end: false deleted: false email: None fiscal_address: None has_accepted_contract: false has_accepted_privacy_policy: false has_accepted_terms_of_service: false has_apikey: false invoicing_email: None language: es-ES name: Acme LTD oid: da887110-3c22-42ba-883a-d9380126c112 owner_oid: ea7e95fc-0efd-40b3-b51a-b6fc898d9508 phone: None postal_code: None slug: None update_at: '2022-10-24T10:52:28.337032+00:00' vat: None webhook: None description: description email: testing@testing.com name: name oid: 255b9ce8-eb9d-45c1-a619-9877b47f789d slug: slug webhook: None User does not belong to any group: value: data: [] /v1/pois/: get: summary: Gets company or group associated POIs. description: This endpoint returns the list of POIs associated with either the group or company specified. tags: - POIs security: - BearerAuth: - read - ApiKeyAuth: - read parameters: - in: query name: company_oid description: Returned POIs will be filtered by this company. Either this parameter or `group_oid` must be specified. schema: type: string required: false - in: query name: group_oid description: Returned POIs will be filtered by this group. Either this parameter or `company_oid` must be specified. schema: type: string required: false - in: query name: all description: Get both subscribed and owned POIs in the company. If not specified, only owned POIs will be returned. This only applies when the endpoint is queried with a `company_oid`. schema: type: boolean default: false required: false responses: '200': description: OK content: application/json: schema: type: array items: $ref: '#/components/schemas/PoiSchema' '415': description: Wrong request parameters. content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' examples: Invalid company_oid: value: error: 415 msg: 'company_oid: is not a valid UUID' http_code: 415 err_code: 9900 Both company_oid and group_oid missing: value: error: 415 msg: 'company_oid or group_oid: is missing' http_code: 415 err_code: 9901 /v1/commands/tracker/{tracker_id}/bluetooth/token: post: summary: Retrieve the Bluetooth token for a specific tracker. description: 'This endpoint generates and retrieves a Bluetooth token for a tracker. The token is valid for a specified time range provided via query parameters. ' tags: - Tracker Commands security: - BearerAuth: - write - ApiKeyAuth: - write parameters: - in: path name: tracker_id description: The unique identifier of the tracker. required: true schema: type: string example: 3FAHP0JA6CR302697 - in: query name: correlation_id description: An internal correlation identifier for the token request. required: true schema: type: integer example: 1 - in: query name: valid_from description: The start date and time for the token's validity (ISO 8601 format). required: true schema: type: string format: date-time example: '2025-01-01T09:12:33.001Z' - in: query name: valid_to description: The end date and time for the token's validity (ISO 8601 format). required: true schema: type: string format: date-time example: '2025-01-07T18:00:00.001Z' responses: '200': description: The token was successfully generated. content: application/json: schema: type: object properties: open: type: string close: type: string characteristicUUID: type: string idBLE: type: string serviceUUID: type: string examples: success: summary: Token successfully generated. value: open: token_open_value close: token_close_value characteristicUUID: uuid_value idBLE: ble_id_value serviceUUID: service_uuid_value '400': description: Bad request due to missing or invalid parameters. content: application/json: schema: type: object properties: error: type: string msg: type: string err_code: type: integer examples: Missing parameter: value: error: 'Invalid ''validFrom'' format. Expected ISO 8601 format: ''YYYY-MM-DDTHH:MM:SS.sssZ''.' msg: Missing required query parameters. err_code: 9901 '403': description: Access forbidden due to insufficient permissions or inactive service. content: application/json: schema: type: object properties: error: type: integer msg: type: string examples: Service inactive: value: error: 403 msg: The company does not have the service active. '404': description: Tracker ID not found. content: application/json: schema: type: object properties: error: type: integer msg: type: string err_code: type: integer examples: Tracker not found: value: error: 404 msg: Tracker ID not found. err_code: 101 '406': description: Command not supported for the tracker. content: application/json: schema: type: object properties: error: type: integer msg: type: string examples: Not supported: value: error: 406 msg: Command not available for the tracker. /v1/companies/{oid}/pois/unsubscribe: delete: summary: Unsubscribes your company from a single POI. description: 'This endpoint unsubscribes your company from a single POI. It requires the _company_oid_ as your identifier. ' tags: - Companies security: - BearerAuth: - delete - ApiKeyAuth: - delete requestBody: content: application/json: schema: properties: poiOid: type: string required: - poiOid examples: Valid POI OID in the UUID format: value: poi_oid: 4be64551-529d-4115-b91e-5a8fe803ba8a parameters: - in: path name: oid description: Company OID. required: true schema: type: string example: 95e9fca3-394c-4489-8261-6e66912df541 format: uuid responses: '200': description: OK - POI has been removed from your subscriptions. content: application/json: schema: type: array items: $ref: '#/components/schemas/PoiSchema' examples: POI has been removed from your subscriptions: value: - public: true visible: true updated_at: '2022-10-28T08:49:24.430Z' created_at: '2022-10-28T08:49:24.430Z' name: Madrid oid: 687ab1e2-9ecf-4aac-a120-3d6777d3dc92 company_oid: 33799e83-8e8d-4d78-b24d-af25eb169f98 geometry: '' info: ccaa: Madrid province: Madrid '400': description: Attribute missing. Provide the required parameters. content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' examples: POI OID missing: value: error: 400 err_code: 9901 msg: poi_oid is missing Company OID missing: value: error: 400 err_code: 9901 msg: company_oid is missing '403': description: No permission. You cannot update the POIs of this company. content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' examples: No permission to modify this company's data: value: error: 403 err_code: 9902 msg: You cannot update the company '404': description: Company or POI not found within our database. Revise the provided OIDs. content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' examples: Company OID not found: value: error: 404 err_code: 10003 msg: not found POI ID not found: value: error: 404 err_code: 801 msg: not found '415': description: Invalid OID format. The OID string has to be provided in the UUID format. content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' examples: Company OID was provided in an invalid format: value: error: 415 err_code: 9900 msg: 'oid: is incorrect' /v1/companies/{oid}/pois/subscribe: post: summary: Subscribe a company to a given poi description: 'This endpoint allows you to subscribe a company to a given poi. This feature enables you to get the POIs related to the company in a simple way. If the action is completed, it returns the subscribed POIs of the company plus the new one. ' tags: - Companies security: - BearerAuth: - write - ApiKeyAuth: - write parameters: - in: path name: oid description: Company OID. required: true schema: type: string example: 95e9fca3-394c-4489-8261-6e66912df541 format: uuid responses: '200': description: 'Returns the list of POIs that the company has subscribed. It should include the new poi, as well as the past POIs that the company subscribed. ' content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/PoiSchema' '400': description: Incorrect or missing parameters in the request. content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' examples: POI oid is missing: value: error: 400 err_code: 413 msg: poi_oid can not be missing. '403': description: You cannot subscribe this company to the poi. You don't have enough permissions to complete this action. content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' examples: User does not have permissions to subscribe the company to a poi: value: msg: You cannot update the company. error: 403 err_code: 9902 '404': description: Company or poi not found. content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' examples: Company not found: value: msg: company_oid not found error: 404 err_code: 10003 POI not found: value: msg: poi_id not found error: 404 err_code: 801 '415': description: 'This error is shown when the company OID or poi OID string has not a valid UUID format. ' content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' examples: Company OID string has not valide UUID format: value: msg: oid string has not valid UUID format. error: 415 err_code: 9900 Poi OID string has not valide UUID format: value: msg: oid string has not valid UUID format. error: 415 err_code: 9900 /v1/commands/tracker/{oid}/send_command: post: summary: Post if want to send a command to a tracker. description: 'This endpoint sends a command to a tracker. At this moment, this endpoint is only available for the trackers connected with Targa. ' tags: - Tracker Commands security: - BearerAuth: - write - ApiKeyAuth: - write parameters: - in: path name: oid description: The OID of the tracker. required: true schema: type: string example: 95e9fca3-394c-4489-8261-6e66912df541 format: uuid - in: query name: command_name description: the name of the command. required: true schema: type: string enum: - DOOR_LOCKED - DOOR_UNLOCKED - ENGINE_BLOCK_ON - ENGINE_BLOCK_OFF responses: '204': description: The command was send to the tracker. '400': description: 'Tracker OID format is wrong, must be valid UUID format. ' content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' examples: Command_name is missing: value: msg: command_name is missing error: 400 err_code: 9901 '403': description: Not enough permissions. content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' examples: You cannot update the tracker: value: error: 403 msg: You cannot update the TRACKER err_code: 9902 '404': description: Tracker not found. content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' examples: Tracker not found: value: msg: Tracker not found. error: 404 err_code: 101 '406': description: 'This error is shown when the tracker has not available this command. ' content: application/json: schema: $ref: '#/components/schemas/ErrorSchema' examples: Tracker has not available this command: value: msg: This tracker has not available this command. error: 406 '415': description: 'This error is shown when the tracker OID has no valid UUID format. ' content: application/json: schema: $ref: '#/components/schemas/ErrorSchema' examples: Tracker OID string has no valid UUID format: value: msg: oid string has no valid UUID format. error: 415 err_code: 9900 /v1/groups/{oid}/trackers/positions: get: summary: Returns trackers' last position. description: Returns a list with the last position of the trackers of one group by its group OID. tags: - Groups security: - BearerAuth: - read - ApiKeyAuth: - read parameters: - in: path name: oid description: Group OID. required: true schema: type: string example: cfd9e3bb-1158-40ab-b83f-4146d9e33447 format: uuid responses: '200': description: List of group's tracker with their last position. content: application/json: schema: type: array items: $ref: '#/components/schemas/Position' examples: Correct process: value: data: - latitude: 40.989312797928065 longitude: -3.3624383593885327 tracker_id: cartrack0 ts: '2022-11-13T11:58:04.072831+00:00' - latitude: 41.14514680993196 longitude: -3.232825861606184 tracker_id: cartrack1 ts: '2022-11-13T11:58:04.072831+00:00' - latitude: 41.03668997764376 longitude: -3.0776209544183426 tracker_id: cartrack2 ts: '2022-11-13T11:58:04.072831+00:00' - latitude: 41.543410957725015 longitude: -3.1670515054454205 tracker_id: cartrack3 ts: '2022-11-13T11:58:04.072831+00:00' - latitude: 41.76527833467426 longitude: -3.0881463611642133 tracker_id: cartrack4 ts: '2022-11-13T11:58:04.072831+00:00' - latitude: 41.225444364281714 longitude: -3.6586244742167895 tracker_id: cartrack5 ts: '2022-11-13T11:58:04.072831+00:00' - latitude: 40.63944526590116 longitude: -3.4166970422063527 tracker_id: cartrack6 ts: '2022-11-13T11:58:04.072831+00:00' - latitude: 41.135387340399774 longitude: -3.140295315234774 tracker_id: cartrack7 ts: '2022-11-13T11:58:04.072831+00:00' - latitude: 41.43643068461442 longitude: -3.606487759038501 tracker_id: cartrack8 ts: '2022-11-13T11:58:04.072831+00:00' - latitude: 41.19954052388213 longitude: -3.617131795486305 tracker_id: cartrack9 ts: '2022-11-13T11:58:04.072831+00:00' - latitude: 40.54281276608254 longitude: -3.795796653294489 tracker_id: cartrack10 ts: '2022-11-13T11:58:04.072831+00:00' - latitude: 41.27049476265155 longitude: -3.2352244057125334 tracker_id: 132ACK11 ts: '2022-11-13T11:58:04.072831+00:00' - latitude: 41.53234478175431 longitude: -3.334827779505384 tracker_id: 1ADDXBD2 ts: '2022-11-13T11:58:04.072831+00:00' - latitude: 40.408103483502735 longitude: -3.298439563502786 tracker_id: AADBBD13 ts: '2022-11-13T11:58:04.072831+00:00' - latitude: 41.27307039898459 longitude: -3.5771396100318604 tracker_id: ADFEEC14 ts: '2022-11-13T11:58:04.072831+00:00' - latitude: 40.26114949609621 longitude: -3.488879025601494 tracker_id: ASDF15 ts: '2022-11-13T11:58:04.072831+00:00' - latitude: 40.69875687983846 longitude: -3.699976437293161 tracker_id: UULASCB16 ts: '2022-11-13T11:58:04.072831+00:00' - latitude: 41.340297645400014 longitude: -3.150798513288557 tracker_id: CBDJR17 ts: '2022-11-13T11:58:04.072831+00:00' - latitude: 41.45167355019214 longitude: -3.095112784815429 tracker_id: BSCC18 ts: '2022-11-13T11:58:04.072831+00:00' - latitude: 41.34941436454212 longitude: -3.890159971268531 tracker_id: KKBAC19 ts: '2022-11-13T11:58:04.072831+00:00' '403': description: You cannot read data of the group. This error is thrown when you don't have the necessary permissions assigned to read data of the group. content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' examples: Not allowed to read data of the group: value: error: 404 msg: You cannot read the group. err_code: 9902 '404': description: Group not found. The system could not find a group for the provided oid. content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' examples: Group not found: value: error: 404 err_code: 500 msg: group_oid not found. '415': description: Group OID string has not a valid UUID format. content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' examples: Not valid UUID format: value: error: 415 err_code: 9901 msg: 'oid: is incorrect.' /v1/groups/{oid}/trackers/push: put: summary: Add trackers to a group. description: 'This endpoint allows you to assign trackers to a group within a company. This is a feature that allows you to "group" trackers within the company. For example, you can create a group to group all the vehicles that are being used by your sales team. The group could be named "sales" and then you can add the trackers to it, so you can get their positions, and statistics. ' tags: - Groups security: - BearerAuth: - read - ApiKeyAuth: - read parameters: - in: path name: oid description: Group OID. required: true schema: type: string example: cfd9e3bb-1158-40ab-b83f-4146d9e33447 format: uuid requestBody: content: application/json: schema: type: object properties: trackers: type: array items: type: object properties: oid: type: string responses: '200': description: The trackers has been successfully added. content: application/json: schema: type: object properties: group: type: object properties: oid: type: string name: type: string trackers: type: array items: type: object properties: oid: type: string tracker_id: type: string object_id: type: object '400': description: A required parameter is missing. content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' examples: Trackers parameter empty: value: err_code: 9901 error: 400 msg: 'trackers: is missing' status: error company_oid parameter empty: value: err_code: 9901 error: 400 msg: 'company_oid: is missing' status: error '404': description: Group not found. The system could not find a group for the provided oid. content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' examples: Group not found: value: error: 404 err_code: 500 msg: group_oid not found. '415': description: Group OID string has not a valid UUID format. content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' examples: Not valid UUID format: value: error: 415 err_code: 9901 msg: 'oid: is incorrect.' '500': description: The tracker could not be added to the group due to a problem when performing the action on our side. Please, contact us so we can address this issue. content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' examples: The tracker could not be added to the group: value: msg: Tracker could not be added. error: 500 err_code: 503 /v1/groups/{oid}/trackers/pop: put: summary: Removes trackers from a group description: This endpoints allows you to remove trackers from a certain group. tags: - Groups security: - BearerAuth: - read - ApiKeyAuth: - read parameters: - in: path name: oid description: Group OID. required: true schema: type: string example: cfd9e3bb-1158-40ab-b83f-4146d9e33447 format: uuid requestBody: content: application/json: schema: type: object properties: trackers: type: array items: type: string examples: Valid data: value: trackers: - 1e08f6a1-4b3c-4df7-b7d8-32ff0ddc1e71 responses: '200': description: The trackers has been successfully removed. content: application/json: schema: type: object properties: group: type: object properties: oid: type: string name: type: string trackers: type: array items: type: object properties: oid: type: string tracker_id: type: string object_id: type: object '400': description: A required parameter is missing. content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' examples: Trackers parameter is empty: value: err_code: 9901 error: 400 msg: 'trackers: is missing' status: error company_oid parameter is empty: value: err_code: 9901 error: 400 msg: 'company_oid: is missing' status: error '404': description: Group not found. The system could not find a group for the provided oid. content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' examples: Group not found: value: error: 404 err_code: 500 msg: group_oid not found. '415': description: Group OID string has not a valid UUID format. content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' examples: Not valid UUID format: value: error: 415 err_code: 9901 msg: 'oid: is incorrect.' /v1/groups/{oid}/pois/unsubscribe: delete: summary: Unsubscribe a public POI from a group. description: 'Unsubscribe a public POI from a group. When removing a POI from a group, the poi remains in the system but it will not apply anymore to the group. ' tags: - Groups security: - BearerAuth: - delete - ApiKeyAuth: - delete parameters: - in: path name: oid description: Group OID. required: true schema: type: string example: cfd9e3bb-1158-40ab-b83f-4146d9e33447 format: uuid requestBody: content: application/json: schema: properties: poiOid: type: string required: - poiOid examples: Valid data: value: poi_oid: 1e08f6a1-4b3c-4df7-b7d8-32ff0ddc1e71 responses: '200': description: The POI has been successfully unsubscribed. content: application/json: examples: Correct process: value: data: [] '400': description: A required parameter is missing. content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' examples: poiOid parameter empty: value: err_code: 9901 error: 400 msg: 'poiOid: is missing' status: error '403': description: You cannot update the group. This error is thrown when you don't have the necessary permissions assigned to update a group. content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' examples: Not allowed to update the group: value: error: 403 msg: You cannot update the group. err_code: 9902 '404': description: POI or group not found. The system could not find a group for the provided oid. content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' examples: Group not found: value: error: 404 err_code: 500 msg: group_oid not found. POI not found: value: error: 404 err_code: 801 msg: POI not found. '415': description: Group OID string has not a valid UUID format. content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' examples: Not valid UUID format: value: error: 415 err_code: 9901 msg: 'oid: is incorrect.' /v1/groups/{oid}/pois/subscribe: post: summary: Subscribe a public POI to a group. description: Subscribe a public POI to a group. The subscribed POI will appear in the list of POIs of the group. tags: - Groups security: - BearerAuth: - write - ApiKeyAuth: - write parameters: - in: path name: oid description: Group OID. required: true schema: type: string example: cfd9e3bb-1158-40ab-b83f-4146d9e33447 format: uuid requestBody: content: application/json: schema: properties: poiOid: type: string required: - poiOid examples: Valid data: value: poi_oid: 1e08f6a1-4b3c-4df7-b7d8-32ff0ddc1e71 responses: '200': description: The POI has been successfully subscribed. content: application/json: schema: $ref: '#/components/schemas/GroupSchema' examples: Correct process: value: data: - company_oid: 100fbd5d-6d61-4ff0-871c-fd26e63a0504 created_at: '2022-10-26T09:20:52.367375+00:00' geometry: coordinates: - - - -3.708057403564453 - 40.42107625193684 - - -3.721017837524414 - 40.41068593018809 - - -3.707199096679688 - 40.39839844820752 - - -3.699560165405273 - 40.40316991770238 - - -3.69114875793457 - 40.40735284561541 - - -3.691492080688477 - 40.4191159366806 - - -3.708057403564453 - 40.42107625193684 type: Polygon info: business: Low name: LEZ613 oid: 1e08f6a1-4b3c-4df7-b7d8-32ff0ddc1e71 public: false tags: - one - two - three visible: true '400': description: A required parameter is missed. content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' examples: poiOid parameter empty: value: err_code: 9901 error: 400 msg: 'poiOid: is missing' status: error '403': description: You cannot update the group. This error is thrown when you don't have the necessary permissions assigned to update a group. content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' examples: Not allowed to update the group: value: error: 403 msg: You cannot update the group. err_code: 9902 '404': description: POI or group not found. The system could not find a group for the provided oid. content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' examples: Group not found: value: error: 404 err_code: 500 msg: group_oid not found. POI not found: value: error: 404 err_code: 801 msg: POI not found. '415': description: Group OID string has not a valid UUID format. content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' examples: Not valid UUID format: value: error: 415 err_code: 9901 msg: 'oid: is incorrect.' /v1/tracking-schedules/{oid}/update: post: summary: Update an schedule for a company. description: "This endpoint allows you to modify an existing schedule. You can\ \ change the parameters that uses those schedules.\nThis schedules set in\ \ which timetable the tracker information is stored.\nUpdate schedule with:\n\ \ * name\n * description\n * schedule\n * timezone\n" tags: - Tracking Schedules security: - BearerAuth: - write - ApiKeyAuth: - write parameters: - in: path name: oid description: Schedule OID. required: true schema: type: string example: cfd9e3bb-1158-40ab-b83f-4146d9e33447 format: uuid requestBody: content: application/json: schema: type: object properties: name: type: string description: type: string schedule: type: object properties: timetable: type: object properties: Mon: type: array Tue: type: array Wed: type: array Thu: type: array Fri: type: array Sat: type: array Sun: type: array exceptions: type: array timezone: type: string examples: Schedule with exceptions: description: Create the schedule with one exception value: timezone: Pacific/Niue schedule: timetable: Mon: - - '8:00' - '10:00' - - '14:00' - '17:00' Tue: - - '8:00' - '10:00' - - '14:00' - '17:00' exceptions: - day: 1 month: 1 year: 2024 on_repeat: true company_oid: 71ecd9a1-51f0-4bb7-974b-f93feb300a49 name: Working hours description: Working hours responses: '200': description: The endpoint returns an object with the created schedule. content: application/json: schema: $ref: '#/components/schemas/TrackingSchedule' examples: Correct process: value: company_oid: eb51c264-2d19-4e11-9009-20a7bc2e9446 description: Working hours name: Working hours oid: 12f4cf73-bcc3-4462-9086-27b0a6900236 schedule: exceptions: - day: 1 month: 1 on_repeat: true year: 2024 timetable: Mon: - - '8:00' - '10:00' - - '14:00' - '17:00' Tue: - - '8:00' - '10:00' - - '14:00' - '17:00' timezone: Pacific/Niue '400': description: Required entity not specified. A required parameter is missed. content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' examples: Timetable parameter empty: value: err_code: 9901 error: 400 msg: 'timezone: is missing' status: error '403': description: You cannot update the schedule. This error is thrown when you don't have the necessary permissions assigned to update an schedule. content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' examples: Not allowed to update the schedule: value: error: 403 msg: You cannot update the schedule. err_code: 9902 /v1/tracking-schedules/{oid}/delete: delete: tags: - Tracking Schedules summary: Delete a schedule by its oid. description: 'This endpoint allows you to remove a schedule when you do not need it anymore. ' security: - BearerAuth: - delete - ApiKeyAuth: - delete parameters: - in: path name: oid description: Schedule OID. required: true schema: type: string example: cfd9e3bb-1158-40ab-b83f-4146d9e33447 format: uuid responses: '204': description: The schedule has been successfully deleted. '403': description: You cannot delete the schedule. This error is thrown when you don't have the necessary permissions assigned to delete schedules. content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' examples: No allow to delete the schedule: value: error: 403 msg: You cannot delete the schedule. err_code: 9902 '404': description: Schedule not found. The system could find an schedule for the provided oid. content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' examples: Schedule not found: value: error: 404 err_code: 600 msg: schedule_oid not found. '415': description: Schedule oid string has not a valid UUID format. content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' examples: Not valid UUID format: value: error: 415 err_code: 9901 msg: 'oid: is incorrect.' /v1/telemetrics/{tracker_oid}/dates-with-trips: get: summary: Returns a list of trip's dates for the given tracker description: 'This endpoint allows you to get a list of dates where the given tracker OID has had at least one trip. This endpoint is useful for creating a calendar for the tracker, showing on which days the tracker had at least one trip. ' tags: - Telemetrics security: - BearerAuth: - read - ApiKeyAuth: - read parameters: - in: path name: tracker_oid description: Tracker OID. schema: type: string example: 123e4567-e89b-12d3-a456-426614174000 required: true responses: '200': description: List of trip's dates for the given tracker OID content: application/json: schema: type: object properties: data: type: array items: type: string format: date-time '403': description: You don't have permission to read_trips for this tracker. content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' examples: The user session or API key does not have enough privileges to read this data: value: msg: You cannot read_trips the tracker err_code: 9902 error: 403 status: error '404': description: Tracker could not be found by its OID content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' examples: Tracker cannot be found: value: msg: tracker_id not found err_code: 101 error: 404 status: error '415': description: Tracker OID does not have a valid UUID format. content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' examples: Invalid tracker OID: value: msg: 'oid: is not a valid UUID' err_code: 9900 error: 415 status: error /v1/telemetrics/{tracker_oid}/trips-stats: get: summary: Returns statistics for all trips for the tracker OID. description: 'This endpoint returns statistics on the tracker''s trips from its creation up until the last received heartbeat. * **kms**: Total kilometers. * **time**: Total time moving within those trips. This variable is measured in seconds. The heartbeat of the tracker represents the last time the tracker has sent a valid GPS position to the system. You can filter the statistics for a range of dates using the following query parameters: * **start_date**: From this given date in this format YYYY-MM-DD. * **end_date**: To this given date in this format YYYY-MM-DD. If this value is not given, the system will use the last heartbeat of the tracker to filter the data. ' tags: - Telemetrics security: - BearerAuth: - read - ApiKeyAuth: - read parameters: - in: path name: tracker_oid description: Tracker OID. schema: type: string example: 123e4567-e89b-12d3-a456-426614174000 required: true - in: query name: start_date description: The start date, in the format YYYY-MM-DD, for filtering the trips' statistics of the tracker OID. schema: type: string format: date-time - in: query name: end_date description: The end date, in the format YYYY-MM-DD, for filtering the trips' statistics of the tracker OID. schema: type: string format: date-time responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/Stats' '403': description: You don't have permissions to read trips for this tracker. content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' examples: User session or API key does not have enough privileges to read this data: value: msg: You cannot read trips of this tracker err_code: 9902 error: 403 status: error '404': description: Tracker could not be found by its OID. content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' examples: Tracker cannot be found: value: msg: tracker_id not found err_code: 101 error: 404 status: error '415': description: Tracker OID does not have a valid UUID format. content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' examples: Invalid tracker OID: value: msg: 'oid: is not a valid UUID' err_code: 9900 error: 415 status: error /v1/companies/{oid}/remove-tracking-schedule: delete: summary: Remove a tracking schedule from a company description: 'This endpoint allows you to remove a tracking schedule from a company and all their trackers. This feature enables you to unset the tracking schedule for a single company and all their trackers. This endpoint gets the ''all'' parameter, which indicates if we want to remove the tracking schedule from all the trackers which belong to the company or only the ones which currently have the tracking schedule set. If the action is completed, it returns the updated company. ' tags: - Companies security: - BearerAuth: - write - ApiKeyAuth: - write parameters: - in: path name: oid description: Company OID. required: true schema: type: string example: 95e9fca3-394c-4489-8261-6e66912df541 format: uuid - in: query name: all description: Remove the tracking schedule from all the trackers in the company or only the ones which have the tracking schedule set. schema: type: boolean default: false required: false responses: '200': description: 'Returns the updated company. ' content: application/json: schema: $ref: '#/components/schemas/Company' '400': description: Incorrect or missing parameters in the request. content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' examples: Schedule oid is missing: value: error: 400 err_code: 413 msg: schedule_oid can not be missing. '403': description: You cannot update this company or remove the schedule. You don't have enough permissions to complete this action. content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' examples: User does not have permissions to update the company: value: msg: You cannot update the company. error: 403 err_code: 9902 User does not have permissions to remove the schedule: value: msg: You cannot remove the schedule. error: 403 err_code: 9902 '404': description: Company or schedule not found. content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' examples: Company not found: value: msg: Company oid not found error: 404 err_code: 10003 Schedule not found: value: msg: schedule_oid not found error: 404 err_code: 801 '415': description: 'This error is shown when the company OID string has not a valid UUID format. ' content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' examples: Company OID string has not valid UUID format: value: msg: oid string has not valid UUID format. error: 415 err_code: 9900 /v1/companies/{oid}/set-tracking-schedule: post: summary: Set a tracking schedule to a company description: 'This endpoint allows you to set a tracking schedule to a company and theirs trackers. This feature enables you to set the tracking schedule to a single company and all theirs trackers. This endpoint get the ''all'' parameter, which indicates if we want to set this tracking schedule to all the trackers which belong to the company or only the ones which has not a tracking schedule. If the action is completed, it returns the updated company. ' tags: - Companies security: - BearerAuth: - write - ApiKeyAuth: - write parameters: - in: path name: oid description: Company OID. required: true schema: type: string example: 95e9fca3-394c-4489-8261-6e66912df541 format: uuid - in: query name: schedule_oid description: Schedule OID. required: true schema: type: string example: 95e9fca3-394c-4489-8261-6e66912df541 format: uuid - in: query name: all description: Set the tracking schedule to all the trackers in the company or only the ones which has not tracking schedule. schema: type: boolean default: false required: false responses: '200': description: 'Returns the updated company. ' content: application/json: schema: $ref: '#/components/schemas/Company' '400': description: Incorrect or missing parameters in the request. content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' examples: Schedule oid is missing: value: error: 400 err_code: 413 msg: schedule_oid can not be missing. '403': description: You cannot update this company or read the schedule. You don't have enough permissions to complete this action. content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' examples: User does not have permissions to update the company: value: msg: You cannot update the company. error: 403 err_code: 9902 User does not have permissions to read the schedule: value: msg: You cannot read the schedule. error: 403 err_code: 9902 '404': description: Company or schedule not found. content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' examples: Company not found: value: msg: Company oid not found error: 404 err_code: 10003 Schedule not found: value: msg: schedule_oid not found error: 404 err_code: 801 '415': description: 'This error is shown when the company OID or schedule OID string has not a valid UUID format. ' content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' examples: Company OID string has not valide UUID format: value: msg: oid string has not valid UUID format. error: 415 err_code: 9900 Schedule OID string has not valide UUID format: value: msg: oid string has not valid UUID format. error: 415 err_code: 9900 /v1/importers/{oid}/cartrackfleet: post: description: Get a list of the trackers of a company registered in Cartrack and associated with your credentials. You can choose between getting all the trackers or only those not registered in our system. summary: Get a list of Cartrack registered trackers on Cartrack API of a company. tags: - Data Importers security: - ApiKeyAuth: - read parameters: - in: path name: oid description: Company OID. required: true schema: type: string example: 123e4567-e89b-12d3-a456-426614174000 format: uuid - in: query name: all description: Boolean parameter that specifies whether the returned list includes all the trackers registered in Cartrack associated with your credentials, or only the Cartrack trackers that are not registered in our system. schema: type: boolean default: false example: false/true responses: '200': description: The endpoint returns the list of trackers registered in Cartrack and associated to your company's credentials. content: application/json: schema: type: object properties: vehicles: type: array items: $ref: '#/components/schemas/TrackerSchema' total_vehicles: type: integer not_registered: type: integer examples: Trackers in Cartrack that are not registered in the system: value: not_registered: 0 total: 3 vehicles: [] All the trackers registered in Cartrack: value: not_registered: 0 total: 3 vehicles: - object_id: make: Peugeot model: tweet provider: cartrack tracker_id: 5453LBR type: canbus vehicle_type: car - object_id: make: Mercedes-Benz model: Vito provider: cartrack tracker_id: 4784LCV type: canbus vehicle_type: car - object_id: make: Peugeot model: '3008' provider: cartrack tracker_id: 1789LCY type: canbus vehicle_type: car '401': description: The token has been already used content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' examples: The token has been already used: value: error: 401 err_code: 406 msg: Token has been already used status: error '404': description: Company not found. There is not a match with what is in the database for the company OID. content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' examples: Company not found: value: error: 404 err_code: 10003 msg: company_oid not found. status: error '403': description: Connection to Cartrack not available. This usually happens because the credential is not working. content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' examples: Credential not working: value: error: 403 err_code: 605 msg: Credential is not working. status: error /v1/companies/{oid}/trackers: get: summary: Returns a list of trackers that belong to your company. description: "This endpoint returns a list of the trackers belonging to your\ \ company. It requires the _company_oid_ as your identifier.\nBy default,\ \ the output will include all your trackers and order them by _start_date_\ \ in ascending order.\nThe output can be further tailored with the help of\ \ the following filter and sorting options:\n * _Validation status._ Limits\ \ the output to trackers with the selected validation status.\n * _Active._\ \ Limits the output to trackers which are still active.\n * _Tracker ID._\ \ Limits the output to one specific tracker.\n * _Order by._ Orders the output\ \ according to the selected parameter.\n * _Ascending/Descending._ Specifies\ \ if the ordering is ascending (from small to large values) or descending\ \ (vice versa).\n If none or both are set to \"True\", the output will be\ \ ordered by _start_date_ in ascending order.\n * _All._ Returns the entire\ \ output at once without pagination.\n * _next_ and _previous_. These parameters\ \ provide the pagination functionality for browsing the returned list.\n \ \ Upon calling this endpoint for the first time, it returns the first 10 trackers.\n\ \ If there are more trackers, the returned file will include the parameter\ \ _next_ and/or _previous_.\n By passing one of these parameters into a second\ \ call of the same endpoint, the next/previous 10 trackers will be returned,\ \ together with a new _next_/_previous_.\n" tags: - Companies security: - BearerAuth: - read - ApiKeyAuth: - read parameters: - in: path name: oid description: Company OID. required: true schema: type: string example: 95e9fca3-394c-4489-8261-6e66912df541 format: uuid - in: query name: all description: Forces to include all trackers. required: false schema: type: boolean default: false - in: query name: next required: false schema: type: string example: null - in: query name: previous required: false schema: type: string example: null - in: query name: tracker_id required: false description: Tracker ID e.g. VIN, IMEI, license plate schema: type: string example: 6789ABC - in: query name: order_by required: false description: Orders trackers by the selected parameter. schema: type: string enum: - heartbeat - start_date - end_date - tracker_id default: start_date - in: query name: filter_by required: false description: Filters trackers by their validation status. schema: type: string enum: - connected - disconnected - error_access - error_not_available - error_revoked - pending - pending_for_data - pending_validation - wrong_tracker_id - in: query description: Includes only active trackers in the list. name: active required: false schema: type: boolean - in: query description: Sorts in ascending order. name: ascending required: false schema: type: boolean - in: query description: Sorts in descending order. name: descending required: false schema: type: boolean responses: '200': description: OK - List of trackers is being returned. content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/TrackerSchema' '404': description: Company not found within our database. Revise the provided OID. content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' examples: Company OID not found: value: error: 404 err_code: 10003 msg: not found '415': description: The Company OID string has to be provided in the UUID format. content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' examples: Company OID was provided in an invalid format: value: error: 415 err_code: 9900 msg: 'oid: is incorrect' /v1/companies/{oid}/update: put: summary: Update company's data. description: "This endpoint can be used to update some fields about a company.\ \ In particular, the following fields can be changed:\n\n * name: The name\ \ of the company.\n * CIF: Company legal identifier for taxes (Spain only).\n\ \ * country: Country of the company.\n * city: City of the company.\n *\ \ postal_code: Company's zip code.\n * fiscal_address: Legal address of the\ \ company.\n * email: Main email address.\n * invoicing_email: The email\ \ where invoices will be addressed to.\n * webhook: Registered webhook where\ \ notifications will POST to.\n * VAT: Company legal identifier for taxes\ \ (EU and other countries).\n * language: Preferred language for notification\ \ and transaction emails.\n" tags: - Companies security: - BearerAuth: - update - ApiKeyAuth: - update parameters: - in: path name: oid description: Company OID. required: true schema: type: string example: 123e4567-e89b-12d3-a456-426614174000 format: uuid requestBody: content: application/json: schema: type: object properties: name: type: string cif: type: string country: type: string city: type: string postal_code: type: string fiscal_address: type: string email: type: string invoicing_email: type: string webhook: type: string vat: type: string language: type: string responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/Company' '400': description: No attributes in payload. content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' example: value: msg: 'payload: is missing' error: 400 err_code: 9901 '403': description: You cannot update the company. content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' example: value: msg: forbidden error: 403 err_code: 9902 '404': description: Company not found. content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' example: value: msg: oid not found error: 404 err_code: 10003 '415': description: Company could not be updated because of an error in the request. content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' examples: Company oid has invalid UUID format: value: msg: 'oid: is incorrect' error: 415 err_code: 9900 Incorrect values in payload: value: msg: The company could not be updated error: 415 err_code: 10005 /v1/companies/{oid}/groups: get: summary: Returns a list of the groups belonging to your company. description: 'This endpoint returns a list of the groups belonging to your company. It requires the _company_oid_ as your identifier. ' tags: - Companies security: - BearerAuth: - get - ApiKeyAuth: - get parameters: - in: path name: oid description: Company OID. required: true schema: type: string example: 95e9fca3-394c-4489-8261-6e66912df541 format: uuid responses: '200': description: OK - List of groups is being returned. content: application/json: schema: type: array items: $ref: '#/components/schemas/GroupSchema' '403': description: No permission. You cannot read the groups of this company. content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' examples: No permission to read data from this company: value: error: 403 err_code: 9902 msg: You cannot read_groups the company '404': description: Company not found within our database. Revise the provided OID. content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' examples: Company OID not found: value: error: 404 err_code: 10003 msg: not found '415': description: Invalid OID format. The Company OID string has to be provided in the UUID format. content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' examples: Company OID was provided in an invalid format: value: error: 415 err_code: 9900 msg: 'oid: is incorrect' /v2/trackers/{tracker_identifier}/trips-distance-by-odometer: get: summary: Get tracker trips by oid or tracker_id. description: "Returns the list of trips for the given tracker with distance\ \ by odometer without geom.\n\nThe tracker can be identified using either:\n\ \ * its internal 'oid' (UUID), or\n * its external 'tracker_id'.\n\nYou\ \ can optionally filter the trips between 'start_date' and 'end_date'\n(inclusive).\ \ The filter is applied over the trip 'start_date'.\n" tags: - Trips security: - BearerAuth: - read - ApiKeyAuth: - read parameters: - in: path name: tracker_identifier required: true schema: type: string description: "Tracker identifier. This can be either:\n * the internal tracker\ \ 'oid' (UUID), or\n * the external 'tracker_id'.\n" - in: query name: start_date required: false schema: type: string format: date description: 'Start date (YYYY-MM-DD), inclusive. If not provided, no lower bound is applied to the trip start date. ' - in: query name: end_date required: false schema: type: string format: date description: 'End date (YYYY-MM-DD), inclusive. If not provided, no upper bound is applied to the trip start date. ' responses: '200': description: List of trips for the given tracker and date range. content: application/json: schema: type: array items: $ref: '#/components/schemas/TripOdometerSchema' '400': description: Invalid parameters (e.g. invalid date format). content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' '404': description: Tracker not found. content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' /v1/trackers/{oid}/remove-tracking-schedule: delete: summary: Remove the tracking schedule from a tracker description: 'This endpoint removes the tracking schedule from a specific tracker by clearing the `schedule_oid` field. If the action is completed, it returns the updated tracker. ' tags: - Trackers security: - BearerAuth: - write - ApiKeyAuth: - write parameters: - in: path name: oid description: Tracker OID. required: true schema: type: string example: 95e9fca3-394c-4489-8261-6e66912df541 format: uuid responses: '200': description: 'Returns the updated tracker with the schedule removed. ' content: application/json: schema: $ref: '#/components/schemas/TrackerSchema' '403': description: You do not have permission to update this tracker. content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' examples: User does not have permissions to update the tracker: value: msg: You cannot update the tracker. error: 403 err_code: 9902 '404': description: Tracker not found. content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' examples: Tracker not found: value: msg: Tracker oid not found error: 404 err_code: 10003 /v1/trackers/{oid}/set-tracking-schedule: post: summary: Set a tracking schedule to a tracker description: 'This endpoint allows you to set a tracking schedule to a tracker. This feature enables you to set the tracking schedule to a single tracker. If the action is completed, it returns the updated tracker. ' tags: - Trackers security: - BearerAuth: - write - ApiKeyAuth: - write parameters: - in: path name: oid description: Tracker OID. required: true schema: type: string example: 95e9fca3-394c-4489-8261-6e66912df541 format: uuid - in: query name: schedule_oid description: Schedule OID. required: true schema: type: string example: 95e9fca3-394c-4489-8261-6e66912df541 format: uuid responses: '200': description: 'Returns the updated tracker. ' content: application/json: schema: $ref: '#/components/schemas/TrackerSchema' '400': description: Incorrect or missing parameters in the request. content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' examples: Schedule oid is missing: value: error: 400 err_code: 413 msg: schedule_oid can not be missing. '403': description: You cannot update this tracker or read the schedule. You don't have enough permissions to complete this action. content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' examples: User does not have permissions to update the tracker: value: msg: You cannot update the tracker. error: 403 err_code: 9902 User does not have permissions to read the schedule: value: msg: You cannot read the schedule. error: 403 err_code: 9902 '404': description: Tracker or schedule not found. content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' examples: Tracker not found: value: msg: Tracker oid not found error: 404 err_code: 10003 Schedule not found: value: msg: schedule_oid not found error: 404 err_code: 801 '415': description: 'This error is shown when the tracker OID or schedule OID string has not a valid UUID format. ' content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' examples: Tracker OID string has not valide UUID format: value: msg: oid string has not valid UUID format. error: 415 err_code: 9900 Schedule OID string has not valide UUID format: value: msg: oid string has not valid UUID format. error: 415 err_code: 9900 /v1/trackers/{oid}/update: put: summary: Updates tracker attributes. description: "This endpoint allows you to update the *object_id*, the *tracker_id*,\ \ the *vehicle_type* and the *type* of the specified tracker.\nAt least one\ \ of these attributes has to be specified in the request body.\n * *object_id*:\ \ attribute which contains the vehicle's make and model associated with the\ \ tracker.\n * *tracker_id*: attribute used to identify the tracker. This\ \ is a critical parameter because it links the tracker to its data provider.\n\ \n If the tracker_id was not specified correctly during the registration\ \ procedure, the validation status of the tracker will be **wrong_tracker_id**.\ \ To rectify this issue,\n use this endpoint to provide a new tracker_id.\ \ This will restart the verification process within the data provider system.\ \ If the new verification is successful,\n the validation status will be\ \ moved to **pending**. Once the validation_status is **pending**, one can\ \ proceed with the clearance procedure using the /trackers/validate endpoint.\n" tags: - Trackers security: - BearerAuth: - update - ApiKeyAuth: - update parameters: - in: path name: oid description: Tracker OID. required: true schema: type: string example: af03a796-fa8f-4f90-9360-9d491064935d format: uuid requestBody: content: application/json: schema: $ref: '#/components/schemas/UpdateTracker' examples: Valid format: value: object_id: make: Mercedes-Benz model: SLK license_plate: 0000KKK tracker_id: W1W9106331P320573 vehicle_type: truck type: canbus responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/TrackerSchema' examples: Correct process: value: end_date: null external_validation_data: odometer: 1811 heartbeat: '2022-12-23T14:02:40.000000+00:00' motorization: null object_id: make: Mercedes-Benz model: SLK oid: af03a796-fa8f-4f90-9360-9d491064935d position: latitude: 42.878582 longitude: -2.738421 provider: mercedes-benz start_date: '2022-07-27T13:48:04.993116+00:00' tracker_id: W1W9106331P320573 type: oem validation_status: connected vehicle_type: car '400': description: "This error is returned when the request body does not include\ \ any of the following attributes:\n * object_id\n * tracker_id\n" content: application/json: schema: $ref: '#/components/schemas/ErrorSchema' examples: Missing attributes: value: msg: Missing attributes. err_code: 9901 error: 400 status: error '403': description: 'The given tracker ID is already associated with an active tracker. Review the provided information and use identifiers that are unique for each tracker. ' content: application/json: schema: $ref: '#/components/schemas/ErrorSchema' examples: VIN tracker_id already registered: value: msg: VIN tracker_id already registered. error: 403 err_code: 103 status: error '404': description: 'The given tracker OID was not found in our database. Check the provided information. ' content: application/json: schema: $ref: '#/components/schemas/ErrorSchema' examples: Tracker not found: value: msg: Tracker not found in our database. error: 404 err_code: 101 status: error '415': description: 'This error is shown when the tracker OID has no valid UUID format. ' content: application/json: schema: $ref: '#/components/schemas/ErrorSchema' examples: Tracker OID string has no valid UUID format: value: msg: oid string has not valid UUID format. error: 415 err_code: 9900 status: error /v1/trackers/{oid}/delete: delete: summary: Deletes or disconnects a tracker. description: 'This endpoint deletes or disconnects a tracker. When a tracker is requested to be deleted there are two aspects to be considered: The connectivity of the tracker and the historical data which we already obtained. In the case of trackers that have not reached the status **connected** and hence do not have any historical data associated, this endpoint simply deletes the trackers. In the case of trackers that have already been successfully connected, the connectivity of the tracker will be removed by updating their connectivity status to **disconnected**. All the historical data will remain accessible for the owner. ' tags: - Trackers security: - BearerAuth: - delete - ApiKeyAuth: - delete parameters: - in: path name: oid description: Tracker OID. schema: type: string example: cfd9e3bb-1158-40ab-b83f-4146d9e33447 required: true responses: '204': description: Tracker deleted with success. '403': description: You don't have the permission to delete this tracker. content: application/json: schema: $ref: '#/components/schemas/ErrorSchema' examples: Permission denied: value: msg: You don't have the permission to delete this tracker. error: 403 err_code: 9902 '404': description: The tracker was not found in our database. content: application/json: schema: $ref: '#/components/schemas/ErrorSchema' examples: Tracker not found: value: msg: tracker_id not found. error: 404 err_code: 101 '415': description: 'This error is shown when the tracker OID has no valid UUID format. ' content: application/json: schema: $ref: '#/components/schemas/ErrorSchema' examples: Tracker OID string has no valid UUID format: value: msg: oid string has no valid UUID format. error: 415 err_code: 9900 /v1/vehicle/versions/{id}: get: summary: Retrieves a vehicle version or all vehicle versions. description: 'This endpoint allows you to retrieve details of a specific vehicle version by its ID, or all vehicle versions if `id` is set to `all`. * If `id` is set to `"all"`, the endpoint returns a list of all vehicle versions. * If a specific `id` is provided, the endpoint returns details of that particular vehicle version. ' tags: - Vehicle Versions parameters: - name: id in: path required: true schema: type: string description: 'The unique identifier for the vehicle version. Set to `"all"` to retrieve all vehicle versions. ' responses: '200': description: 'OK - The requested vehicle version(s) has been retrieved successfully. ' content: application/json: schema: oneOf: - type: array items: $ref: '#/components/schemas/VehicleVersionSchema' - $ref: '#/components/schemas/VehicleVersionSchema' examples: all_versions: summary: All vehicle versions value: - id: 1 name: Model A doors: 4 transmission: manual engine_displacement: 2000 engine_power: 150 motorization: name: ICE fuel_types: - name: gasoline vehicle_models_makes_id: 1234 - id: 2 name: Model B doors: 2 transmission: automatic engine_displacement: 1500 engine_power: 100 motorization: name: BEV fuel_types: - name: gasoline vehicle_models_makes_id: 5678 specific_version: summary: A specific vehicle version value: id: 1 name: Model A doors: 4 transmission: manual engine_displacement: 2000 engine_power: 150 motorization: name: ICE fuel_types: - name: gasoline vehicle_models_makes_id: 1234 '404': description: 'Not Found - The requested vehicle version ID does not exist. ' content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' example: vehicle_version_not_found: value: msg: Vehicle version with ID 123 not found err_code: 1001 error: 404 status: error '400': description: 'Invalid ID - The provided ID is not valid. ' content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' example: invalid_id: value: msg: The provided ID is invalid err_code: 1000 error: 400 status: error '500': description: 'Internal Server Error - An error occurred while processing the request. ' content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' examples: server_error: value: msg: An error occurred while retrieving the vehicle version(s) err_code: 500 error: 500 status: error /v1/groups/{oid}/remove-tracking-schedule: delete: summary: Remove a tracking schedule from a group description: 'This endpoint allows you to remove a tracking schedule from a group and all their trackers. This feature enables you to unset the tracking schedule for a single group and all their trackers. This endpoint gets the ''all'' parameter, which indicates if we want to remove the tracking schedule from all the trackers which belong to the group or only the ones which currently have the tracking schedule set. If the action is completed, it returns the updated group. ' tags: - Groups security: - BearerAuth: - write - ApiKeyAuth: - write parameters: - in: path name: oid description: Group OID. required: true schema: type: string example: 95e9fca3-394c-4489-8261-6e66912df541 format: uuid - in: query name: all description: Remove the tracking schedule from all the trackers in the group or only the ones which have the tracking schedule set. schema: type: boolean default: false required: false responses: '200': description: 'Returns the updated group. ' content: application/json: schema: $ref: '#/components/schemas/GroupSchema' '400': description: Incorrect or missing parameters in the request. content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' examples: Schedule oid is missing: value: error: 400 err_code: 413 msg: schedule_oid can not be missing. '403': description: You cannot update this group or remove the schedule. You don't have enough permissions to complete this action. content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' examples: User does not have permissions to update the group: value: msg: You cannot update the group. error: 403 err_code: 9902 User does not have permissions to remove the schedule: value: msg: You cannot remove the schedule. error: 403 err_code: 9902 '404': description: Group or schedule not found. content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' examples: Group not found: value: msg: Group oid not found error: 404 err_code: 10003 Schedule not found: value: msg: schedule_oid not found error: 404 err_code: 801 '415': description: 'This error is shown when the group OID string has not a valid UUID format. ' content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' examples: Group OID string has not valid UUID format: value: msg: oid string has not valid UUID format. error: 415 err_code: 9900 /v1/groups/{oid}/set-tracking-schedule: post: summary: Set a tracking schedule to a group description: 'This endpoint allows you to set a tracking schedule to a group and theirs trackers. This feature enables you to set the tracking schedule to a single group and all theirs trackers. This endpoint get the ''all'' parameter, which indicates if we want to set this tracking schedule to all the trackers which belong to the group or only the ones which has not a tracking schedule. If the action is completed, it returns the updated group. ' tags: - Groups security: - BearerAuth: - write - ApiKeyAuth: - write parameters: - in: path name: oid description: Group OID. required: true schema: type: string example: 95e9fca3-394c-4489-8261-6e66912df541 format: uuid - in: query name: schedule_oid description: Schedule OID. required: true schema: type: string example: 95e9fca3-394c-4489-8261-6e66912df541 format: uuid - in: query name: all description: Set the tracking schedule to all the trackers in the group or only the ones which has not tracking schedule. schema: type: boolean default: false required: false responses: '200': description: 'Returns the updated group. ' content: application/json: schema: $ref: '#/components/schemas/GroupSchema' '400': description: Incorrect or missing parameters in the request. content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' examples: Schedule oid is missing: value: error: 400 err_code: 413 msg: schedule_oid can not be missing. '403': description: You cannot update this group or read the schedule. You don't have enough permissions to complete this action. content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' examples: User does not have permissions to update the group: value: msg: You cannot update the group. error: 403 err_code: 9902 User does not have permissions to read the schedule: value: msg: You cannot read the schedule. error: 403 err_code: 9902 '404': description: Group or schedule not found. content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' examples: Group not found: value: msg: Group oid not found error: 404 err_code: 10003 Schedule not found: value: msg: schedule_oid not found error: 404 err_code: 801 '415': description: 'This error is shown when the group OID or schedule OID string has not a valid UUID format. ' content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' examples: Group OID string has not valide UUID format: value: msg: oid string has not valid UUID format. error: 415 err_code: 9900 Schedule OID string has not valide UUID format: value: msg: oid string has not valid UUID format. error: 415 err_code: 9900 /v1/groups/{oid}/trackers: get: summary: Returns a list of trackers related to the group. description: "Returns a list of trackers related to the group.\n\nYou can filter\ \ trackers by the following statuses:\n\n * connected,\n * disconnected,\n\ \ * error_access,\n * error_not_available,\n * error_revoked,\n * pending,\n\ \ * pending_for_data,\n * pending_validation,\n * wrong_tracker_id\n\nYou\ \ can order the trackers using the following groups:\n\n * heartbeat,\n *\ \ start_date,\n * end_date,\n * tracker_id\n\nThe endpoint also supports the\ \ `next` and `previous` attributes to go to the next and previous pages if\ \ they exist.\n\nYou can also query only those trackers that are active. Or\ \ you can use the `all` parameter to get all the trackers, which means all\ \ the trackers in any possible state.\n" tags: - Groups security: - BearerAuth: - read - ApiKeyAuth: - read parameters: - in: path name: oid description: Group OID. required: true schema: type: string example: cfd9e3bb-1158-40ab-b83f-4146d9e33447 format: uuid - in: query name: next schema: type: string - in: query name: previous schema: type: string - in: query name: tracker_id schema: type: string - in: query name: order_by schema: type: string enum: - heartbeat - start_date - end_date - tracker_id - in: query name: filter_by schema: type: string enum: - connected - disconnected - error_access - error_not_available - error_revoked - pending - pending_for_data - pending_validation - wrong_tracker_id - in: query name: active schema: type: boolean - in: query name: ascending schema: type: boolean - in: query name: descending schema: type: boolean responses: '200': description: Gets list of trackers related to the group content: application/json: schema: type: array items: $ref: '#/components/schemas/Trackers' examples: Query with no parameters: value: data: - end_date: None external_validation_data: None heartbeat: '2022-10-25T09:57:14.346637+00:00' motorization: None object_id: foo: 1 oid: 3ace00c9-736a-4d03-a5ee-ee76747e3a07 provider: provider start_date: '2022-10-25T09:57:14.346599+00:00' tracker_id: cartrack type: obd validation_status: pending vehicle_type: car pagination: next: None previous: None total: 1 Query with parameter 'next': value: data: - end_date: None external_validation_data: None heartbeat: '2022-11-03T10:01:39.475635+00:00' motorization: None object_id: foo: 9 oid: 0c3bb271-9c46-4c07-963e-9b3b908021f3 provider: provider start_date: '2022-10-25T10:01:39.752370+00:00' tracker_id: cartrack9 type: obd validation_status: pending_for_data vehicle_type: car - end_date: None external_validation_data: None heartbeat: '2022-11-02T10:01:39.475635+00:00' motorization: None object_id: foo: 8 oid: 4d4cb7ac-07a6-49ca-a7dc-18a396f564ea provider: provider start_date: '2022-10-25T10:01:39.726890+00:00' tracker_id: cartrack8 type: obd validation_status: pending_for_data vehicle_type: car - end_date: None external_validation_data: None heartbeat: '2022-11-01T10:01:39.475635+00:00' motorization: None object_id: foo: 7 oid: 2fa3ce08-5ee4-4fa5-9e5b-d37317e6ba19 provider: provider start_date: '2022-10-25T10:01:39.699549+00:00' tracker_id: cartrack7 type: obd validation_status: pending_for_data vehicle_type: car - end_date: None external_validation_data: None heartbeat: '2022-10-31T10:01:39.475635+00:00' motorization: None object_id: foo: 6 oid: 7a36f290-7021-46ba-b66a-fb8e1a318ecb provider: provider start_date: '2022-10-25T10:01:39.668984+00:00' tracker_id: cartrack6 type: obd validation_status: pending_for_data vehicle_type: car - end_date: None external_validation_data: None heartbeat: '2022-10-30T10:01:39.475635+00:00' motorization: None object_id: foo: 5 oid: e7bb376e-b0a7-43c7-be4f-0db2807190b7 provider: provider start_date: '2022-10-25T10:01:39.643273+00:00' tracker_id: cartrack5 type: obd validation_status: pending_for_data vehicle_type: car - end_date: None external_validation_data: None heartbeat: '2022-10-29T10:01:39.475635+00:00' motorization: None object_id: foo: 4 oid: 7f103adf-1255-428d-b09c-39ed29647a06 provider: provider start_date: '2022-10-25T10:01:39.618048+00:00' tracker_id: cartrack4 type: obd validation_status: connected vehicle_type: car - end_date: None external_validation_data: None heartbeat: '2022-10-28T10:01:39.475635+00:00' motorization: None object_id: foo: 3 oid: 007dff9a-69d2-413a-a132-04fe2e9a7960 provider: provider start_date: '2022-10-25T10:01:39.592332+00:00' tracker_id: cartrack3 type: obd validation_status: connected vehicle_type: car - end_date: None external_validation_data: None heartbeat: '2022-10-27T10:01:39.475635+00:00' motorization: None object_id: foo: 2 oid: 71aa8f62-8482-48e3-a9a0-301955f7ec9f provider: provider start_date: '2022-10-25T10:01:39.566149+00:00' tracker_id: cartrack2 type: obd validation_status: connected vehicle_type: car - end_date: None external_validation_data: None heartbeat: '2022-10-26T10:01:39.475635+00:00' motorization: None object_id: foo: 1 oid: 15c64144-0036-4918-a600-7826d4e59392 provider: provider start_date: '2022-10-25T10:01:39.538769+00:00' tracker_id: cartrack1 type: obd validation_status: connected vehicle_type: car - end_date: None external_validation_data: None heartbeat: '2022-10-25T10:01:39.475635+00:00' motorization: None object_id: foo: 0 oid: 7940ea45-2c3e-44cc-b260-16eb029ebad4 provider: provider start_date: '2022-10-25T10:01:39.487340+00:00' tracker_id: cartrack0 type: obd validation_status: connected vehicle_type: car pagination: next: None previous: dt:2022-11-03 10:15:24.500094+00:00~s:2b1a57e9-a731-4030-be64-1324b149e1a1' previous: None total: 20 Query with parameter all 'true': value: data: - end_date: None external_validation_data: None heartbeat: '2022-11-13T10:17:52.261451+00:00' motorization: None object_id: foo: 19 oid: 45456671-7d3c-4581-807e-1b6240bedca7 provider: provider start_date: '2022-10-25T10:17:52.774550+00:00' tracker_id: BC19 type: obd validation_status: pending vehicle_type: car - end_date: None external_validation_data: None heartbeat: '2022-11-12T10:17:52.261451+00:00' motorization: None object_id: foo: 18 oid: bc18df4c-5abf-4bd9-a529-00ea30c4accc provider: provider start_date: '2022-10-25T10:17:52.745675+00:00' tracker_id: CVB18 type: obd validation_status: pending vehicle_type: car - end_date: None external_validation_data: None heartbeat: '2022-11-11T10:17:52.261451+00:00' motorization: None object_id: foo: 17 oid: df0c75b6-efd6-4038-ac73-3751a7634bce provider: provider start_date: '2022-10-25T10:17:52.721721+00:00' tracker_id: QQW17 type: obd validation_status: pending vehicle_type: car - end_date: None external_validation_data: None heartbeat: '2022-11-10T10:17:52.261451+00:00' motorization: None object_id: foo: 16 oid: bb596f3d-a259-4274-b787-fd5951da64fa provider: provider start_date: '2022-10-25T10:17:52.697370+00:00' tracker_id: ERER16 type: obd validation_status: pending vehicle_type: car - end_date: None external_validation_data: None heartbeat: '2022-11-09T10:17:52.261451+00:00' motorization: None object_id: foo: 15 oid: 08d6ef72-4bf0-42a4-b1fc-c12c848a94e8 provider: provider start_date: '2022-10-25T10:17:52.673658+00:00' tracker_id: BDCS15 type: obd validation_status: pending vehicle_type: car - end_date: None external_validation_data: None heartbeat: '2022-11-08T10:17:52.261451+00:00' motorization: None object_id: foo: 14 oid: 5556e6e2-6340-4908-8be1-8ecd4e4f976d provider: provider start_date: '2022-10-25T10:17:52.649734+00:00' tracker_id: WERR14 type: obd validation_status: pending vehicle_type: car - end_date: None external_validation_data: None heartbeat: '2022-11-07T10:17:52.261451+00:00' motorization: None object_id: foo: 13 oid: 079f55ec-e3ea-4b26-8fb8-fc3cdcc084dd provider: provider start_date: '2022-10-25T10:17:52.625878+00:00' tracker_id: BBDXX13 type: obd validation_status: pending vehicle_type: car - end_date: None external_validation_data: None heartbeat: '2022-11-06T10:17:52.261451+00:00' motorization: None object_id: foo: 12 oid: 01542b8d-bb24-40e3-86a8-fbe85f7c656e provider: provider start_date: '2022-10-25T10:17:52.600747+00:00' tracker_id: CBBX12 type: obd validation_status: pending vehicle_type: car - end_date: None external_validation_data: None heartbeat: '2022-11-05T10:17:52.261451+00:00' motorization: None object_id: foo: 11 oid: 80a4d02f-f4d0-4c06-8340-786dbf309ee5 provider: provider start_date: '2022-10-25T10:17:52.576696+00:00' tracker_id: CBBD11 type: obd validation_status: pending vehicle_type: car - end_date: None external_validation_data: None heartbeat: '2022-11-04T10:17:52.261451+00:00' motorization: None object_id: foo: 10 oid: 10b032be-9f67-4f26-b83c-a7c9f6074b70 provider: provider start_date: '2022-10-25T10:17:52.551238+00:00' tracker_id: cartrack10 type: obd validation_status: pending vehicle_type: car - end_date: None external_validation_data: None heartbeat: '2022-11-03T10:17:52.261451+00:00' motorization: None object_id: foo: 9 oid: 3657e6e8-49ef-4aa6-a21c-2aeee2e5287f provider: provider start_date: '2022-10-25T10:17:52.526264+00:00' tracker_id: cartrack9 type: obd validation_status: pending_for_data vehicle_type: car - end_date: None external_validation_data: None heartbeat: '2022-11-02T10:17:52.261451+00:00' motorization: None object_id: foo: 8 oid: 989ee527-4478-43c2-8fe0-c38ca7a0a2eb provider: provider start_date: '2022-10-25T10:17:52.501221+00:00' tracker_id: cartrack8 type: obd validation_status: pending_for_data vehicle_type: car - end_date: None external_validation_data: None heartbeat: '2022-11-01T10:17:52.261451+00:00' motorization: None object_id: foo: 7 oid: 2db453d0-0cce-49ba-9ebc-82916d26401c provider: provider start_date: '2022-10-25T10:17:52.476408+00:00' tracker_id: cartrack7 type: obd validation_status: pending_for_data vehicle_type: car - end_date: None external_validation_data: None heartbeat: '2022-10-31T10:17:52.261451+00:00' motorization: None object_id: foo: 6 oid: 18a3aee6-ae83-4483-928f-23c2e59810b9 provider: provider start_date: '2022-10-25T10:17:52.451368+00:00' tracker_id: cartrack6 type: obd validation_status: pending_for_data vehicle_type: car - end_date: None external_validation_data: None heartbeat: '2022-10-30T10:17:52.261451+00:00' motorization: None object_id: foo: 5 oid: 4d3e2827-3d43-40c3-94ae-0ce0d255db45 provider: provider start_date: '2022-10-25T10:17:52.425520+00:00' tracker_id: cartrack5 type: obd validation_status: pending_for_data vehicle_type: car - end_date: None external_validation_data: None heartbeat: '2022-10-29T10:17:52.261451+00:00' motorization: None object_id: foo: 4 oid: b20a45e1-0cf7-4ccf-9c17-2f7fb063d905 provider: provider start_date: '2022-10-25T10:17:52.399023+00:00' tracker_id: cartrack4 type: obd validation_status: connected vehicle_type: car - end_date: None external_validation_data: None heartbeat: '2022-10-28T10:17:52.261451+00:00' motorization: None object_id: foo: 3 oid: fffc2430-cbef-4c21-bb03-068bcc0907ae provider: provider start_date: '2022-10-25T10:17:52.372911+00:00' tracker_id: cartrack3 type: obd validation_status: connected vehicle_type: car - end_date: None external_validation_data: None heartbeat: '2022-10-27T10:17:52.261451+00:00' motorization: None object_id: foo: 2 oid: ecbb1f86-710f-4e7b-8e88-b5985ec7cc61 provider: provider start_date: '2022-10-25T10:17:52.346153+00:00' tracker_id: cartrack2 type: obd validation_status: connected vehicle_type: car - end_date: None external_validation_data: None heartbeat: '2022-10-26T10:17:52.261451+00:00' motorization: None object_id: foo: 1 oid: 7935a5c5-b7ef-4930-acd4-3263ace0f59f provider: provider start_date: '2022-10-25T10:17:52.320406+00:00' tracker_id: cartrack1 type: obd validation_status: connected vehicle_type: car - end_date: None external_validation_data: None heartbeat: '2022-10-25T10:17:52.261451+00:00' motorization: None object_id: foo: 0 oid: 66beda48-0f1f-499f-9b9d-1528f723ca46 provider: provider start_date: '2022-10-25T10:17:52.272731+00:00' tracker_id: cartrack0 type: obd validation_status: connected vehicle_type: car Query with parameter tracker_id: value: data: - end_date: None external_validation_data: None heartbeat: '2022-10-25T10:23:44.422486+00:00' motorization: None object_id: foo: 0 oid: dc101e7d-594e-4c0e-9550-027e8cbc233b provider: provider start_date: '2022-10-25T10:23:44.434040+00:00' tracker_id: cartrack0 type: obd validation_status: connected vehicle_type: car pagination: next: None previous: None total: 1 '403': description: You cannot read data of the group. This error is thrown when you don't have the necessary permissions assigned to read data of the group. content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' examples: Not allowed to read data of the group: value: error: 403 msg: You cannot read the group. err_code: 9902 '404': description: Group not found. The system could not find a group for the provided oid. content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' examples: Company not found: value: error: 404 err_code: 500 msg: group_oid not found. '415': description: Group OID string has not a valid UUID format. content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' examples: Not valid UUID format: value: error: 415 err_code: 9901 msg: 'oid: is incorrect.' /v1/groups/{oid}/update: put: summary: Updates an existing group. description: "Updates any property of a group by its group OID. You can update:\n\ \ * name: string parameter which identifies the group\n * slug: unique,\ \ human-readable identifier, alphanumeric character string without special\ \ characters or spaces.\n * company_oid: OID of the company at which the\ \ group belongs\n * webhook: url pointing to the group's webhook\n * email:\ \ email address to which notifications are sent\n" tags: - Groups security: - BearerAuth: - update - ApiKeyAuth: - update parameters: - in: path name: oid description: Group OID. required: true schema: type: string example: cfd9e3bb-1158-40ab-b83f-4146d9e33447 format: uuid requestBody: content: application/json: schema: properties: name: type: string slug: type: string company_oid: type: string webhook: type: string email: type: string examples: Valid data: value: name: ACME admin slug: acme admin responses: '200': description: The group has been successfully updated. content: application/json: schema: $ref: '#/components/schemas/GroupSchema' examples: Correct proccess: value: company: cif: None city: None country: None created_at: '2022-10-25T06:09:04.200988+00:00' delete_at_period_end: false deleted: false email: None fiscal_address: None has_accepted_contract: true has_accepted_privacy_policy: true has_accepted_terms_of_service: true has_apikey: false invoicing_email: None language: es-ES name: Company 0 oid: 45981ee1-fa2c-44a4-838b-d74c64e2c354 owner_oid: 8a29bf6f-3cc3-4254-b615-c447da849c12 phone: None postal_code: None slug: slug0 update_at: '2022-10-25T06:09:04.200988+00:00' vat: None webhook: None description: None email: org0@1234 name: ACME admin oid: 92300a31-029c-4dee-bb0b-5bd1cfe42d8a slug: acme admin webhook: None '403': description: You cannot update the group. This error is thrown when you don't have the necessary permissions assigned to update a group. content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' examples: Not allowed to update the group: value: error: 403 msg: You cannot update the group. err_code: 9902 '404': description: Group not found. The system could find a group for the provided oid. content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' examples: Group not found: value: error: 404 err_code: 500 msg: group_oid not found. '415': description: Group OID string has not a valid UUID format. content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' examples: Not valid UUID format: value: error: 415 err_code: 9901 msg: 'oid: is incorrect.' '400': description: An group already exists with the selected slug. content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' examples: Slug not unique: value: error: 400 msg: slug not unique. err_code: 501 /v1/groups/{oid}/delete: delete: summary: Deletes a group by its OID. description: 'This endpoint allows you to remove a group from the system. ' tags: - Groups security: - BearerAuth: - delete - ApiKeyAuth: - delete parameters: - in: path name: oid description: Group OID. required: true schema: type: string example: cfd9e3bb-1158-40ab-b83f-4146d9e33447 format: uuid responses: '204': description: The group has been successfully deleted. '403': description: You cannot delete the group. This error is thrown when you don't have the necessary permissions assigned to delete a group. content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' examples: Not allowed to delete the group: value: error: 403 msg: You cannot delete the group. err_code: 9902 '404': description: Group not found. The system could not find a group for the provided oid. content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' examples: Company not found: value: error: 404 err_code: 500 msg: group_oid not found. '415': description: Group OID string has not a valid UUID format. content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' examples: Not valid UUID format: value: error: 415 err_code: 9901 msg: 'oid: is incorrect.' '422': description: The request is valid but a business rule prevented the operation from completing. content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' examples: The group tracking schedule could not be updated: value: msg: Group tracking schedule could not be updated. error: 422 err_code: 505 The group notification rules could not be deleted: value: msg: Group notification rules could not be deleted. error: 422 err_code: 506 The group users could not be deleted: value: msg: Group User roles could not be deleted. error: 422 err_code: 504 '500': description: The group could not be deleted due to a problem when performing the action on our side. Please, contact us so we can address this issue. content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' examples: The group could not be deleted: value: msg: Group could not be deleted. error: 500 err_code: 503 /v1/assets/{asset_oid}/update: post: summary: Updates an existing asset. description: "This endpoint allows you to update an existing asset by its oid.\n\ You can update the following fields:\n\n * id: The unique ID of the asset,\ \ For vehicles is the VIN.\n * license_plate: The license plate of the asset\ \ if is a vehicle.\n * model_year: The year of the vehicle model.\n * tank_size:\ \ The size of the fuel tank in liters for vehicles.\n * color: Color of the\ \ asset (as an enum value).\n * alias: A friendly name for the asset.\n \ \ * battery_size: Integer with the battery size expressed in kWh for electric\ \ vehicles.\n * external_validation_data: Json with external validation id\ \ to extract information from provider. Eg. value with which to extract the\ \ information in Cartrack provider.\n * version_id: The ID of the associated\ \ vehicle version.\n * status: The asset status, available values are draft,\ \ processed, active and inactive.\n * registration_country(required): registration\ \ country code of the vehicle, it must be in format ISO 3166-1 alpha-3.\n\ \ * registration_date: The asset's registration date.\n" tags: - Assets security: - BearerAuth: - write - ApiKeyAuth: - write parameters: - in: path name: asset_oid description: Asset OID. required: true schema: type: string example: 123e4567-e89b-12d3-a456-426614174000 format: uuid requestBody: content: application/json: schema: $ref: '#/components/schemas/AssetSchema' examples: default: summary: Basic asset update. value: id: 550e8400-e29b-41d4-a716-446655440000 license_plate: ABC-1234 model_year: 2020 tank_size: 50 color: blue alias: My Car image_id: 42 battery_size: 70 external_validation_data: external_id: ABC-1234 version_id: 123 status: draft registration_country: ITA registration_date: '2024-01-01' responses: '200': description: 'The asset was created successfully. ' content: application/json: schema: $ref: '#/components/schemas/AssetSchema' '400': description: 'Missing or invalid required parameters. ' content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' examples: missing_id: value: msg: 'oid: is missing' err_code: 9901 error: 400 status: error '404': description: Asset not found. content: application/json: schema: type: object properties: error: type: string example: Asset not found status: type: string example: error '415': description: 'Incorrect data format in the request body. ' content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' '403': description: You cannot update the asset. This error is thrown when you don't have the necessary permissions assigned to update an asset. content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' examples: No allow to update the asset: value: error: 403 msg: You cannot update the asset. err_code: 9902 /v1/assets/{oid}/delete: delete: tags: - Assets summary: Delete an asset by its oid. description: 'This endpoint allows you to remove an asset when you do not need it anymore. ' security: - BearerAuth: - delete - ApiKeyAuth: - delete parameters: - in: path name: oid description: Asset OID. required: true schema: type: string example: cfd9e3bb-1158-40ab-b83f-4146d9e33447 format: uuid responses: '204': description: The asset has been successfully deleted. '403': description: You cannot delete the asset. This error is thrown when you don't have the necessary permissions assigned to delete an asset. content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' examples: No allow to delete the asset: value: error: 403 msg: You cannot delete the asset. err_code: 9902 '404': description: Asset not found. content: application/json: schema: type: object properties: error: type: string example: Asset not found status: type: string example: error /v1/pois/{oid}/delete: delete: summary: Deletes a POI. description: This endpoints deletes the POI (Point of Interest) with the given OID. tags: - POIs security: - BearerAuth: - delete - ApiKeyAuth: - delete parameters: - in: path name: oid description: POI OID. schema: type: string example: cfd9e3bb-1158-40ab-b83f-4146d9e33447 required: true responses: '204': description: POI deleted with success. '404': description: POI not found. content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' examples: POI not found: value: error: 404 msg: oid not found http_code: 404 err_code: 801 '403': description: You cannot delete the POI as you do not have enough permissions, or it belongs to a company or group you don't have access to. content: application/json: schema: $ref: '#/components/schemas/ExceptionSchema' examples: You cannot delete the POI: value: error: 403 msg: You cannot delete the POI http_code: 403 err_code: 9902 /v1/trackers/{oid}/: get: summary: Retrieves basic information about a specific tracker. description: "This endpoint returns a number of parameters associated with a\ \ given tracker identifier (tracker_oid).\nThe following parameters will be\ \ returned:\n\n * oid - The tracker's unique internal identifier.\n * tracker_id\ \ - The tracker_id is the tracker's unique identifier e.g. VIN, IMEI, license\ \ plate number...\n The format of this value depends of the provider of\ \ your tracker:\n * Option 1: for the HTML5 importer the tracker IDs can\ \ be customized. It is up to the owner to specify an identifier.\n * Option\ \ 2: for the regular data providers this is defined by each provider, as specified\ \ in the following list:\n * Mercedes-Benz: VIN\n * Cartrack:\ \ VIN or license plate\n * BMW: VIN\n * object_id - The object_id is\ \ a dictionary that contains information about the identity of the tracked\ \ object, such as the VIN or the license plate number.\n * provider - The\ \ provider of the tracker, e.g. Mercedes-Benz, BMW...\n * type - The tracker\ \ type, e.g. OEM, OBD, ...\n * vehicle_type - The vehicle type, e.g. car,\ \ van, motorcycle...\n * start_date - The date when the tracker was registered\ \ on the platform.\n * end_date - The date when the tracker was deregistered\ \ on the platform.\n * heartbeat - Timestamp of the trackers' latest data.\n\ \ * validation_status - Tracker's current status within the validation chain.\ \ For example: pending, pending validation, error_access, connected.\n * external_validation_data\ \ - An optional parameter which contains validation information from third-party\ \ data providers.\n * foreign_tracker_id - The identity of the tracker on\ \ a third-party data provider platform.\n * company_oid - The unique identifier\ \ of the company to which the tracker belongs.\n * motorization - An optional\ \ parameter which specifies the motorization of the vehicle in which the tracker\ \ is installed. Options include gasoline, diesel, electric, hydrogen, PHEV\ \ and others.\n * position - The coordinates in WGS84-format of the last position\ \ received from the tracker.\n * properties - A dictionary containing a key-value\ \ pair for each tracker property. For each property name (key), it contains\ \ a sub-dictionary (value), containing the last received reading and the associated\ \ timestamp. For properties with no associated value it will be set to None.\n" tags: - Trackers security: - BearerAuth: - read - ApiKeyAuth: - read parameters: - in: path name: oid description: Tracker OID. schema: type: string example: cfd9e3bb-1158-40ab-b83f-4146d9e33447 required: true - in: query name: property_info description: Return the description, possible values, unit and UN/CEFACT Common Code for each property. schema: type: boolean default: true required: false responses: '200': description: OK - Response that contains the accessible information about a given tracker. content: application/json: schema: $ref: '#/components/schemas/TrackerSchema' examples: Tracker data plain text: value: end_date: null external_validation_data: odometer: '1831' heartbeat: '2022-01-01T00:00:00.00000+00:00' motorization: null object_id: document: 0000XXX-2022.jpg license_plate: 0000XXX make: Mercedes-Benz model: eVito odometerLastRead: '11795' odometerLastReadings: - kms: '1831' ts: '2022-01-01T00:00:00.00000+00:00' vin: W1V00000000000000 oid: 71e2684b-66f5-46a3-b12b-33710a094bbb position: latitude: 40.464092 longitude: -3.685438 properties: altitude: property_info: data_type: float battery: property_info: data_type: float ts: '2023-03-31T18:03:48.000000+00:00' value: 43.0 behaviour.distance.electric: property_info: code: KTM data_type: float description: This value indicates the electrical driven distance since start operative, at the time of data collection. unit: km behaviour.distance.electricReset: property_info: code: KTM data_type: float description: This value indicates the electrical driven distance, since an specific reset point, at the time of data collection. unit: km behaviour.distance.fuel: property_info: code: KTM data_type: float description: This value indicates the fuel driven distance, since start operative, at the time of data collection. unit: km behaviour.distance.fuelReset: property_info: code: KTM data_type: float description: This value indicates the fuel driven distance, since an specific reset point, at the time of data collection. unit: km behaviour.distance.zeroEmissions: property_info: code: KTM data_type: float description: This value indicates the zero emission distance, since start operative, at the time of data collection. unit: km behaviour.distance.zeroEmissionsReset: property_info: code: KTM data_type: float description: This value indicates the zero emission distance, since an specific reset point, at the time of data collection. unit: km behaviour.score.acceleration: property_info: code: P1 data_type: float description: This value indicates the ECOscore rating for acceleration at the time of data collection. unit: '%' behaviour.score.constancy: property_info: code: P1 data_type: float description: This value indicates the ECOscore rating for constancy driving behaviour at the time of data collection. unit: '%' behaviour.score.freewheel: property_info: code: P1 data_type: float description: This value indicates the ECOscore rating for free wheeling at the time of data collection. unit: '%' behaviour.score.range: property_info: code: KTM data_type: float description: This value indicates the bonus range(km) achieved from the ECOscore rating at the time of data collection. unit: km behaviour.seatbelt.frontLeft: property_info: data_type: boolean description: This value indicates whether the front left seat belt was buckled up at the time of data collection. values: '0': not buckled up '1': buckled up behaviour.speed.average: property_info: code: KMH data_type: float description: This value indicates the average speed, since start operative, at the time of data collection. unit: km/h behaviour.speed.averageReset: property_info: code: KMH data_type: float description: This value indicates the average speed, since an specific reset point, at the time of data collection. unit: km/h behaviour.speed.current: property_info: code: KMH data_type: float description: The value indicates the current vehicle speed (km/h) at the time of data collection. unit: km/h behaviour.time.driving: property_info: code: MIN data_type: integer description: This value indicates the driven time(min.), since start operative, at the time of data collection. unit: min behaviour.time.drivingReset: property_info: code: MIN data_type: integer description: This value indicates the driven time(min.), since an specific reset point, at the time of data collection. unit: min behaviour.time.zeroEmissions: property_info: code: MIN data_type: integer description: This value indicates the zero emission time(min.), since start operative, at the time of data collection. unit: min behaviour.time.zeroEmissionsReset: property_info: code: MIN data_type: integer description: This value indicates the zero emission time(min.), since an specific reset point, at the time of data collection. unit: min charging.amperage.current: property_info: code: AMP data_type: float description: The charging amperage indicates the electrical current into a device in A(amps) during the charging process at the time of the data collection. unit: A charging.plugged: property_info: data_type: boolean description: The value indicates if the battery is plugged at the time of the data collection. values: '0': unplugged '1': plugged ts: '2023-07-04T02:50:49.000000+00:00' value: 0 charging.power.current: property_info: code: KWT data_type: float description: The value indicates the electrical charging power in kW at the time of the data collection. unit: kW charging.preconditioning.remaining: property_info: code: MIN data_type: float description: The value indicates the remaining time of the preconditioning to continue running. unit: min charging.preconditioning.status: property_info: data_type: boolean description: The value indicates if the preconditioning charging is active. values: '0': inactive '1': active charging.remaining.time: property_info: code: MIN data_type: integer description: The value indicates the remaining time of completion for the vehicle's full charging process at the time of the data collection. unit: min ts: '2023-07-03T19:09:30.000000+00:00' value: 1395 consumption: property_info: data_type: float ts: '2022-12-31T18:43:31.000000+00:00' value: 0.0 consumption.adBlue.percentage: property_info: code: P1 data_type: float description: The value indicates the percentage (%) of adBlue tank level at the time of data collection. unit: '%' consumption.adBlue.range: property_info: code: KTM data_type: float description: The value indicates the remaining range of adBlue in kilometers(km) at the time of the data collection. unit: km consumption.electric.average: property_info: data_type: float description: This value indicates the average electric consumption in kW·h/100 km at the time of data collection. unit: kWh/100km ts: '2023-07-04T02:50:49.000000+00:00' value: 0.0 consumption.electric.averageReset: property_info: data_type: float description: This value indicates the average electric consumption in kilowatt hours per 100 km, since an specific reset point, at the time of data collection. unit: kWh/100km ts: '2023-07-04T02:50:49.000000+00:00' value: 0.0 consumption.electric.max: property_info: code: KTM data_type: float description: The value indicates the maximum electrical range in km with the 100% SoC. unit: km ts: '2023-07-04T03:18:40.000000+00:00' value: 148.0 consumption.electric.percentage: property_info: code: P1 data_type: float description: This value indicates the current State of Charge level in percent (%) at the time of data collection. unit: '%' ts: '2023-07-04T02:50:49.000000+00:00' value: 100.0 consumption.electric.range: property_info: code: KTM data_type: float description: The value indicates the remaining range of fuel in kilometers (km) at the time of the data collection. unit: km ts: '2023-07-04T03:18:40.000000+00:00' value: 148.0 consumption.fuel.average: property_info: code: R10 data_type: float description: The value indicates the average fuel consumption in liters per 100 km at the time of data collection. unit: l/100km consumption.fuel.averageReset: property_info: code: R10 data_type: float description: This value indicates the average fuel consumption in liters per 100 km, since an specific reset point, at the time of data collection. unit: l/100km consumption.fuel.percentage: property_info: code: P1 data_type: float description: The value indicates the percentage (%) of fuel tank level at the time of data collection. unit: '%' consumption.fuel.range: property_info: code: KTM data_type: float description: The value indicates the remaining range of fuel in kilometer (km) at the time of the data collection. unit: km consumption.fuel.rangeWarning: property_info: data_type: boolean description: The value indicates if the remaining range of fuel is a critical state at the time of the data collection. values: '0': not in critical state '1': in critical state consumption.fuel.tank: property_info: code: LTR data_type: float description: The value indicates the current fuel tank level in liters (l) at the time of data collection. unit: l consumption.fuel.warning: property_info: data_type: float description: The value indicates whether a warning for fuel level is triggered. values: '0': not warning '1': warning device.battery.percentage: property_info: code: P1 data_type: float description: The value represents the percent of battery level of the device at the time of the data collection. unit: '%' device.battery.voltage: property_info: code: VLT data_type: float description: The value indicates the current battery voltage(V) of the device at the time of the data collection. unit: V device.gps.odometer: property_info: code: KTM data_type: float description: The value represents the calculated vehicle odometer based on GPS coordinates. unit: km device.gps.speed: property_info: code: KMH data_type: float description: The value represents the calculated vehicle speed based on GPS coordinates. unit: km/h doors.frontLeft.locked: property_info: data_type: boolean description: This value indicates whether the front left door was locked at the time of data collection. values: '0': unlocked '1': front left door locked ts: '2023-07-03T19:09:06.000000+00:00' value: 1 doors.frontLeft.open: property_info: data_type: boolean description: The value indicates whether the front left door was closed at the time of data collection. values: '0': closed '1': front left door open ts: '2023-07-03T19:09:04.000000+00:00' value: 0 doors.frontRight.locked: property_info: data_type: boolean description: This value indicates whether the front right door was locked at the time of data collection. values: '0': unlocked '1': front right door locked ts: '2023-07-03T19:09:06.000000+00:00' value: 1 doors.frontRight.open: property_info: data_type: boolean description: The value indicates whether the front right door was closed at the time of data collection. values: '0': closed '1': front right door open ts: '2023-07-03T15:02:48.000000+00:00' value: 0 doors.hood.open: property_info: data_type: boolean description: This value indicates whether the hood is open at the time of data collection. values: '0': closed '1': hood door open doors.locked: property_info: data_type: boolean description: This value indicates whether the vehicle doors are locked at the time of data collection. values: '0': unlocked '1': all doors locked ts: '2023-07-03T19:09:06.000000+00:00' value: 1 doors.rearLeft.locked: property_info: data_type: boolean description: This value indicates whether the rear left door was locked at the time of data collection. values: '0': unlocked '1': rear left door locked doors.rearLeft.open: property_info: data_type: boolean description: The value indicates whether the rear left door was closed at the time of data collection. values: '0': closed '1': rear left door open doors.rearRight.locked: property_info: data_type: boolean description: This value indicates whether the rear right door was locked at the time of data collection. values: '0': unlocked '1': rear right door locked ts: '2023-07-03T19:09:06.000000+00:00' value: 1 doors.rearRight.open: property_info: data_type: boolean description: The value indicates whether the rear right door was closed at the time of data collection. values: '0': closed '1': rear right door open ts: '2023-07-03T07:36:20.000000+00:00' value: 0 doors.rooftop.open: property_info: data_type: boolean description: This value indicates whether the roof is open at the time of data collection. values: '0': closed '1': rooftop door open doors.tankcap.open: property_info: data_type: boolean description: This value indicates whether the tankcap is open at the time of data collection. values: '0': closed '1': tankcap door open ts: '2022-12-19T16:57:12.000000+00:00' value: 0 doors.trunk.locked: property_info: data_type: boolean description: This value indicates whether the truck is locked at the time of data collection. values: '0': unlocked '1': trunk door open ts: '2023-07-03T19:09:06.000000+00:00' value: 1 doors.trunk.open: property_info: data_type: boolean description: The value indicates whether the trunk is open. values: '0': closed '1': open ts: '2023-07-03T19:01:10.000000+00:00' value: 0 engine.brakes.fluid.warning: property_info: data_type: boolean description: The value indicates whether a warning for the brake fluid is triggered. values: '0': not warning '1': warning engine.brakes.pads.prewarning: property_info: data_type: boolean description: The value indicates whether a previous warning for the brakepads is triggered. values: '0': no warning '1': brakepads previous warning engine.brakes.pads.warning: property_info: data_type: boolean description: 'The value indicates whether a warning for the brakepads is triggered. ' values: '0': no warning '1': brakepads warning engine.brakes.park: property_info: data_type: boolean description: The value indicates if the park brake is active (true). values: '0': inactive '1': park brake active engine.coolant.temperature: property_info: code: CEL data_type: float description: The value indicates the engine coolant temperature. unit: ºC engine.coolant.warning: property_info: data_type: boolean description: The value indicates whether a warning for the coolant level is triggered. values: '0': no warning '1': low coolant level warning engine.dashboard: property_info: data_type: boolean description: The value indicates if the control and information panel is on (true). values: '0': dashboard off '1': dashboard on engine.electric.mode: property_info: data_type: boolean description: The value indicates if the electrical engine mode is on at the time of the data collection. values: '0': 'off' '1': electrical engine mode on engine.electric.temperature: property_info: code: CEL data_type: float description: The value indicates the battery temperature in Celsius (ºC) at the time of the data collection. unit: ºC engine.limpMode.status: property_info: data_type: boolean description: The value indicates whether a warning for the limp mode is active. values: '0': inactive '1': limp mode active engine.oil.percentage: property_info: code: P1 data_type: float description: The value indicates the percentage (%) of oil level at the time of data collection. unit: '%' engine.oil.warning: property_info: data_type: boolean description: The value indicates whether a warning for the oil level is triggered. values: '0': no warning '1': low oil level warning engine.supplyBattery.voltage: property_info: code: VLT data_type: float description: The value indicates the current battery voltage (V) at the time of the data collection. unit: V engine.supplyBattery.warning: property_info: data_type: boolean description: The value indicates whether a warning for the supply battery is triggered. values: '0': no warning '1': supply battery warning engine.washWater.warning: property_info: data_type: boolean description: The value indicates whether a warning for the wash water level is triggered. values: '0': no warning '1': low wash water level warning fuel: property_info: data_type: float heading: property_info: data_type: float ignition: property_info: data_type: boolean ts: '2023-05-18T08:09:53.000000+00:00' value: 0 ignition.status: property_info: data_type: boolean description: The value indicates the status of the ignition of the vehicle at the time of the data collection. values: '0': 'off' '1': 'on' '2': stand by ts: '2023-06-22T09:37:02.000000+00:00' value: 0 lights: property_info: data_type: boolean ts: '2023-05-17T17:21:59.000000+00:00' value: 1 lights.interior.front.on: property_info: data_type: boolean description: This value indicates whether the interior light is on at the time of data collection. values: '0': 'off' '1': interior front lights on ts: '2023-07-03T19:09:10.000000+00:00' value: 0 lights.interior.readingFrontLeft.on: property_info: data_type: boolean description: This value indicates whether the interior reading lamp at the front left is on at the time of data collection. values: '0': 'off' '1': front left reading lamp on ts: '2023-06-15T11:29:19.000000+00:00' value: 0 lights.interior.readingFrontRight.on: property_info: data_type: boolean description: This value indicates whether the interior reading lamp at the front right is on at the time of data collection. values: '0': 'off' '1': front right reading lamp on ts: '2023-06-15T11:27:22.000000+00:00' value: 0 lights.interior.rear.on: property_info: data_type: boolean description: This value indicates whether the interior light is on at the time of data collection. values: '0': 'off' '1': rear lights on odometer: property_info: code: KTM data_type: float description: Odometer or mileage value at the time of data collection. unit: km ts: '2023-07-03T19:03:30.000000+00:00' value: 11617.0 position.altitude: property_info: code: MTR data_type: float description: The value represents the altitude of the vehicle above sea-level at the time of data collection. The value range reaches from -100m to 6000m. unit: m position.heading: property_info: data_type: float description: This value indicates the angle of the vehicle's orientation in degrees (º) at the data collection . A value of 180 signifies that the vehicle is facing due south, while a value of 0 indicates it is facing due north. The range of possible values spans from 0 to 359 degrees. unit: degrees ts: '2023-07-03T19:04:00.000000+00:00' value: 11.7 security.alarm.status: property_info: data_type: boolean description: This value indicates whether the anti-theft system is armed at the time of data collection. values: '0': not armed '1': anti-theft system armed security.alarm.warning: property_info: data_type: boolean description: The value indicates whether a warning for anti-theft system alarm is triggered. values: '0': no warning '1': anti-theft system warning security.interior.status: property_info: data_type: boolean description: This value indicates whether the interior protection sensors are active at the time of data collection. values: '0': inactive '1': interior protector sensors active security.interior.warning: property_info: data_type: boolean description: The value indicates whether a warning from the interior protector sensors are triggered. values: '0': no warning '1': interior protector sensors warning security.tow.status: property_info: data_type: boolean description: This value indicates whether the tow protection sensors are active at the time of data collection. values: '0': inactive '1': tow protector sensors active security.tow.warning: property_info: data_type: boolean description: The value indicates whether a warning from the tow protector sensors are triggered. values: '0': no warning '1': tow protector sensors warning service.distance: property_info: code: KTM data_type: float description: This value indicates the distance remaining, in kilometers(km), before the next scheduled service at the time of data collection. unit: km service.time: property_info: code: DAY data_type: integer description: The value indicates the days left the vehicle is approaching its next scheduled service. unit: d speed: property_info: data_type: float ts: '2023-07-03T19:03:45.000000+00:00' value: 52.9 tires: property_info: data_type: boolean ts: '2023-05-18T08:07:56.000000+00:00' value: 325 wheels.frontLeft.pressure: property_info: code: KPA data_type: float description: This value indicates the measured tyre pressure on the front left in kilopascal (kPa). unit: kPa ts: '2023-07-03T19:02:12.000000+00:00' value: 332.5 wheels.frontLeft.warning: property_info: data_type: boolean description: The value indicates whether a warning for the front left wheel is triggered. values: '0': no warning '1': front left wheel warning ts: '2023-07-03T19:05:20.000000+00:00' value: 0 wheels.frontRight.pressure: property_info: code: KPA data_type: float description: This value indicates the measured tyre pressure on the front right in kilopascal (kPa). unit: kPa ts: '2023-07-03T19:03:30.000000+00:00' value: 362.5 wheels.frontRight.warning: property_info: data_type: boolean description: The value indicates whether a warning for the front right wheel is triggered. values: '0': no warning '1': front right wheel warning ts: '2023-07-03T19:05:20.000000+00:00' value: 0 wheels.rearLeft.pressure: property_info: code: KPA data_type: float description: This value indicates the measured tyre pressure on the rear left in kilopascal (kPa). unit: kPa ts: '2023-07-03T18:54:04.000000+00:00' value: 330.0 wheels.rearLeft.warning: property_info: data_type: boolean description: The value indicates whether a warning for the rear left wheel is triggered. values: '0': no warning '1': rear left wheel warning ts: '2023-07-03T19:05:20.000000+00:00' value: 0 wheels.rearRight.pressure: property_info: code: KPA data_type: float description: This value indicates the measured tyre pressure on the rear right in kilopascal (kPa). unit: kPa ts: '2023-07-03T19:02:11.000000+00:00' value: 327.5 wheels.rearRight.warning: property_info: data_type: boolean description: The value indicates whether a warning for the rear right wheel is triggered. values: '0': no warning '1': rear right wheel warning ts: '2023-07-03T19:05:20.000000+00:00' value: 0 windows: property_info: data_type: boolean ts: '2023-05-18T07:01:33.000000+00:00' value: 0 windows.frontLeft.open: property_info: data_type: boolean description: This value indicates whether the front left window is open at the time of data collection. values: '0': closed '1': front left window open ts: '2023-07-03T19:03:56.000000+00:00' value: 0 windows.frontRight.open: property_info: data_type: boolean description: This value indicates whether the front right window is open at the time of data collection. values: '0': closed '1': front right window open ts: '2023-07-03T19:03:54.000000+00:00' value: 0 windows.rearLeft.open: property_info: data_type: boolean description: This value indicates whether the rear left window is open at the time of data collection. values: '0': closed '1': rear left window open windows.rearRight.open: property_info: data_type: boolean description: This value indicates whether the rear right window is open at the time of data collection. values: '0': closed '1': rear right window open provider: mercedes-benz start_date: '2022-10-13T15:38:41.892373+00:00' tracker_id: W1V44760313923683 type: oem validation_status: connected vehicle_type: van '404': description: 'The given tracker OID was not found. Revise the provided information. ' content: application/json: schema: $ref: '#/components/schemas/ErrorSchema' examples: Tracker not found: value: msg: Tracker not found in our database. error: 404 err_code: 101 '415': description: 'This error is shown when the tracker OID has no valid UUID format. ' content: application/json: schema: $ref: '#/components/schemas/ErrorSchema' examples: Tracker OID string has no valid UUID format: value: msg: oid string has no valid UUID format. error: 415 err_code: 9900 /v1/assets/{asset_oid}: get: summary: Get an asset by its OID. description: 'This endpoint retrieves an asset based on the provided OID. If the asset is not found, it returns a 404 error. ' tags: - Assets parameters: - in: path name: asset_oid required: true schema: type: string description: The OID of the asset to retrieve. responses: '200': description: The asset details. content: application/json: schema: $ref: '#/components/schemas/AssetSchema' '404': description: Asset not found. content: application/json: schema: type: object properties: error: type: string example: Asset not found status: type: string example: error info: title: Astara Connect API v1 version: 1.213.0 openapi: 3.0.2 components: schemas: ExternalValidationData: type: object properties: document: type: string odometer: type: integer format: int32 minimum: 0 foreign_provider_id: type: string ContactPerson: type: object properties: name: type: string email: type: string format: email phone: type: string required: - email - name - phone AssetRegisterRequestSchema: type: object properties: provider: type: string enum: - mercedes-benz - bmw - cartrack - targa - stellantis - hyundai-kia - html5 - ford - renault - toyota - volkswagen installation_order: type: boolean registration_country: type: string pattern: ^[A-Z]{3}$ id: type: string type: type: string enum: - oem - obd - CANbus version_id: type: string packages: type: array minItems: 1 items: type: string model_year: type: integer format: int32 minimum: 1900 maximum: 2100 license_plate: type: string tank_size: type: integer format: int32 minimum: 0 color: type: string enum: - aqua - aubergine - beige - black - blue - brown - dark grey - green - light grey - olive - orange - pink - purple - red - silver - teal - white - yellow alias: type: string battery_size: type: integer format: int32 minimum: 0 external_validation_data: $ref: '#/components/schemas/ExternalValidationData' company_oid: type: string registration_date: type: string format: date company_address_oid: type: string format: uuid contact_person: $ref: '#/components/schemas/ContactPerson' credentials: description: 'JSON object with provider-specific credentials must include exactly the required keys: - cartrack: { url, token } - hyundai-kia: { username, password, pin }' oneOf: - $ref: '#/components/schemas/CartrackCredsSchema' - $ref: '#/components/schemas/TargaCredsSchema' - $ref: '#/components/schemas/HyundaiKiaCredsSchema' credential_oid: type: string odo_value: type: integer format: int32 minimum: 0 required: - company_oid - id - installation_order - model_year - packages - provider - registration_country - type - version_id description: ' Constraints (documented; enforced at runtime): - If provider=''targa'' and installation_order=true: require company_address_oid and contact_person. - If provider=''mercedes-benz'': require odo_value. - require credentials when provider is one of [cartrack, hyundai-kia]. ' AssetSchema: type: object properties: image_id: type: integer format: int32 nullable: true version_id: type: integer format: int32 alias: type: string nullable: true external_validation_data: type: object nullable: true registration_date: type: string format: date readOnly: true updated_at: type: string format: date-time readOnly: true oid: type: string color: type: string enum: - aqua - aubergine - beige - black - blue - brown - dark grey - green - light grey - olive - orange - pink - purple - red - silver - teal - white - yellow nullable: true battery_size: type: object nullable: true default: gross: '0' net: '0' provided: '0' unit: kWh model_year: type: integer format: int32 nullable: true status: type: string enum: - draft - processed - active - inactive tank_size: type: integer format: int32 nullable: true registration_country: type: string model: type: string readOnly: true license_plate: type: string nullable: true version: type: string readOnly: true created_at: type: string format: date-time readOnly: true id: type: string make: type: string readOnly: true required: - id - registration_country - status - version_id CartrackCredsSchema: type: object properties: url: type: string format: url token: type: string required: - token - url additionalProperties: false CartrackSchema: type: object properties: o_odometer: type: number format: float o_speed: type: number format: float o_event_location: type: string o_latitude: type: number format: float o_ignition: type: integer format: int32 o_event_ts: readOnly: true o_longitude: type: number format: float ContactPersonSchema: type: object properties: name: type: string email: type: string format: email phone: type: string required: - email - name - phone ErrorSchema: type: object properties: error: type: string msg: type: string EventsSchema: type: object properties: longitude: type: number format: float ts: type: string format: date-time latitude: type: number format: float name: type: string ExceptionSchema: type: object properties: status: type: string error: type: number err_code: type: string msg: type: string ExternalValidationDataSchema: type: object properties: document: type: string odometer: type: integer format: int32 minimum: 0 foreign_provider_id: type: string FuelTypesSchema: type: object properties: name: type: string required: - name Company: type: object properties: owner_oid: type: string fiscal_address: type: string slug: type: string delete_at_period_end: type: boolean email: type: string code: type: string has_accepted_privacy_policy: type: boolean product: type: string schedule_oid: type: string nullable: true oid: type: string has_accepted_contract: type: boolean invoicing_email: type: string phone: type: string city: type: string language: type: string country: type: string name: type: string update_at: type: string format: date-time cif: type: string has_apikey: type: boolean deleted: type: boolean postal_code: type: string created_at: type: string format: date-time readOnly: true webhook: type: string has_accepted_terms_of_service: type: boolean vat: type: string GroupSchema: type: object properties: slug: type: string schedule_oid: type: string nullable: true company: readOnly: true allOf: - $ref: '#/components/schemas/Company' oid: type: string name: type: string description: type: string webhook: type: string email: type: string Html5Schema: type: object properties: longitude: type: number format: float time: type: string format: date-time ts: type: string format: date-time latitude: type: number format: float HyundaiKiaCredsSchema: type: object properties: username: type: string password: type: string pin: type: string refresh_token: type: string required: - password - pin - username additionalProperties: false ManufacturerSchema: type: object properties: name: type: string MotorizationSchema: type: object properties: name: type: string required: - name NotificationInboxSchema: type: object properties: trash: readOnly: true group_oid: type: string nullable: true user_oid: type: string notification_oid: type: string nullable: true read: readOnly: true favorite: readOnly: true tracker_oid: type: string nullable: true oid: type: string readOnly: true created_at: type: string format: date-time readOnly: true info: type: object event_type: type: string Poi: type: object properties: public: type: boolean company_oid: type: string updated_at: type: string format: date-time oid: type: string name: type: string geometry: readOnly: true visible: type: boolean created_at: type: string format: date-time tags: type: array items: type: string info: type: object NotificationRuleSchema: type: object properties: enable: type: boolean min_distance_to_poi: type: integer format: int32 user_oid: type: string nullable: true disable_rule_at: type: string format: date-time trips_max_kms_in_total: type: integer format: int32 inside_poi: type: boolean trips_max_kms_per_day: type: integer format: int32 days_of_the_week: type: array items: type: integer format: int32 updated_at: type: string format: date-time readOnly: true oid: type: string readOnly: true description: readOnly: true is_mileage: type: boolean enable_rule_at: type: string format: date-time notify_by_email: type: boolean close_to_poi: type: boolean poi: readOnly: true allOf: - $ref: '#/components/schemas/Poi' group_oid: type: string nullable: true poi_oid: type: string nullable: true enabled: type: boolean company_oid: type: string movement_time_slot_start: type: string trips_max_kms_per_week: type: integer format: int32 rule_email: type: string nullable: true max_time_at_poi: type: integer format: int32 report_7days_inactive: type: boolean trips_max_kms_per_month: type: integer format: int32 tracker_oid: type: string nullable: true movement_time_slot_end: type: string notify_by_webhook: type: boolean deleted: type: boolean outside_poi: type: boolean link_type: type: string enum: - tracker-travels-more-than-n-km - tracker-outside-geofence - tracker-inside-geofence - tracker-close-to-poi - tracker-inside-geofence-for-more-than-n-minutes - device-disconnected - towing-event - crash-event - engine-blocked-event - tracker-property-min-value - tracker-property-equal-boolean-value - tracker-property-max-value - block-engine - maintenance-notification nullable: true created_at: type: string format: date-time readOnly: true odometer_maintenance: type: integer format: int32 webhook: type: string nullable: true required: - company_oid PackageProviderSchema: type: object properties: provider_oid: type: string description: type: string oid: type: string info: type: object PackageProviderSlimSchema: type: object properties: provider_oid: type: string description: type: string oid: type: string info: readOnly: true PoiSchema: type: object properties: public: type: boolean company_oid: type: string updated_at: type: string format: date-time oid: type: string name: type: string geometry: readOnly: true visible: type: boolean created_at: type: string format: date-time tags: type: array items: type: string info: type: object TargaCredsSchema: type: object properties: client_id: type: string client_secret: type: string required: - client_id - client_secret additionalProperties: false TelemetricSchema: type: object properties: tracker_id: type: string oid: type: string longitude: type: number format: float ts: type: string format: date-time latitude: type: number format: float info: type: object ConnectionStatus: type: object properties: connected: type: boolean nullable: true ts: type: string format: date-time TrackerHealthSchema: type: object properties: obd: $ref: '#/components/schemas/ConnectionStatus' health: type: string enum: - good - medium - bad battery: $ref: '#/components/schemas/ConnectionStatus' TrackerOrderSchema: type: object properties: user_oid: type: string updated_at: type: string format: date-time readOnly: true external_oid: type: string nullable: true oid: type: string tracker_oid: type: string description: type: string created_at: type: string format: date-time readOnly: true payload: type: object order_status: type: string required: - tracker_oid TrackerPositionSchema: type: object properties: longitude: type: number format: float ts: type: string format: date-time latitude: type: number format: float tracker_id: type: string TrackerPropertiesSchema: type: object properties: tracker_id: type: string key: type: string value: type: number format: float tracker_oid: type: string oid: type: string ts: type: string format: date-time TrackerSchema: type: object properties: provider: type: string validation_status: type: string end_date: type: string format: date-time nullable: true external_validation_data: type: object tracker_id: type: string schedule_oid: type: string nullable: true type: type: string enum: - oem - obd - canbus - iot asset_oid: type: string nullable: true object_id: type: object heartbeat: type: string format: date-time company_oid: type: string writeOnly: true oid: type: string vehicle_type: {} position: type: object readOnly: true start_date: type: string format: date-time motorization: type: object readOnly: true foreign_tracker_id: type: string writeOnly: true required: - provider TripOdometerSchema: type: object properties: end_date: type: string format: date-time nullable: true avg_speed_by_odometer: type: number format: float nullable: true tracker: readOnly: true allOf: - $ref: '#/components/schemas/TrackerSchema' oid: type: string distance_by_odometer: type: number format: float nullable: true start_date: type: string format: date-time TripSchema: type: object properties: vertex_number: type: integer format: int32 distance: type: number format: float end_date: type: string format: date-time nullable: true avg_speed_by_mm_geom: type: number format: float nullable: true geojson: {} avg_speed_by_odometer: type: number format: float nullable: true end_address: type: object oid: type: string tracker: readOnly: true allOf: - $ref: '#/components/schemas/TrackerSchema' start_address: type: object distance_by_odometer: type: number format: float nullable: true points_oid: type: array items: type: string avg_speed_by_geom: type: number format: float nullable: true start_date: type: string format: date-time geojson_mm: {} distance_by_mm_geom: type: number format: float nullable: true distance_by_geom: type: number format: float nullable: true Roles: type: object properties: company_oid: type: string role: type: string Roles1: type: object properties: group_oid: type: string name: readOnly: true UserSchema: type: object properties: fullname: type: string roles_user_company: readOnly: true allOf: - $ref: '#/components/schemas/Roles' validated: type: boolean roles_user_group: readOnly: true allOf: - $ref: '#/components/schemas/Roles1' oid: type: string dashboard: type: object active_company: type: string phone: type: string admin: type: boolean companies: readOnly: true type: array items: $ref: '#/components/schemas/Company' companies_membership: readOnly: true type: array items: $ref: '#/components/schemas/Company' has_accepted_marketing_contact: type: boolean email: type: string VehicleMakeSchema: type: object properties: name: type: string VehicleModelMakeSchema: type: object properties: vehicle_type: type: string id: type: integer format: int32 name: type: string VehicleModelSchema: type: object properties: manufacturer: type: string countries_alias: type: object updated_at: type: string format: date-time oid: type: string name: type: string created_at: type: string format: date-time readOnly: true info: type: object VehicleTypeSchema: type: object properties: name: type: string VehicleVersionSchema: type: object properties: motorization: readOnly: true engine_power: type: object nullable: true transmission: type: string nullable: true type_approval: type: string nullable: true updated_at: type: string format: date-time readOnly: true vehicle_model: readOnly: true name: type: string nullable: true concat_version: readOnly: true fuel_types: readOnly: true created_at: type: string format: date-time readOnly: true id: type: integer format: int32 vehicle_make: readOnly: true doors: type: string nullable: true engine_displacement: type: object nullable: true wltp: type: object nullable: true required: - id TrackingSchedule: type: object properties: company_oid: type: string oid: type: string name: type: string schedule: type: object description: type: string timezone: type: string Trips: type: object properties: pagination: readOnly: true data: readOnly: true RegisterTracker: type: object properties: company_oid: type: string writeOnly: true tracker_id: type: string provider: type: string type: type: string enum: - oem - obd - canbus - iot vehicle_type: type: string enum: - car - van - other nullable: true packages: type: array description: Assigning packages requires the definition of an object_id. items: type: string enum: - mercedesbenzmileage - mercedesbenzelectrotest - mercedesbenzextended object_id: type: object description: 'The keys may include any combination of the following: make, model, vin, and license_plate.' required: - company_oid - provider - tracker_id - type ValidateTracker: type: object properties: provider: type: string odo_value: type: integer format: int32 tracker_id: type: string type: type: string enum: - oem - obd - canbus - iot required: - provider Position: type: object properties: longitude: type: number format: float ts: type: string format: date-time latitude: type: number format: float Stats: type: object properties: time: type: integer format: int32 kms: type: number format: float ObjectId: type: object properties: make: type: string nullable: true model: type: string nullable: true vin: type: string nullable: true license_plate: type: string nullable: true UpdateTracker: type: object properties: object_id: nullable: true allOf: - $ref: '#/components/schemas/ObjectId' type: type: string enum: - oem - obd - canbus - iot nullable: true tracker_id: type: string nullable: true vehicle_type: {} Trackers: type: object properties: pagination: readOnly: true data: readOnly: true securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-BOTON-APIKEY BearerAuth: type: http scheme: bearer bearerFormat: JWT