Advance Integration

Rental relay api integration for locations

All request in these documents are written as raw http request, and you convert that to what ever language

Schema

We provide an open api v3 schema.

You can find it here: https://prod.rr.apis.stefna.is/openapi.json

Visit data

Visit data needed by the api are

Vehicle plate
Vehicle owner kennitala
Vehicle registration date
Visit started on 2022-04-27 15:41:00
Visit ended on 2022-04-27 15:41:00 can be the same as started on

Flow

sequenceDiagram

actor Customer
participant "Location"
participant "Rental Relay"

Customer->"Location": Pay for service
"Location"->"Rental Relay":Check if owner of vehicle is part of api
alt If not
    "Rental Relay"-->"Location":Returns nothing
    "Location"-->Customer:Payment complete
end
"Rental Relay"-->"Location":Returns company
"Location"->"Rental Relay":Find active vehicle by license plate
alt If no vehicle
    "Location"->"Rental Relay":Create new vehicle
    "Location"->"Rental Relay":Create new vehicle custodian
end
"Rental Relay"-->"Location":Return vehicle
"Location"->"Rental Relay":Create payment
"Location"-->Customer:Payment complete

Http flow

Check if owner of vehicle is part of api

GET https://baseUrl/rental-comapnies?kennitala={{vehicle.owner}}
Authorization: Bearer {{TOKEN}}

Response

[
    {
        "id": "1ec30e4c-8aed-64e2-8cd9-0242bb17e826",
        "name": "Höldur",
        "kennitala": "1111111111"
    }
]

Find active vehicle by license plate

GET https://baseUrl/vehicles?plate={{vehicle.plate}}
Authorization: Bearer {{TOKEN}}

Response

[
    {
        "id": "1ec30e4c-8aed-64e2-8cd9-0242bb17e826",
        "plate": "ABC123",
        "country": "is"
    }
]

Create new vehicle

POST https://baseUrl/vehicles
Content-Type: application/json
Authorization: Bearer {{TOKEN}}

{
    "plate": "ABC123",
    "country": "is"
}

Response

{
    "id": "1ec30e4c-8aed-64e2-8cd9-0242bb17e826",
    "link": "/vehicles/1ec30e4c-8aed-64e2-8cd9-0242bb17e826"
}

Create new vehicle custodian

POST https://baseUrl/custodians
Content-Type: application/json
Authorization: Bearer {{TOKEN}}

{
    "vehicleId": "1ec30e4c-8aed-64e2-8cd9-0242bb17e826", 
    "rentalCompanyId": "1ec30e4c-8aed-64e2-8cd9-0242bb17e826",
    "acquiredOn": "2022-04-27 16:14:42" // date the vehicle was accuired by the owner
}

Response

{
    "id": "1ec30e4c-8aed-64e2-8cd9-0242bb17e826",
    "link": "/custodians/1ec30e4c-8aed-64e2-8cd9-0242bb17e826"
}

Create payment

POST https://baseUrl/payments
Content-Type: application/json
Authorization: Bearer {{TOKEN}}

{
	"locationId": {{locationId}},
	"vehicleId": {{vehicleId}},
	"amount": {
		"amount": 1000,
		"currency": "ISK" // at the moment the only supported currency is ISK
	},
	"startedOn": {{visit.startedOn}},
	"endedOn": {{visit.endedOn}}
}

Response

{
    "id": "1ec30e4c-8aed-64e2-8cd9-0242bb17e826",
    "link": "/payments/1ec30e4c-8aed-64e2-8cd9-0242bb17e826"
}

Js example


const visit = {
	startedOn: '2022-04-27 14:00:00',
	endedOn: '2022-04-27 14:35:00',
	vehicle: {
		plate: "test plate",
		regDate: '2020-01-05 12:43:12'
	},
	customer: {
		kennitala: "1234123412" // should be rental company kennitala
	}
};

createPayment(visit);

async function createPayment(visit) {

	const companies = await queryApi('/rental-companies', {
		kennitala: visit.customer.kennitala,
	})
	if (!companies.length) {
		return; // skip rental company not part of rental-relay
	}
	const company = companies[0];

	const vehicles = await queryApi('/vehicles', {
		plate: visit.vehicle.plate,
	});

	let vehicleId = null;
	if (!vehicles.length) {
		const response = await sendToApi('/vehicles', {
			plate: visit.vehicle.plate,
			country: 'is',
		});
		await sendToApi('/custodians', {
			vehicleId: response.id,
			rentalCompanyId: company.id,
			acquiredOn: visit.vehicle.regDate
		});
		vehicleId = response.id;
	} else {
		vehicleId = vehicles[0].id;
	}

	await sendToApi('/payments', {
		locationId: 'the location id',
		vehicleId: vehicleId,
		amount: {
			amount: 1000,
			currency: 'ISK' // at the moment the only supported currency is ISK
		},
		status: 'new',
		startedOn: visit.startedOn,
		endedOn: visit.endedOn,
	});
}

const baseUrl = 'https://baseurl';
const apiToken = 'your api token';

async function queryApi(endpoint, query)
{
	const queryString = Object.keys(query).map(key => key + '=' + query[key]).join('&');
	const response = await fetch(baseUrl + endpoint + '?' + queryString, {
		headers: {
			'Content-Type': 'application/json',
			'Authorization': 'Bearer ' + apiToken,
		},
	});
	return response.json();
}

async function sendToApi(endpoint, payload)
{
	const response = await fetch(baseUrl + endpoint, {
		method: 'POST',
		headers: {
			'Content-Type': 'application/json',
			'Authorization': 'Bearer ' + apiToken,
		},
		body: JSON.stringify(payload) // body data type must match "Content-Type" header
	});
	return response.json();
}