Basic Information

Endpoint

/api-impexp/

Overview

GIR W150 is a fuel management system, composed of one central server and one or several controllers. It allows to:

  • Define, on the central server, a list of vehicles (and optionally: drivers) that are allowed to take fuel.
  • Synchronize vehicles and drivers to controllers. Controllers are hardware devices which control the physical refueling. They can operate without a permanent link to the central server.
  • Retrieve fuel transactions from controllers. Vehicles and drivers are identified on controllers either by presenting a badge or entering a code. This information is captured during each refueling, and stored along with other relevant details (date, volume, etc.) in a "fuel transaction" record.

This page describes web services to interface GIR W150 central server with a third-party system. It provides a REST API in JSON format.

All web services start with the common base URL of <app_url>/api-impexp/ where <app_url> is the same URL you use to access the application web interface. HTTP methods GET, POST, PUT, and DELETE are used to perform the different operations.

Vehicles are available at /api-impexp/vehicles:

Drivers are available at /api-impexp/drivers:

Fuel transactions are available at /api-impexp/transac_fuels:

Sites are available at /api-impexp/rcm/sites:

Inventories are available at /api-impexp/inventories:

(Optional) Enter your server's URL and Impexp API key to update the examples below.


(found at https://demo-w150-gir.klervi.net/settings/advanced/impexp)

Authentication

Accessing web services requires authentication. An HTTP header "X-Klervi-API-Key: <apikey>" must be added to the request, where <apikey> is the value of the Impexp API key field in the Advanced / Impexp tab of application settings. If this header is missing or invalid, an authentication error is returned (401).

Authorization

Since the 1.0.41 version, the impexp API web services are disabled by default when installing a new application. To enable them, you have to define the permissions of the API key in the Authorization field in the advanced window of the Impexp API key parameter in the Advanced / Impexp tab of the application settings.

This field allows three values:

  • Read/Write: the impexp API web services can view and edit records (GET, PUT, POST and DELETE methods)
  • Read-only: the impexp API web services can only view records, but edition is forbidden (only GET method)
  • Disabled: the impexp API web services are all disabled

If a web service is not authorized, a forbidden error is returned (403).

Identifiers

See ID.

References

Some fields in the data model are references to other entities, such as:

  • department, model, and product in vehicles
  • department in drivers

The behaviour when reading and writing reference fields is different than when dealing other fields. The properties within these fields (such as the name of a department) are shared between other records with a matching id property in the reference field. Changing any properties within the reference field of a record will also change the properties in the reference field of all other records that contain a matching id property.

When writing data (via POST or PUT request), if no id is provided, then an attempt is made to resolve the id value to an existing reference field value with the same name value. If no matching value is found, then a new id is assigned.

For instance, a PUT request on a vehicle containing "model":{"name":"m1"} will:

  • Search if there is a model whose name is "m1".
  • If the "m1" model is found, assign it to the vehicle.
  • If the "m1" model is not found, create a new "m1" model and assign it to the vehicle.

Resolving an entity uses the id field when it is set in a request, and the name field otherwise. If both id and name are set, the search is performed by id, and the name field of the referenced entity is modified if needed, to match the request content.

Constraints on references

In vehicles, tanks are identified by their product (vtanks[].product field). As products are part of the protected settings, it is not possible to create a new product through a vehicle creation or update, but only to reference an existing product, by ID or by name. A vehicle can't have two tanks referencing the same product.

Idempotency

When a request is sent to the server and a network problem occurs, the caller may not get a response. In such a case, the caller will have to re-emit the request.

However, the caller may not always be able to know if the network error occurred when transmitting the request to the server, or when receiving the response. In the first case, there is nothing special to watch out for: the caller simply re-emits the request, and the server processes it. The second case is more complex as it requires that all requests are idempotent to avoid undesired duplicates. In other words, sending a request once or several times must produce the same result server-side.

  • GET requests are idempotent by nature, as they do not change the server state.
  • PUT requests are idempotent as well: if the server receives a PUT request for the second time, all fields will already have the correct value, and the server state will remain unchanged.
  • DELETE requests are made idempotent by considering that deleting an unknown ID is always successful. This way, if the caller doesn't receive the response to a first DELETE request and re-emits it, it will still receive a "200 OK" response, indicating that the object is indeed no longer in the database.
  • POST requests are the most problematic: as they do not contain an ID (except when using custom Public IDs: see below), the server has no way to know if a POST request to create a new object has already been processed or not. This can be solved by the X-Klervi-Idempotency-Key HTTP header, which does the following:
    • The value defined by this header is called an "idempotency key"
    • When a POST request contains an idempotency key, the key is associated to the object created, for 24 hours after the first request has been processed.
    • If an idempotency key has already been processed, the rest of the POST request is ignored (as the creation already occurred), and the associated object is simply returned. In such a case, the request is equivalent to a GET request with the object identifier.

For POST requests without an ID, it is recommended to use the X-Klervi-Idempotency-Key header, with a random or content-related idempotency key, which is re-transmitted as is when there are retries. Without this header, a network error at the wrong time may cause duplicates to be created when there are retries.

Idempotency and custom Public IDs

When using custom Public IDs (see the Identifiers section), POST requests can contain an ID, and are then naturally idempotent. The X-Klervi-Idempotency-Key HTTP header remains operative if it is set, but it is no longer required.

For convenience, when custom Public IDs are enabled, a PUT request on an unknown ID is interpreted as a creation operation, and is naturally idempotent as well.

HTTP Status codes

The API uses HTTP status codes to indicate the success or failure of an operation:

  • a 2XX status code indicates a successful operation.
  • a 4XX status code indicates an error due to request content. Retrying the same request will cause the same error.
  • a 5XX status code indicates an internal or temporary error. Retrying the same request may succeed. When an error occurs, a message in the response body contains a detailed description of the problem.

In the future, new fields may be added to the JSON body of server responses (both success and failure). The caller must be prepared for this, by not assuming anything about field names that are not presently documented in this API. The HTTP status code alone should be used to determine whether an operation is successful – not the fact that the response body is empty (as this behaviour may change in the future). Certain API requests do currently return empty objects upon successful completion.

Legend

The following annotations may be referenced throughout this documentation:

  1. The first_name field of Drivers is only available when the Name + First name feature is enabled
  2. The units for some fields depend on the application's settings and geographical area
  3. Only set when the ?ctrl_badge=true parameter is set
  4. Only available for access-only licenses when the Zones feature is enabled

Resources

/vehicles

/vehicles
GET /vehicles

Read the list of vehicles

curl -X GET https://demo-w150-gir.klervi.net/api-impexp/vehicles \
  -H "X-Klervi-API-Key: your-api-key"

Request
Query Parameters
ctrl_badge
boolean, optional

If set to true, sets the ctrl_badge field in response

limit
integer , default: 500, optional

Maximum number of objects to return in the response

offset
integer , default: 0, optional

Position of the first object to return in the results

Response

OK – operation completed successfully

Body
Properties (object)
offset
Offset (number), required

Number of objects ignored before the first object returned. This value always matches the offset value set in the request.

more
More (boolean), required

Boolean indicating if the limit of the result array is reached. When more is true, there remains objects to read, and a new GET request has to be performed, by incrementing the offset to get the rest of the data. When more is false, the end of the list has been reached and all objects have been read.

result
Array of Vehicle, required

Array of matching records, starting at offset and containing at most limit objects

Vehicle[]
id
ID (string), optional

Vehicle Public ID

name
string, required

Vehicle name/label (mandatory)

badge
string, optional

Badge used for identification

ctrl_badge
string, optional

Badge sent to controller (read-only) 3

code
string, optional

Code used for identification

pin_code
string, optional

PIN code

model
Model, optional

Vehicle model

model
id
ID (string), optional

Model Public ID

name
string, optional

Model name

department
Department, optional

Department

department
id
ID (string), optional

Department Public ID

name
string, optional

Department name

kmeter
integer, optional

Odometer (in km or miles)

hmeter
number, optional

Hour meter (in hours)

notes
string, optional

Additional notes for this vehicle

vtanks
Array of Product, optional

List of products used by this vehicle

Product[]
product
object, required
product
id
ID (string), optional

Product Public ID

name
string, optional

Product name (one of id or name is required)

Examples
  • Example
    {
      "result": [
        { "name": "AA-001-AA", ... },
        { "name": "AA-002-AA", ... },
        { "name": "AA-003-AA", ... },
        ...
        { "name": "AA-010-AA", ... }
      ],
      "offset": 0,
      "more": true
    }
    

Bad Request Request – content is invalid (for instance: bad JSON, mandatory name field not set, inconsistent data...)

Unauthorized – The X-Klervi-API-Key header is missing or incorrect

Forbidden – This web service is not authorized. Check the permissions defined in the Authorization field in the advanced window of the Impexp API key parameter in the Advanced / Impexp tab of the application settings

Not found – The record ID in parameter is unknown

Method Not Allowed – HTTP method is not supported on this resource

Conflict – The object identifier (id) is not unique

Internal error – Temporary error due to some server condition

/vehicles
POST /vehicles

Create a vehicle. Note that:

  • The request body must be a JSON object, matching the data model.
  • Fields indicated as mandatory in the data model (for instance, for vehicles, the name field) must be defined.
  • Other fields are optional and may be omitted, in which case the object is created with default values (for instance, if the vtanks field is omitted when creating a vehicle, it will be created with products defined as Authorized by default in the settings).
curl -X POST https://demo-w150-gir.klervi.net/api-impexp/vehicles \
  -H "X-Klervi-API-Key: your-api-key" \
  -H "Content-type: application/json" \
  -d '{"name": "AA-001-AA", "badge": "20000002"}'

Request
Query Parameters
ctrl_badge
boolean, optional

If set to true, sets the ctrl_badge field in response

Body
Properties (Vehicle)
id
ID (string), optional

Vehicle Public ID

name
string, required

Vehicle name/label (mandatory)

badge
string, optional

Badge used for identification

ctrl_badge
string, optional

Badge sent to controller (read-only) 3

code
string, optional

Code used for identification

pin_code
string, optional

PIN code

model
Model, optional

Vehicle model

model
id
ID (string), optional

Model Public ID

name
string, optional

Model name

department
Department, optional

Department

department
id
ID (string), optional

Department Public ID

name
string, optional

Department name

kmeter
integer, optional

Odometer (in km or miles)

hmeter
number, optional

Hour meter (in hours)

notes
string, optional

Additional notes for this vehicle

vtanks
Array of Product, optional

List of products used by this vehicle

Product[]
product
object, required
product
id
ID (string), optional

Product Public ID

name
string, optional

Product name (one of id or name is required)

Examples
  • Example
    {
      "name": "AA-001-AA",
      "badge": "20000001"
    }
    
Response

OK – operation completed successfully

Body
Properties (object)
result
Vehicle, required

A copy of the created vehicle

Vehicle
id
ID (string), optional

Vehicle Public ID

name
string, required

Vehicle name/label (mandatory)

badge
string, optional

Badge used for identification

ctrl_badge
string, optional

Badge sent to controller (read-only) 3

code
string, optional

Code used for identification

pin_code
string, optional

PIN code

model
Model, optional

Vehicle model

model
id
ID (string), optional

Model Public ID

name
string, optional

Model name

department
Department, optional

Department

department
id
ID (string), optional

Department Public ID

name
string, optional

Department name

kmeter
integer, optional

Odometer (in km or miles)

hmeter
number, optional

Hour meter (in hours)

notes
string, optional

Additional notes for this vehicle

vtanks
Array of Product, optional

List of products used by this vehicle

Product[]
product
object, required
product
id
ID (string), optional

Product Public ID

name
string, optional

Product name (one of id or name is required)

Examples
  • Example
    {
      "result": {
        "id": "9c9d372b-0c62-42a5-9a4d-f7be1b5af060",
        "name": "AA-001-AA",
        "badge": "20000001",
        "code": "",
        "pin_code": "",
        "model": null,
        "kmeter": 0,
        "hmeter": null,
        "notes": "",
        "department": null,
        "vtanks": [
          {
            "product": {
              "id": "226aad3b-762b-441d-98c1-6e5f1f24e7d5",
              "name": "DIESEL"
            }
          }
        ]
      }
    }
    

Bad Request Request – content is invalid (for instance: bad JSON, mandatory name field not set, inconsistent data...)

Unauthorized – The X-Klervi-API-Key header is missing or incorrect

Forbidden – This web service is not authorized. Check the permissions defined in the Authorization field in the advanced window of the Impexp API key parameter in the Advanced / Impexp tab of the application settings

Not found – The record ID in parameter is unknown

Method Not Allowed – HTTP method is not supported on this resource

Conflict – The object identifier (id) is not unique

Internal error – Temporary error due to some server condition

/vehicles/{id}
GET /vehicles/{id}

Read a vehicle

curl -X GET https://demo-w150-gir.klervi.net/api-impexp/vehicles/9c9d372b-0c62-42a5-9a4d-f7be1b5af060 \
  -H "X-Klervi-API-Key: your-api-key"

Request
Path Variables
id
ID (string), required

Vehicle Public ID

Query Parameters
ctrl_badge
boolean, optional

If set to true, sets the ctrl_badge field in response

Response

OK – operation completed successfully

Body
Properties (object)
result
Vehicle, required

The requested vehicle

Vehicle
id
ID (string), optional

Vehicle Public ID

name
string, required

Vehicle name/label (mandatory)

badge
string, optional

Badge used for identification

ctrl_badge
string, optional

Badge sent to controller (read-only) 3

code
string, optional

Code used for identification

pin_code
string, optional

PIN code

model
Model, optional

Vehicle model

model
id
ID (string), optional

Model Public ID

name
string, optional

Model name

department
Department, optional

Department

department
id
ID (string), optional

Department Public ID

name
string, optional

Department name

kmeter
integer, optional

Odometer (in km or miles)

hmeter
number, optional

Hour meter (in hours)

notes
string, optional

Additional notes for this vehicle

vtanks
Array of Product, optional

List of products used by this vehicle

Product[]
product
object, required
product
id
ID (string), optional

Product Public ID

name
string, optional

Product name (one of id or name is required)

Examples
  • Example
    {
      "result": {
        "id": "9c9d372b-0c62-42a5-9a4d-f7be1b5af060",
        "name": "AA-001-AA",
        "badge": "20000001",
        "code": "",
        "pin_code": "",
        "model": null,
        "kmeter": 0,
        "hmeter": null,
        "notes": "",
        "department": null,
        "vtanks": [
          {
            "product": {
              "id": "226aad3b-762b-441d-98c1-6e5f1f24e7d5",
              "name": "DIESEL"
            }
          }
        ]
      }
    }
    

Bad Request Request – content is invalid (for instance: bad JSON, mandatory name field not set, inconsistent data...)

Unauthorized – The X-Klervi-API-Key header is missing or incorrect

Forbidden – This web service is not authorized. Check the permissions defined in the Authorization field in the advanced window of the Impexp API key parameter in the Advanced / Impexp tab of the application settings

Not found – The record ID in parameter is unknown

Method Not Allowed – HTTP method is not supported on this resource

Conflict – The object identifier (id) is not unique

Internal error – Temporary error due to some server condition

/vehicles/{id}
PUT /vehicles/{id}

Update an existing vehicle. Note:

  • The request body must be a JSON object, matching the data model.
  • Omitted fields are left unchanged.
curl -X PUT https://demo-w150-gir.klervi.net/api-impexp/vehicles/9c9d372b-0c62-42a5-9a4d-f7be1b5af060 \
  -H "X-Klervi-API-Key: your-api-key" \
  -H "Content-type: application/json" \
  -d '{"badge": "20000002"}'

Request
Path Variables
id
ID (string), required

Vehicle Public ID

Query Parameters
ctrl_badge
boolean, optional

If set to true, sets the ctrl_badge field in response

Body
Properties (Vehicle)
id
ID (string), optional

Vehicle Public ID

name
string, required

Vehicle name/label (mandatory)

badge
string, optional

Badge used for identification

ctrl_badge
string, optional

Badge sent to controller (read-only) 3

code
string, optional

Code used for identification

pin_code
string, optional

PIN code

model
Model, optional

Vehicle model

model
id
ID (string), optional

Model Public ID

name
string, optional

Model name

department
Department, optional

Department

department
id
ID (string), optional

Department Public ID

name
string, optional

Department name

kmeter
integer, optional

Odometer (in km or miles)

hmeter
number, optional

Hour meter (in hours)

notes
string, optional

Additional notes for this vehicle

vtanks
Array of Product, optional

List of products used by this vehicle

Product[]
product
object, required
product
id
ID (string), optional

Product Public ID

name
string, optional

Product name (one of id or name is required)

Examples
  • Example
    {
      "badge": "20000002"
    }
    
Response

OK – operation completed successfully

Body
Properties (object)
result
Vehicle, required

The modified vehicle

Vehicle
id
ID (string), optional

Vehicle Public ID

name
string, required

Vehicle name/label (mandatory)

badge
string, optional

Badge used for identification

ctrl_badge
string, optional

Badge sent to controller (read-only) 3

code
string, optional

Code used for identification

pin_code
string, optional

PIN code

model
Model, optional

Vehicle model

model
id
ID (string), optional

Model Public ID

name
string, optional

Model name

department
Department, optional

Department

department
id
ID (string), optional

Department Public ID

name
string, optional

Department name

kmeter
integer, optional

Odometer (in km or miles)

hmeter
number, optional

Hour meter (in hours)

notes
string, optional

Additional notes for this vehicle

vtanks
Array of Product, optional

List of products used by this vehicle

Product[]
product
object, required
product
id
ID (string), optional

Product Public ID

name
string, optional

Product name (one of id or name is required)

Examples
  • Example
    {
      "result": {
        "id": "9c9d372b-0c62-42a5-9a4d-f7be1b5af060",
        "name": "AA-001-AA",
        "badge": "20000002",
        ...
      }
    }
    

Bad Request Request – content is invalid (for instance: bad JSON, mandatory name field not set, inconsistent data...)

Unauthorized – The X-Klervi-API-Key header is missing or incorrect

Forbidden – This web service is not authorized. Check the permissions defined in the Authorization field in the advanced window of the Impexp API key parameter in the Advanced / Impexp tab of the application settings

Not found – The record ID in parameter is unknown

Method Not Allowed – HTTP method is not supported on this resource

Conflict – The object identifier (id) is not unique

Internal error – Temporary error due to some server condition

/vehicles/{id}
DELETE /vehicles/{id}

Delete a vehicle. Note that performing a DELETE on a non-existing ID is considered as successful, and returns "200 OK". See the Idempotency section for an explanation of this behaviour.

curl -X DELETE https://demo-w150-gir.klervi.net/api-impexp/vehicles/9c9d372b-0c62-42a5-9a4d-f7be1b5af060 \
  -H "X-Klervi-API-Key: your-api-key"

Request
Path Variables
id
ID (string), required

Vehicle Public ID

Response

OK – operation completed successfully

Body
Examples
  • Example
    {}
    

Bad Request Request – content is invalid (for instance: bad JSON, mandatory name field not set, inconsistent data...)

Unauthorized – The X-Klervi-API-Key header is missing or incorrect

Forbidden – This web service is not authorized. Check the permissions defined in the Authorization field in the advanced window of the Impexp API key parameter in the Advanced / Impexp tab of the application settings

Not found – The record ID in parameter is unknown

Method Not Allowed – HTTP method is not supported on this resource

Conflict – The object identifier (id) is not unique

Internal error – Temporary error due to some server condition

/drivers

/drivers
GET /drivers

Read the list of drivers

curl -X GET https://demo-w150-gir.klervi.net/api-impexp/drivers \
  -H "X-Klervi-API-Key: your-api-key"

Request
Query Parameters
ctrl_badge
boolean, optional

If set to true, sets the ctrl_badge field in response

limit
integer , default: 500, optional

Maximum number of objects to return in the response

offset
integer , default: 0, optional

Position of the first object to return in the results

Response

OK – operation completed successfully

Body
Properties (object)
offset
Offset (number), required

Number of objects ignored before the first object returned. This value always matches the offset value set in the request.

more
More (boolean), required

Boolean indicating if the limit of the result array is reached. When more is true, there remains objects to read, and a new GET request has to be performed, by incrementing the offset to get the rest of the data. When more is false, the end of the list has been reached and all objects have been read.

result
Array of Driver, required

Array of matching records, starting at offset and containing at most limit object

Driver[]
id
ID (string), optional

Driver Public ID

name
string, required

Driver name/label (mandatory)

first_name
string, optional

Driver first name 1

badge
string, optional

Badge used for identification

ctrl_badge
string, optional

Badge sent to controller (read-only) 3

code
string, optional

Code used for identification

pin_code
string, optional

PIN code

department
Department, optional

Department

department
id
ID (string), optional

Department Public ID

name
string, optional

Department name

activity_prompt
boolean, optional

Activity code prompt

nce_prompt
boolean, optional

NCE code prompt

notes
string, optional

Additional notes for this driver

Examples
  • Example
    {
      "result": [
        { "name": "Nelson", ... },
        ...
        { "name": "Martin", ... }
      ],
      "offset": 0,
      "more": true
    }
    

Bad Request Request – content is invalid (for instance: bad JSON, mandatory name field not set, inconsistent data...)

Unauthorized – The X-Klervi-API-Key header is missing or incorrect

Forbidden – This web service is not authorized. Check the permissions defined in the Authorization field in the advanced window of the Impexp API key parameter in the Advanced / Impexp tab of the application settings

Not found – The record ID in parameter is unknown

Method Not Allowed – HTTP method is not supported on this resource

Conflict – The object identifier (id) is not unique

Internal error – Temporary error due to some server condition

/drivers
POST /drivers

Create a driver.

curl -X POST https://demo-w150-gir.klervi.net/api-impexp/drivers \
  -H "X-Klervi-API-Key: your-api-key" \
  -H "Content-type: application/json" \
  -d '{ "name": "Nelson", "code": "1234" }'

Request
Query Parameters
ctrl_badge
boolean, optional

If set to true, sets the ctrl_badge field in response

Body
Properties (Driver)
id
ID (string), optional

Driver Public ID

name
string, required

Driver name/label (mandatory)

first_name
string, optional

Driver first name 1

badge
string, optional

Badge used for identification

ctrl_badge
string, optional

Badge sent to controller (read-only) 3

code
string, optional

Code used for identification

pin_code
string, optional

PIN code

department
Department, optional

Department

department
id
ID (string), optional

Department Public ID

name
string, optional

Department name

activity_prompt
boolean, optional

Activity code prompt

nce_prompt
boolean, optional

NCE code prompt

notes
string, optional

Additional notes for this driver

Examples
  • Example
    {
      "name": "Nelson",
      "code": "1234"
    }
    
Response

OK – operation completed successfully

Body
Properties (object)
result
Driver, required

A copy of the created driver

Driver
id
ID (string), optional

Driver Public ID

name
string, required

Driver name/label (mandatory)

first_name
string, optional

Driver first name 1

badge
string, optional

Badge used for identification

ctrl_badge
string, optional

Badge sent to controller (read-only) 3

code
string, optional

Code used for identification

pin_code
string, optional

PIN code

department
Department, optional

Department

department
id
ID (string), optional

Department Public ID

name
string, optional

Department name

activity_prompt
boolean, optional

Activity code prompt

nce_prompt
boolean, optional

NCE code prompt

notes
string, optional

Additional notes for this driver

Examples
  • Example
    {
      "result": {
        "id": "28d6f2da-b10b-4102-b3da-db93351c98d4",
        "name": "Nelson",
        "first_name": "Andrew",
        "badge": "",
        "code": "1234",
        "pin_code": "",
        "nce_prompt": false,
        "activity_prompt": false,
        "notes": "",
        "department": null
      }
    }
    

Bad Request Request – content is invalid (for instance: bad JSON, mandatory name field not set, inconsistent data...)

Unauthorized – The X-Klervi-API-Key header is missing or incorrect

Forbidden – This web service is not authorized. Check the permissions defined in the Authorization field in the advanced window of the Impexp API key parameter in the Advanced / Impexp tab of the application settings

Not found – The record ID in parameter is unknown

Method Not Allowed – HTTP method is not supported on this resource

Conflict – The object identifier (id) is not unique

Internal error – Temporary error due to some server condition

/drivers/{id}
GET /drivers/{id}

Read a driver

curl -X GET https://demo-w150-gir.klervi.net/api-impexp/drivers/28d6f2da-b10b-4102-b3da-db93351c98d4 \
  -H "X-Klervi-API-Key: your-api-key"

Request
Path Variables
id
string, required

Driver Public ID

Query Parameters
ctrl_badge
boolean, optional

If set to true, sets the ctrl_badge field in response

Response

OK – operation completed successfully

Body
Properties (object)
result
Driver, required

The requested driver

Driver
id
ID (string), optional

Driver Public ID

name
string, required

Driver name/label (mandatory)

first_name
string, optional

Driver first name 1

badge
string, optional

Badge used for identification

ctrl_badge
string, optional

Badge sent to controller (read-only) 3

code
string, optional

Code used for identification

pin_code
string, optional

PIN code

department
Department, optional

Department

department
id
ID (string), optional

Department Public ID

name
string, optional

Department name

activity_prompt
boolean, optional

Activity code prompt

nce_prompt
boolean, optional

NCE code prompt

notes
string, optional

Additional notes for this driver

Examples
  • Example
    {
      "result": {
        "id": "28d6f2da-b10b-4102-b3da-db93351c98d4",
        "name": "Nelson",
        "first_name": "Andrew",
        "badge": "",
        "code": "1234",
        "pin_code": "",
        "nce_prompt": false,
        "activity_prompt": false,
        "notes": "",
        "department": null
      }
    }
    

Bad Request Request – content is invalid (for instance: bad JSON, mandatory name field not set, inconsistent data...)

Unauthorized – The X-Klervi-API-Key header is missing or incorrect

Forbidden – This web service is not authorized. Check the permissions defined in the Authorization field in the advanced window of the Impexp API key parameter in the Advanced / Impexp tab of the application settings

Not found – The record ID in parameter is unknown

Method Not Allowed – HTTP method is not supported on this resource

Conflict – The object identifier (id) is not unique

Internal error – Temporary error due to some server condition

/drivers/{id}
PUT /drivers/{id}

Update an existing driver. Note:

  • The request body must be a JSON object, matching the data model.
  • Omitted fields are left unchanged.
curl -X PUT https://demo-w150-gir.klervi.net/api-impexp/drivers/28d6f2da-b10b-4102-b3da-db93351c98d4 \
  -H "X-Klervi-API-Key: your-api-key" \
  -H "Content-type: application/json" \
  -d '{"department": { "name" : "D1" } }'

Request
Path Variables
id
string, required

Driver Public ID

Query Parameters
ctrl_badge
boolean, optional

If set to true, sets the ctrl_badge field in response

Body
Properties (Driver)
id
ID (string), optional

Driver Public ID

name
string, required

Driver name/label (mandatory)

first_name
string, optional

Driver first name 1

badge
string, optional

Badge used for identification

ctrl_badge
string, optional

Badge sent to controller (read-only) 3

code
string, optional

Code used for identification

pin_code
string, optional

PIN code

department
Department, optional

Department

department
id
ID (string), optional

Department Public ID

name
string, optional

Department name

activity_prompt
boolean, optional

Activity code prompt

nce_prompt
boolean, optional

NCE code prompt

notes
string, optional

Additional notes for this driver

Examples
  • Example
    {
      "department": { "name" : "D1" }
    }
    
Response

OK – operation completed successfully

Body
Properties (object)
result
Driver, required

The modified driver

Driver
id
ID (string), optional

Driver Public ID

name
string, required

Driver name/label (mandatory)

first_name
string, optional

Driver first name 1

badge
string, optional

Badge used for identification

ctrl_badge
string, optional

Badge sent to controller (read-only) 3

code
string, optional

Code used for identification

pin_code
string, optional

PIN code

department
Department, optional

Department

department
id
ID (string), optional

Department Public ID

name
string, optional

Department name

activity_prompt
boolean, optional

Activity code prompt

nce_prompt
boolean, optional

NCE code prompt

notes
string, optional

Additional notes for this driver

Examples
  • Example
    {
      "result": {
        "id": "28d6f2da-b10b-4102-b3da-db93351c98d4",
        "name": "Nelson",
        "code": "1234",
        "department": {
          "id": "702f6726-bd13-4916-adb9-9840064cd7bf",
          "name": "D1"
        },
        ...
      }
    }
    

Bad Request Request – content is invalid (for instance: bad JSON, mandatory name field not set, inconsistent data...)

Unauthorized – The X-Klervi-API-Key header is missing or incorrect

Forbidden – This web service is not authorized. Check the permissions defined in the Authorization field in the advanced window of the Impexp API key parameter in the Advanced / Impexp tab of the application settings

Not found – The record ID in parameter is unknown

Method Not Allowed – HTTP method is not supported on this resource

Conflict – The object identifier (id) is not unique

Internal error – Temporary error due to some server condition

/drivers/{id}
DELETE /drivers/{id}

Delete a driver. Note that performing a DELETE on a non-existing ID is considered as successful, and returns "200 OK". See the Idempotency section for an explanation of this behaviour.

curl -X DELETE https://demo-w150-gir.klervi.net/api-impexp/drivers/a3cffa32-f795-4a21-9131-1127f7c8efcf \
  -H "X-Klervi-API-Key: your-api-key"

Request
Path Variables
id
string, required

Driver Public ID

Response

OK – operation completed successfully

Body
Examples
  • Example
    {}
    

Bad Request Request – content is invalid (for instance: bad JSON, mandatory name field not set, inconsistent data...)

Unauthorized – The X-Klervi-API-Key header is missing or incorrect

Forbidden – This web service is not authorized. Check the permissions defined in the Authorization field in the advanced window of the Impexp API key parameter in the Advanced / Impexp tab of the application settings

Not found – The record ID in parameter is unknown

Method Not Allowed – HTTP method is not supported on this resource

Conflict – The object identifier (id) is not unique

Internal error – Temporary error due to some server condition

/transac_fuels

/transac_fuels
GET /transac_fuels

Retrieve the list of fuel transactions

curl -X GET https://demo-w150-gir.klervi.net/api-impexp/transac_fuels \
  -H "X-Klervi-API-Key: your-api-key"

curl -X GET "https://demo-w150-gir.klervi.net/api-impexp/transac_fuels?last_id=29002d00-6d00-7800-005d-00cc0014020c" \
  -H "X-Klervi-API-Key: your-api-key"

If more in the response body is true, it means that there are more records to retrieve and that you'll need to issue a follow-up request using the last_id parameter (cf. the example above).

Usage notes:

  • We call "line" each element of the result[] array returned by this web service.
  • Exported fuel transactions are not always ordered by date (e.g. when there are modifications, or when some transactions were not immediately received by the server after being made). No assumption should be made about the ordering of the exported transactions. Using the last_id parameter is the only method to guarantee that all transactions are exported.
  • Third-party softwares using the GET /transac_fuels web service are required to store the last id value (export line UUID) in their database each time a response is received. This value must be used in the following request last_id parameter in order to get the following transactions records. It is recommended to store the last id value received even if the more field in the response body is true, in order to avoid getting the same results twice if the third-party software is stopped in between queries.
  • There isn't at one-to-one relation between the number of lines exposed by this API, and the list of fuel transactions that can be viewed in the application menu. This is because this API is designed as a stream, to be easily usable by a third-party system to take into account transactions creations, but also modifications. So a transaction that is created, then modified will appear as a single object in the application, but generate mutiple "lines" in this API. This is also the reason for the two "ID" fields: id is unique per line (it changes on each modification), while transac_id is unique per transaction object (it stays the same on each modification). This behaviour can be customized: see the change parameter below for more information.
  • The lines exposed by this API when the change parameter is set to diff can be vizualized in the application web interface by selecting a record in the Fuel transactions page, then by opening the Info window and displaying the Ledger tab. The id column in that tab match the id field in this web service response, which is the line UUID and also the value to pass to the last_id parameter.
  • New columns or fields may be added to the exported data at a later date.
Request
Query Parameters
last_id
ID (string), optional

The line UUID of the last transaction retrieved during the last export operation. The response will then contain the following elements. When not provided, the response will start from the first transactions stored in the database.

change
string, one of [noneupdatedifffulldiff] , default: diff, optional

Defines how fuel transactions modifications are exported. Transactions creations are always exported independently of the selected value.

  • none: only transactions creations are exported.
  • update: a transaction modification is exported as a new element which updates a previous transaction.
  • diff: a transaction modification is exported as two elements: the first one cancels the previous transaction, and the second one creates a new transaction with updated values.
  • fulldiff: a transaction modification is exported as at least two elements, and sometimes more, in case of cascading changes on the following fields: kdelta, kcons, hdelta, hcons.
Response

OK – operation completed successfully

Body
Properties (object)
more
boolean, required

is a boolean set to true if the limit of results in result was reached and there is some data left

result
Array of FuelTransaction, required

Array containing the exported data. Please note that if the size of this array hits a predetermined limit, we'll stop sending you data and you'll have to call the web service once again with the right parameters (using the last_id parameter) to get the rest of the data.

FuelTransaction[]
id
ID (string), optional

Export line UUID (unique)

transac_id
ID (string), optional

Transaction Public ID

_deleted
boolean, optional

true if the transaction was deleted

type
string, optional

"int" (internal) or "ext" (external)

date
datetime, optional

Date + time in UTC

vehicle.id
ID (string), optional

Vehicle Public ID

vehicle.name
string, optional

Name or registration

vehicle.badge
string, optional

Vehicle badge

vehicle.code
string, optional

Vehicle code

driver.id
ID (string), optional

Driver Public ID

driver.name
string, optional

Driver name

driver.fstname
string, optional

Driver first name

driver.badge
string, optional

Driver badge

driver.code
string, optional

Driver code

department.id
ID (string), optional

Department Public ID

department.name
string, optional

Department name

product.id
ID (string), optional

Product Public ID

product.name
string, optional

Product name

volume
number, optional

Distributed volume (L or gal) 2

unit_price
number, optional

Unit price 2

kmeter
integer, optional

Odometer (km or Miles) 2

hmeter
number, optional

Meter in hours

activity.id
ID (string), optional

Activity Public ID

activity.name
string, optional

Activity name

nce_code
string, optional

NCE code

site.id
ID (string), optional

Site Public ID

site.name
string, optional

Site name

pump
ID (string), optional

Pump number

manual
boolean, optional

true if created manually

mtr_forced
boolean, optional

true if the meter was forced

vol_max
boolean, optional

true if the maximum capacity was reached

new_kmeter
boolean, optional

true if the odometer was initialized

new_hmeter
boolean, optional

true if the hour meter was initialized

notes
string, optional

Transaction notes

local_date
string, optional

Local date in YYYY-MM-DD format

local_time
string, optional

Local time in HH:MM:SS format

line_id
integer, optional

Unique ID for legacy systems who can't handle UUIDs

kdelta
integer, optional

Covered distance (km or Miles) 2

kcons
number, optional

Fuel consumption (km/L or MPG) 2

hdelta
number, optional

Covered time (h)

hcons
number, optional

Fuel consumption (L/h)

tank.id
ID (string), optional

Tank Public ID

tank.name
number, optional

Tank name

Examples
  • Example
    {
      "result": [
        {
          "id": "35004000-eb00-5800-005e-008c00780177",
          "transac_id": "c58709c9-d4f2-49e5-ac1e-da9d35652722",
          "_deleted": false,
          "type": "int",
          "date": "2020-03-04T13:55:51Z",
          "local_date": "2020-03-04",
          "local_time": "14:55:51",
          "line_id": 1,
          "vehicle": {
            "id": "9c9d372b-0c62-42a5-9a4d-f7be1b5af060",
            "name": "AA-001-AA",
            "badge": "20000001",
            "code": ""
          },
          "driver": {
            "id": "28d6f2da-b10b-4102-b3da-db93351c98d4",
            "fstname": "Andrew",
            "name": "Nelson",
            "badge": "",
            "code": "1234"
          },
          "department": null,
          "product": {
            "id": "226aad3b-762b-441d-98c1-6e5f1f24e7d5",
            "name": "DIESEL"
          },
          "volume": 43.57,
          "unit_price": 0,
          "kmeter": null,
          "hmeter": null,
          "activity": null,
          "nce_code": "",
          "site": {
            "id": "0a98c0bf-a89f-45a8-9a67-23e5f6c1751a",
            "name": "Station"
          },
          "pump": "1",
          "manual": true,
          "mtr_forced": false,
          "vol_max": false,
          "new_kmeter": false,
          "new_hmeter": false,
          "kdelta": null,
          "kcons": null,
          "hdelta": null,
          "hcons": null
        },
        ...
      ],
      "more": false
    }
    

Bad Request Request – content is invalid (for instance: bad JSON, mandatory name field not set, inconsistent data...)

Unauthorized – The X-Klervi-API-Key header is missing or incorrect

Forbidden – This web service is not authorized. Check the permissions defined in the Authorization field in the advanced window of the Impexp API key parameter in the Advanced / Impexp tab of the application settings

Not found – The record ID in parameter is unknown

Method Not Allowed – HTTP method is not supported on this resource

Conflict – The object identifier (id) is not unique

Internal error – Temporary error due to some server condition

/rcm

Remote Control and Monitoring of sites and controllers. The web services below can be used to monitor and trigger actions for tanks, pumps and accesses.

/rcm/sites
GET /rcm/sites

Read the list of sites. Returns the monitoring data of the controllers, tanks, pumps and accesses in each site.

curl -X GET https://demo-w150-gir.klervi.net/api-impexp/rcm/sites \
  -H "X-Klervi-API-Key: your-api-key"

Request
Query Parameters
limit
integer , default: 500, optional

Maximum number of objects to return in the response

offset
integer , default: 0, optional

Position of the first object to return in the results

Response

OK – operation completed successfully

Body
Properties (object)
offset
Offset (number), required

Number of objects ignored before the first object returned. This value always matches the offset value set in the request.

more
More (boolean), required

Boolean indicating if the limit of the result array is reached. When more is true, there remains objects to read, and a new GET request has to be performed, by incrementing the offset to get the rest of the data. When more is false, the end of the list has been reached and all objects have been read.

result
Array of RcmSite, required

Array of matching records, starting at offset and containing at most limit objects

RcmSite[]
id
ID (string), optional

site Public ID

name
string, optional

Site name

gps
string, optional

Site GPS coordinates, with the format: "latitude,longitude". Example: "37.819193,-122.478537"

controllers
Array of RcmController, optional

List of controllers

RcmController[]
sn
string, optional

Controller Serial Number (S/N)

online
boolean, optional

Whether the controller is online (true) or offline (false)

date
datetime, optional

Last time the system communicated with this controller

tanks
Array of RcmTank, optional

List of tanks

RcmTank[]
id
ID (string), optional

Tank Public ID

name
string, optional

Tank name

product.id
ID (string), optional

Product Public ID

product.name
string, optional

Product name

capacity
number, optional

Tank capacity (L or gal) 2

volume
number, optional

Gauged volume (L or gal) 2

volume_date
datetime, optional

Date and time when gauge was last read

pumps
Array of RcmPump, optional

List of pumps

RcmPump[]
id
ID (string), optional

Pump Public ID

name
string, optional

Pump name

num
string, optional

Pump number

product.id
ID (string), optional

Product Public ID

product.name
string, optional

Product name

tank.id
ID (string), optional

Tank Public ID

tank.name
string, optional

Tank name

blocked
boolean, optional

Whether the pump is currently blocked

blocked_reason
string, one of [supervisionzero_volumeserrortank_block], optional

When blocked is true, detail on the blocking reason:

  • supervision: blocked from supervision menu or API.
  • zero_volumes: blocked because of multiple consecutive null volumes.
  • error: blocked because of some hardware error.
  • tank_block: blocked because the tank stock went below the blocking threshold
manual
boolean, optional

Whether the pump is currently in manual mode

pumping
boolean, optional

Whether pumping is current delivering fuel, either because a transaction is in progress, or because manual mode is enabled (as reported by the manual field). See here for the detail of possible blocked/manual/pumping combinations.

transaction.date
datetime, optional

Date + time when the transaction on this pump started

transaction.vehicle.id
ID (string), optional

Vehicle Public ID

transaction.vehicle.name
string, optional

Vehicle name or registration

transaction.driver.id
ID (string), optional

Driver Public ID

transaction.driver.name
string, optional

Driver name

transaction.activity.id
ID (string), optional

Activity Public ID

transaction.activity.name
string, optional

Activity name

transaction.nce_code
string, optional

NCE code

transaction.kmeter
integer, optional

Odometer (km or Miles) 2

transaction.hmeter
number, optional

Meter in hours

accesses
Array of RcmAccess, optional

List of accesses

RcmAccess[]
id
ID (string), optional

Access Public ID

name
string, optional

Access name

stay_open
boolean, optional

Whether the access is currently in "stay open" mode 4

Examples
  • Example
    {
      "result": [
        { "name": "Site 1", ... },
        { "name": "Site 2", ... },
        { "name": "Site 3", ... },
        ...
        { "name": "Site 10", ... }
      ],
      "offset": 0,
      "more": true
    }
    

Bad Request Request – content is invalid (for instance: bad JSON, mandatory name field not set, inconsistent data...)

Unauthorized – The X-Klervi-API-Key header is missing or incorrect

Forbidden – This web service is not authorized. Check the permissions defined in the Authorization field in the advanced window of the Impexp API key parameter in the Advanced / Impexp tab of the application settings

Not found – The record ID in parameter is unknown

Method Not Allowed – HTTP method is not supported on this resource

Conflict – The object identifier (id) is not unique

Internal error – Temporary error due to some server condition

/rcm/sites/{id}
GET /rcm/sites/{id}

Read a site. Returns the status of tanks, pumps and accesses.

curl -X GET https://demo-w150-gir.klervi.net/api-impexp/rcm/sites/bfb3505b-9426-4c21-98e0-2803802d442e \
  -H "X-Klervi-API-Key: your-api-key"

Request
Path Variables
id
ID (string), required

Site Public ID

Response

OK – operation completed successfully

Body
Properties (object)
result
RcmSite, required

The requested site

RcmSite
id
ID (string), optional

site Public ID

name
string, optional

Site name

gps
string, optional

Site GPS coordinates, with the format: "latitude,longitude". Example: "37.819193,-122.478537"

controllers
Array of RcmController, optional

List of controllers

RcmController[]
sn
string, optional

Controller Serial Number (S/N)

online
boolean, optional

Whether the controller is online (true) or offline (false)

date
datetime, optional

Last time the system communicated with this controller

tanks
Array of RcmTank, optional

List of tanks

RcmTank[]
id
ID (string), optional

Tank Public ID

name
string, optional

Tank name

product.id
ID (string), optional

Product Public ID

product.name
string, optional

Product name

capacity
number, optional

Tank capacity (L or gal) 2

volume
number, optional

Gauged volume (L or gal) 2

volume_date
datetime, optional

Date and time when gauge was last read

pumps
Array of RcmPump, optional

List of pumps

RcmPump[]
id
ID (string), optional

Pump Public ID

name
string, optional

Pump name

num
string, optional

Pump number

product.id
ID (string), optional

Product Public ID

product.name
string, optional

Product name

tank.id
ID (string), optional

Tank Public ID

tank.name
string, optional

Tank name

blocked
boolean, optional

Whether the pump is currently blocked

blocked_reason
string, one of [supervisionzero_volumeserrortank_block], optional

When blocked is true, detail on the blocking reason:

  • supervision: blocked from supervision menu or API.
  • zero_volumes: blocked because of multiple consecutive null volumes.
  • error: blocked because of some hardware error.
  • tank_block: blocked because the tank stock went below the blocking threshold
manual
boolean, optional

Whether the pump is currently in manual mode

pumping
boolean, optional

Whether pumping is current delivering fuel, either because a transaction is in progress, or because manual mode is enabled (as reported by the manual field). See here for the detail of possible blocked/manual/pumping combinations.

transaction.date
datetime, optional

Date + time when the transaction on this pump started

transaction.vehicle.id
ID (string), optional

Vehicle Public ID

transaction.vehicle.name
string, optional

Vehicle name or registration

transaction.driver.id
ID (string), optional

Driver Public ID

transaction.driver.name
string, optional

Driver name

transaction.activity.id
ID (string), optional

Activity Public ID

transaction.activity.name
string, optional

Activity name

transaction.nce_code
string, optional

NCE code

transaction.kmeter
integer, optional

Odometer (km or Miles) 2

transaction.hmeter
number, optional

Meter in hours

accesses
Array of RcmAccess, optional

List of accesses

RcmAccess[]
id
ID (string), optional

Access Public ID

name
string, optional

Access name

stay_open
boolean, optional

Whether the access is currently in "stay open" mode 4

Examples
  • Example
    {
      "result": {
        "id": "bfb3505b-9426-4c21-98e0-2803802d442e",
        "name": "Station",
        "controllers": [ ... ],
        "tanks": [ ... ],
        "pumps": [ ... ]
      }
    }
    

Bad Request Request – content is invalid (for instance: bad JSON, mandatory name field not set, inconsistent data...)

Unauthorized – The X-Klervi-API-Key header is missing or incorrect

Forbidden – This web service is not authorized. Check the permissions defined in the Authorization field in the advanced window of the Impexp API key parameter in the Advanced / Impexp tab of the application settings

Not found – The record ID in parameter is unknown

Method Not Allowed – HTTP method is not supported on this resource

Conflict – The object identifier (id) is not unique

Internal error – Temporary error due to some server condition

/rcm/block_pump
POST /rcm/block_pump

Triggers a "Block pump" action. When successful, this action prevents any user from starting transactions with this pump until the pump is unblocked. It requires the controller on which the pump is configured to be online, otherwise it will output an 500 status code. When this request fails with the 500 status code, the reported pump status can be out of sync, and it's preferable to retry the request until it succeeds.

curl -X POST https://demo-w150-gir.klervi.net/api-impexp/rcm/block_pump \
  -H "X-Klervi-API-Key: your-api-key" \
  -H "Content-type: application/json" \
  -d '{ "pump": "04fc9bf7-2bea-438d-98ca-6bf5e050016c" }'

Request
Body
Properties (RcmBlockPump)
pump
ID (string), optional

Public ID of the pump to block

Examples
  • Example
    {
      "pump": "04fc9bf7-2bea-438d-98ca-6bf5e050016c"
    }
    
Response

OK – operation completed successfully

Bad Request Request – content is invalid (for instance: bad JSON, mandatory name field not set, inconsistent data...)

Unauthorized – The X-Klervi-API-Key header is missing or incorrect

Forbidden – This web service is not authorized. Check the permissions defined in the Authorization field in the advanced window of the Impexp API key parameter in the Advanced / Impexp tab of the application settings

Not found – The record ID in parameter is unknown

Method Not Allowed – HTTP method is not supported on this resource

Conflict – The object identifier (id) is not unique

Internal error – Temporary error due to some server condition

/rcm/unblock_pump
POST /rcm/unblock_pump

Triggers a "Unblock pump" action. When successful, this action allows users to start transactions on a pump that was previously blocked. It requires the controller on which the pump is configured to be online, otherwise it will output an 500 status code. When this request fails with the 500 status code, the reported pump status can be out of sync, and it's preferable to retry the request until it succeeds.

curl -X POST https://demo-w150-gir.klervi.net/api-impexp/rcm/unblock_pump \
  -H "X-Klervi-API-Key: your-api-key" \
  -H "Content-type: application/json" \
  -d '{ "pump": "04fc9bf7-2bea-438d-98ca-6bf5e050016c" }'

Request
Body
Properties (RcmUnblockPump)
pump
ID (string), optional

Public ID of the pump to unblock

Examples
  • Example
    {
      "pump": "04fc9bf7-2bea-438d-98ca-6bf5e050016c"
    }
    
Response

OK – operation completed successfully

Bad Request Request – content is invalid (for instance: bad JSON, mandatory name field not set, inconsistent data...)

Unauthorized – The X-Klervi-API-Key header is missing or incorrect

Forbidden – This web service is not authorized. Check the permissions defined in the Authorization field in the advanced window of the Impexp API key parameter in the Advanced / Impexp tab of the application settings

Not found – The record ID in parameter is unknown

Method Not Allowed – HTTP method is not supported on this resource

Conflict – The object identifier (id) is not unique

Internal error – Temporary error due to some server condition

/rcm/start_pump
POST /rcm/start_pump

Triggers a "Remote transaction" action. Allows to start a new transaction using the properties defined in the request. It requires the pump to be available and the controller which the pump is configured to be online, otherwise it will output an 500 status code.

curl -X POST https://demo-w150-gir.klervi.net/api-impexp/rcm/start_pump \
  -H "X-Klervi-API-Key: your-api-key" \
  -H "Content-type: application/json" \
  -d '{ "pump": "04fc9bf7-2bea-438d-98ca-6bf5e050016c", \
        "vehicle": "9c9d372b-0c62-42a5-9a4d-f7be1b5af060" }'

Request
Body
Properties (RcmStartPump)
pump
ID (string), optional

Public ID of the pump

vehicle
ID (string), optional

Public ID of the vehicle

driver
ID (string), optional

Public ID of the driver

kmeter
integer, optional

Odometer (km or Miles) 2

hmeter
number, optional

Meter in hours

activity
ID (string), optional

Public ID of the activity

nce_code
string, optional

NCE code

Examples
  • Example
    {
      "pump": "04fc9bf7-2bea-438d-98ca-6bf5e050016c",
      "vehicle": "9c9d372b-0c62-42a5-9a4d-f7be1b5af060"
    }
    
Response

OK – operation completed successfully

Bad Request Request – content is invalid (for instance: bad JSON, mandatory name field not set, inconsistent data...)

Unauthorized – The X-Klervi-API-Key header is missing or incorrect

Forbidden – This web service is not authorized. Check the permissions defined in the Authorization field in the advanced window of the Impexp API key parameter in the Advanced / Impexp tab of the application settings

Not found – The record ID in parameter is unknown

Method Not Allowed – HTTP method is not supported on this resource

Conflict – The object identifier (id) is not unique

Internal error – Temporary error due to some server condition

/rcm/force_refresh
POST /rcm/force_refresh

This action triggers a data refresh, especially on gauges, which updates the latest volume and volume_date values in the tanks of the selected site. This action may store a new inventory record, and it may also refresh some other monitoring data. This action doesn't need the controllers to be online: if some of them are offline, the data will be refreshed when they come back online.

curl -X POST https://demo-w150-gir.klervi.net/api-impexp/rcm/force_refresh \
  -H "X-Klervi-API-Key: your-api-key" \
  -H "Content-type: application/json" \
  -d '{ "site" : "bfb3505b-9426-4c21-98e0-2803802d442e" }'

Request
Body
Properties (RcmForceRefresh)
site
ID (string), optional

Public ID of the site to gauge

Examples
  • Example
    {
      "site": "bfb3505b-9426-4c21-98e0-2803802d442e"
    }
    
Response

OK – operation completed successfully

Bad Request Request – content is invalid (for instance: bad JSON, mandatory name field not set, inconsistent data...)

Unauthorized – The X-Klervi-API-Key header is missing or incorrect

Forbidden – This web service is not authorized. Check the permissions defined in the Authorization field in the advanced window of the Impexp API key parameter in the Advanced / Impexp tab of the application settings

Not found – The record ID in parameter is unknown

Method Not Allowed – HTTP method is not supported on this resource

Conflict – The object identifier (id) is not unique

Internal error – Temporary error due to some server condition

/inventories

/inventories
GET /inventories

Retrieve the list of inventories

curl -X GET https://demo-w150-gir.klervi.net/api-impexp/inventories \
  -H "X-Klervi-API-Key: your-api-key"

curl -X GET "https://demo-w150-gir.klervi.net/api-impexp/inventories?last_id=ee0c50d4-e4ac-45d6-8235-81ca158ccfa3" \
  -H "X-Klervi-API-Key: your-api-key"

If more in the response body is true, it means that there are more records to retrieve and that you'll need to issue a follow-up request using the last_id parameter (cf. the example above).

Usage notes:

  • Exported inventories are not always ordered by date (e.g. some inventories were not immediately received by the server after being made). No assumption should be made about the ordering of the exported inventories. Using the last_id parameter is the only method to guarantee that all inventories are exported.
  • New columns or fields may be added to the exported data at a later date.
Request
Query Parameters
last_id
ID (string), optional

The Public ID (id field) of the last inventory retrieved during the last export operation. The response will then contain the following elements.

type
string, one of [allscheduled] , default: all, optional

Filters which inventories to export

  • all: all inventories are exported.
  • scheduled: only scheduled inventories are exported. The scheduled inventories are the ones that are automatically done every day at midnight.
Response

OK – operation completed successfully

Body
Properties (object)
more
boolean, required

is a boolean set to true if the limit of results in result was reached and there is some data left

result
Array of Inventory, required

Array containing the exported data. Please note that if the size of this array hits a predetermined limit, we'll stop sending you data and you'll have to call the web service once again with the right parameters (using the last_id parameter) to get the rest of the data.

Inventory[]
id
ID (string), optional

inventory Public ID

date
datetime, optional

Date + time in UTC

site.id
ID (string), optional

Site Public ID

site.name
string, optional

Site name

tank.id
ID (string), optional

Tank Public ID

tank.name
string, optional

Tank name

volume
number, optional

Gauged volume (L or gal) 2

temperature
number, optional

Gauged temperature (°C)

Examples
  • Example
    {
      "result": [
        {
          "id": "22d8c15f-e4af-4a58-9178-eabafd6d1fb0",
          "date": "2018-06-14T07:40:05Z",
          "site": {
            "id": "0a98c0bf-a89f-45a8-9a67-23e5f6c1751a",
            "name": "Station"
          },
          "tank": {
            "id": "226aad3b-762b-441d-98c1-6e5f1f24e7d5",
            "name": "Station T1 DIESEL"
          },
          "volume": 20238,
          "temperature": 16.3
        },
        ...
      ],
      "more": false
    }
    

Bad Request Request – content is invalid (for instance: bad JSON, mandatory name field not set, inconsistent data...)

Unauthorized – The X-Klervi-API-Key header is missing or incorrect

Forbidden – This web service is not authorized. Check the permissions defined in the Authorization field in the advanced window of the Impexp API key parameter in the Advanced / Impexp tab of the application settings

Not found – The record ID in parameter is unknown

Method Not Allowed – HTTP method is not supported on this resource

Conflict – The object identifier (id) is not unique

Internal error – Temporary error due to some server condition

Type Reference

ID

Each object (vehicles, drivers, departments, products...) is uniquely identified by its id field. This field must be unique, to avoid ambiguities when referencing an object. In the application, it can be viewed in the Public ID field of the Info modal.

GIR W150 automatically generates a unique identifier for all objects, as a UUID. It is recommended to use this auto-generated ID in most cases, as the guarantee of uniqueness is then assured by GIR W150.

In some cases, however, it can be relevant to use external identifiers, typically coming from a third-party system. This is possible by enabling one of the following features in the Advanced / Features tab of the application settings:

  • Show vehicles impexp IDs: enables custom Public IDs for vehicles.
  • Show drivers impexp IDs: enables custom Public IDs for drivers.
  • Show settings impexp IDs: enables custom Public IDs for departments, models, products, sites or activities. Note that this is not an all-or-nothing switch: for instance, it is possible to use custom Public IDs for products, but not for departments, by leaving the Impexp ID field blank for the latter.

When custom Public IDs are enabled for a given object type, it makes the id value controllable by the caller:

  • In the application, an editable Impexp ID field is displayed in the object form, where a custom Public ID value can be entered manually.
  • A value must be defined in the id field when a new record is created with the API.
  • A value must be set in the id field to reference an existing object.

When custom Public IDs are enabled, the third-party system is fully responsible for setting the id field in the API, when creating new objects or referencing existing ones. If an object doesn't have a custom ID defined, GIR W150 falls back to the default auto-generated UUID. This situation must be considered as exceptional: for instance, it can happen just after the feature is enabled on a non-empty database, when custom values haven't been set yet. It is highly discouraged to mix auto-generated IDs and custom IDs usage for a given entity: if you decide to use custom Public IDs for vehicles, then all vehicles should have a custom ID defined.

Caution: while using custom Public IDs can sometimes simplify the development of an interface between GIR W150 and a third-party system, that system must then assume full responsibility for generating and maintaining unique IDs. We recommend enabling this feature only when the detailed technical implications are well understood.

Type Information

ID (string)

Offset

Number of objects ignored before the first object returned. This value always matches the offset value set in the request.

Type Information

Offset (number)

More

Boolean indicating if the limit of the result array is reached. When more is true, there remains objects to read, and a new GET request has to be performed, by incrementing the offset to get the rest of the data. When more is false, the end of the list has been reached and all objects have been read.

Type Information

More (boolean)

Vehicle

A vehicle is an equipment which can be refueled.

A link to a vehicle in GIR W150 can be built with:
https://domain/r/vehicles/id
where:

  • domain is the domain name you use to access your application
  • id is the vehicle id field

Properties

id
ID (string), optional

Vehicle Public ID

name
string, required

Vehicle name/label (mandatory)

badge
string, optional

Badge used for identification

ctrl_badge
string, optional

Badge sent to controller (read-only) 3

code
string, optional

Code used for identification

pin_code
string, optional

PIN code

model
Model, optional

Vehicle model

model
id
ID (string), optional

Model Public ID

name
string, optional

Model name

department
Department, optional

Department

department
id
ID (string), optional

Department Public ID

name
string, optional

Department name

kmeter
integer, optional

Odometer (in km or miles)

hmeter
number, optional

Hour meter (in hours)

notes
string, optional

Additional notes for this vehicle

vtanks
Array of Product, optional

List of products used by this vehicle

Product[]
product
object, required
product
id
ID (string), optional

Product Public ID

name
string, optional

Product name (one of id or name is required)

Driver

A driver is a person who performs a refueling.

A link to a driver in GIR W150 can be built with:
https://domain/r/drivers/id
where:

  • domain is the domain name you use to access your application
  • id is the driver id field

Properties

id
ID (string), optional

Driver Public ID

name
string, required

Driver name/label (mandatory)

first_name
string, optional

Driver first name 1

badge
string, optional

Badge used for identification

ctrl_badge
string, optional

Badge sent to controller (read-only) 3

code
string, optional

Code used for identification

pin_code
string, optional

PIN code

department
Department, optional

Department

department
id
ID (string), optional

Department Public ID

name
string, optional

Department name

activity_prompt
boolean, optional

Activity code prompt

nce_prompt
boolean, optional

NCE code prompt

notes
string, optional

Additional notes for this driver

FuelTransaction

A fuel transaction is a refueling visit at a terminal. It is typically retrieved from controllers.

A link to a fuel transaction in GIR W150 can be built with:
https://domain/r/transac_fuels/transac_id
where:

  • domain is the domain name you use to access your application
  • transac_id is the transac_id field

Properties

id
ID (string), optional

Export line UUID (unique)

transac_id
ID (string), optional

Transaction Public ID

_deleted
boolean, optional

true if the transaction was deleted

type
string, optional

"int" (internal) or "ext" (external)

date
datetime, optional

Date + time in UTC

vehicle.id
ID (string), optional

Vehicle Public ID

vehicle.name
string, optional

Name or registration

vehicle.badge
string, optional

Vehicle badge

vehicle.code
string, optional

Vehicle code

driver.id
ID (string), optional

Driver Public ID

driver.name
string, optional

Driver name

driver.fstname
string, optional

Driver first name

driver.badge
string, optional

Driver badge

driver.code
string, optional

Driver code

department.id
ID (string), optional

Department Public ID

department.name
string, optional

Department name

product.id
ID (string), optional

Product Public ID

product.name
string, optional

Product name

volume
number, optional

Distributed volume (L or gal) 2

unit_price
number, optional

Unit price 2

kmeter
integer, optional

Odometer (km or Miles) 2

hmeter
number, optional

Meter in hours

activity.id
ID (string), optional

Activity Public ID

activity.name
string, optional

Activity name

nce_code
string, optional

NCE code

site.id
ID (string), optional

Site Public ID

site.name
string, optional

Site name

pump
ID (string), optional

Pump number

manual
boolean, optional

true if created manually

mtr_forced
boolean, optional

true if the meter was forced

vol_max
boolean, optional

true if the maximum capacity was reached

new_kmeter
boolean, optional

true if the odometer was initialized

new_hmeter
boolean, optional

true if the hour meter was initialized

notes
string, optional

Transaction notes

local_date
string, optional

Local date in YYYY-MM-DD format

local_time
string, optional

Local time in HH:MM:SS format

line_id
integer, optional

Unique ID for legacy systems who can't handle UUIDs

kdelta
integer, optional

Covered distance (km or Miles) 2

kcons
number, optional

Fuel consumption (km/L or MPG) 2

hdelta
number, optional

Covered time (h)

hcons
number, optional

Fuel consumption (L/h)

tank.id
ID (string), optional

Tank Public ID

tank.name
number, optional

Tank name

RcmSite

A site is a geographical location with one or several fuel stations. This type also contains the monitoring data of the pump, tanks and accesses in that site.

A link to a site in GIR W150 can be built with:
https://domain/r/supervision/id
where:

  • domain is the domain name you use to access your application
  • id is the site id field

The pump status can be derived from the blocked, manual and pumping properties:

blocked manual pumping Pump state
false false false The pump is available for selection
true false false The pump is blocked (not available for selection)
true true true The pump is blocked but is also distributing fuel in manual mode
false true true The pump is distributing fuel in manual mode
false false true A fuel transaction has been started on this pump, and it is currently distributing fuel
true false true A fuel transaction is in progress, but a block request has been issued since the transaction started

Properties

id
ID (string), optional

site Public ID

name
string, optional

Site name

gps
string, optional

Site GPS coordinates, with the format: "latitude,longitude". Example: "37.819193,-122.478537"

controllers
Array of RcmController, optional

List of controllers

RcmController[]
sn
string, optional

Controller Serial Number (S/N)

online
boolean, optional

Whether the controller is online (true) or offline (false)

date
datetime, optional

Last time the system communicated with this controller

tanks
Array of RcmTank, optional

List of tanks

RcmTank[]
id
ID (string), optional

Tank Public ID

name
string, optional

Tank name

product.id
ID (string), optional

Product Public ID

product.name
string, optional

Product name

capacity
number, optional

Tank capacity (L or gal) 2

volume
number, optional

Gauged volume (L or gal) 2

volume_date
datetime, optional

Date and time when gauge was last read

pumps
Array of RcmPump, optional

List of pumps

RcmPump[]
id
ID (string), optional

Pump Public ID

name
string, optional

Pump name

num
string, optional

Pump number

product.id
ID (string), optional

Product Public ID

product.name
string, optional

Product name

tank.id
ID (string), optional

Tank Public ID

tank.name
string, optional

Tank name

blocked
boolean, optional

Whether the pump is currently blocked

blocked_reason
string, one of [supervisionzero_volumeserrortank_block], optional

When blocked is true, detail on the blocking reason:

  • supervision: blocked from supervision menu or API.
  • zero_volumes: blocked because of multiple consecutive null volumes.
  • error: blocked because of some hardware error.
  • tank_block: blocked because the tank stock went below the blocking threshold
manual
boolean, optional

Whether the pump is currently in manual mode

pumping
boolean, optional

Whether pumping is current delivering fuel, either because a transaction is in progress, or because manual mode is enabled (as reported by the manual field). See here for the detail of possible blocked/manual/pumping combinations.

transaction.date
datetime, optional

Date + time when the transaction on this pump started

transaction.vehicle.id
ID (string), optional

Vehicle Public ID

transaction.vehicle.name
string, optional

Vehicle name or registration

transaction.driver.id
ID (string), optional

Driver Public ID

transaction.driver.name
string, optional

Driver name

transaction.activity.id
ID (string), optional

Activity Public ID

transaction.activity.name
string, optional

Activity name

transaction.nce_code
string, optional

NCE code

transaction.kmeter
integer, optional

Odometer (km or Miles) 2

transaction.hmeter
number, optional

Meter in hours

accesses
Array of RcmAccess, optional

List of accesses

RcmAccess[]
id
ID (string), optional

Access Public ID

name
string, optional

Access name

stay_open
boolean, optional

Whether the access is currently in "stay open" mode 4

Inventory

An inventory is the result of a gauging which fetches the volume of fuel in a tank at some date.

A link to an inventory in GIR W150 can be built with:
https://domain/r/inventories/id
where:

  • domain is the domain name you use to access your application
  • id is the inventory id field

Properties

id
ID (string), optional

inventory Public ID

date
datetime, optional

Date + time in UTC

site.id
ID (string), optional

Site Public ID

site.name
string, optional

Site name

tank.id
ID (string), optional

Tank Public ID

tank.name
string, optional

Tank name

volume
number, optional

Gauged volume (L or gal) 2

temperature
number, optional

Gauged temperature (°C)

Department

Department

Properties

id
ID (string), optional

Department Public ID

name
string, optional

Department name

Model

Vehicle model

Properties

id
ID (string), optional

Model Public ID

name
string, optional

Model name

Product

Product list for a particular vehicle

Properties

product
object, required
product
id
ID (string), optional

Product Public ID

name
string, optional

Product name (one of id or name is required)

RcmController

Controller monitoring data

Properties

sn
string, optional

Controller Serial Number (S/N)

online
boolean, optional

Whether the controller is online (true) or offline (false)

date
datetime, optional

Last time the system communicated with this controller

RcmTank

Tank monitoring data

Properties

id
ID (string), optional

Tank Public ID

name
string, optional

Tank name

product.id
ID (string), optional

Product Public ID

product.name
string, optional

Product name

capacity
number, optional

Tank capacity (L or gal) 2

volume
number, optional

Gauged volume (L or gal) 2

volume_date
datetime, optional

Date and time when gauge was last read

RcmPump

Pump monitoring data

Properties

id
ID (string), optional

Pump Public ID

name
string, optional

Pump name

num
string, optional

Pump number

product.id
ID (string), optional

Product Public ID

product.name
string, optional

Product name

tank.id
ID (string), optional

Tank Public ID

tank.name
string, optional

Tank name

blocked
boolean, optional

Whether the pump is currently blocked

blocked_reason
string, one of [supervisionzero_volumeserrortank_block], optional

When blocked is true, detail on the blocking reason:

  • supervision: blocked from supervision menu or API.
  • zero_volumes: blocked because of multiple consecutive null volumes.
  • error: blocked because of some hardware error.
  • tank_block: blocked because the tank stock went below the blocking threshold
manual
boolean, optional

Whether the pump is currently in manual mode

pumping
boolean, optional

Whether pumping is current delivering fuel, either because a transaction is in progress, or because manual mode is enabled (as reported by the manual field). See here for the detail of possible blocked/manual/pumping combinations.

transaction.date
datetime, optional

Date + time when the transaction on this pump started

transaction.vehicle.id
ID (string), optional

Vehicle Public ID

transaction.vehicle.name
string, optional

Vehicle name or registration

transaction.driver.id
ID (string), optional

Driver Public ID

transaction.driver.name
string, optional

Driver name

transaction.activity.id
ID (string), optional

Activity Public ID

transaction.activity.name
string, optional

Activity name

transaction.nce_code
string, optional

NCE code

transaction.kmeter
integer, optional

Odometer (km or Miles) 2

transaction.hmeter
number, optional

Meter in hours

RcmAccess

Access monitoring data

Properties

id
ID (string), optional

Access Public ID

name
string, optional

Access name

stay_open
boolean, optional

Whether the access is currently in "stay open" mode 4

RcmBlockPump

Pump blocking request

Properties

pump
ID (string), optional

Public ID of the pump to block

RcmUnblockPump

Pump unblocking request

Properties

pump
ID (string), optional

Public ID of the pump to unblock

RcmStartPump

Start a remote fuel transaction

Properties

pump
ID (string), optional

Public ID of the pump

vehicle
ID (string), optional

Public ID of the vehicle

driver
ID (string), optional

Public ID of the driver

kmeter
integer, optional

Odometer (km or Miles) 2

hmeter
number, optional

Meter in hours

activity
ID (string), optional

Public ID of the activity

nce_code
string, optional

NCE code

RcmForceRefresh

Schedule gauging request

Properties

site
ID (string), optional

Public ID of the site to gauge