Integration - REST

EROAD will provide a RESTful webservice to receive fuel transaction data with the name “fueltransaction”. Data will be received via the PUT operation. The content type is "application/xml".

API clients must ensure the ‘Host’ header is set correctly on all requests to ensure we are able to route the request to the correct backend. Most HTTP libraries will set this header on your behalf, however it is worth checking.

See http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html for more information on the ‘Host’ header.

Example URL: http://hostname/FuelIntegration/fueltransaction

 

Fuel card / vehicle subscription

It is assumed that the customer will inform the fuel provider for what fuel cards/vehicles to send fuel transaction data. This process has to be handled by the customer and the fuel provider.

 

Data ordering

Data is sent from the fuel third party in near real-time. However, data should not be assumed to come in order.

 

Latency

Fuel transaction data will ideally be sent after a successful transaction has occurred.

 

Performance

The load from fuel transaction data is not expected to be high. EROAD will queue and asynchronously process the data to avoid blocking the client.

 

Validation

Validation will be performed by the service and an http 400 error code will be returned when the request fails to meet the validation. For example, the dollar amount of the products and total transaction amount do not equal, or both site coordinates and site address are not present etc.

 

Void transactions

When a fuel purchase is refunded or reversed the original transaction must be voided. It is expected that the same data is sent with the transaction type of ‘VOID’ instead of ‘PURCHASE’.

If the purchase is redone then a new PURCHASE transaction must be sent with a new transaction id.

The diagram below describes the messaging to EROAD when a customer incorrectly purchases for “pump5” when they should have purchased for “pump7”.

 

fuel api 2