Skip to content

Getting Started

How to implement the Parking SDK

The following sections cover how you can get started using Parking functionality. You can easily integrate the Parking Service by following these steps.

1. Dependencies

Open the main build.gradle file of your project and add the following dependencies:

1
2
3
4
5
6
7
dependencies {

    implementation 'com.telenav.commerce:parkingservice:${version}'

    implementation 'com.telenav.commerce:common:${version}'

}

2. Initialization of the Parking Service

The entry point to the Commerce Parking Service is the IParkingApi which exposes the APIs reflecting the parking service functionality.

IParkingApi

IParkingApi is exposed to the client by the implementation of IParkingManagerProvider → ParkingManagerProvider.

The IParkingApi interface represents the entry point to the parking service module. It exposes APIs for getting parking specific information.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
interface IParkingApi {

    fun init(
        apiEndpoint: ApiEndpoint = ApiEndpoint.PRODUCTION,
        apiKey: String,
        apiKeySecret: String,
        userServiceProvider: IParkingUserServiceProvider,
        paymentProvider: IParkingPaymentServiceProvider
    )

    //...

    suspend fun getQuoteForParking(
        parkingId: String,
        parkingTime: ParkingTime
    ): CommerceResponse<Quote>

    suspend fun reserveParking(
        parkingId: String, parkingTime: ParkingTime, quoteReference: String,
        paymentRequest: PaymentRequest
    ): CommerceResponse<String>

    //...

    suspend fun getLastParkingReservation(): CommerceResponse<ParkingOrderInformation>

    suspend fun getParkingHistory(
        sorting: String = Sorting.DESCENDING.name
    ): CommerceResponse<List<ParkingOrderInformation>>

    suspend fun cancelParkingReservationById(
        orderId: String
    ): CommerceResponse<Status>
}

The init method initializes or updates the parking service. Before interacting with the parking service, the client is responsible to call this method. In case of a desired switch to a different environment, the method can be called again with the new endpoint and corresponding api keys and tokens.

The apiEndpoint parameter denotes the Commerce Service environment that we will use. The default value points to ApiEndpoint.PRODUCTION.

The apiKey parameter's unique key is used by each integration client in order to use parking module functionality.

The apiKeySecret parameter's unique key is used by each integration client in order to use parking module functionality together with apiKey.

The userServiceProvider parameter: The user dependency is required by parking service for proper running. View the IParkingUserServiceProvider specifications.

The paymentProvider parameter: The user dependency is required by parking service for proper running. View the IParkingPaymentServiceProvider specifications.

1
2
3
4
5
6
7
fun init(
        apiEndpoint: ApiEndpoint = ApiEndpoint.PRODUCTION,
        apiKey: String,
        apiKeySecret: String,
        userServiceProvider: IParkingUserServiceProvider,
        paymentProvider: IParkingPaymentServiceProvider
    )


The getQuoteForParking method returns the quote for the parking place with the given id in the time interval between the given start time and end time.

The parkingId parameter represents the id of the parking place for which the price info should be returned.

The parkingTime parameter is an object containing the start time and end time of the parking together with the timezone.

The method returns the Quote for the requested parking place.

1
2
3
4
  suspend fun getQuoteForParking(
        parkingId: String,
        parkingTime: ParkingTime
    ): CommerceResponse<Quote>


The reserveParking method makes a parking reservation for the parking place with the given parking id (that was previously selected).

The parkingId parameter represents the id of the parking place for which the reservation should be done.

The parkingTime parameter is an object containing the start time and end time of the parking together with the timezone.

The quoteReference parameter representes the quote reference id retrieved from the getQuoteForParking call.

The paymentRequest is an object containing the payment method.

This method returns a String object holding the payment response in a json format.

1
2
3
4
    suspend fun reserveParking(
        parkingId: String, parkingTime: ParkingTime, quoteReference: String,
        paymentRequest: PaymentRequest
    ): CommerceResponse<String>

The getLastParkingReservation method returns information ParkingOrderInformation about the last parking reservation.

1
    suspend fun getLastParkingReservation(): CommerceResponse<ParkingOrderInformation>


The getParkingHistory method will return all the parking orders satisfying the given conditions.

The sorting parameter shows the way the results should be sorted; values in Sorting.

The default value is Sorting.DESCENDING.

The method returns a list of ParkingOrderInformation reservations of the provided user.

1
2
3
    suspend fun getParkingHistory(
        sorting: String = Sorting.DESCENDING.name
    ): CommerceResponse<List<ParkingOrderInformation>>


The cancelParkingReservationById method will cancel the parking reservation with the given order id.

The orderId parameter represents the id of the parking reservation that should be canceled.

The method returns the status of the cancel operation. 

1
2
3
    suspend fun cancelParkingReservationById(
        orderId: String
    ): CommerceResponse<Status>

IParkingManagerProvider

The IParkingManagerProvider interface is used for exposing an implementation of the API that should be used by the client for accessing the parking module functionality. 

1
2
3
4
5
6
interface IParkingManagerProvider {

    fun provide(): IParkingApi

    fun provide(commerceApi: IParkingCommerceApi): IParkingApi
}

This method provides a concrete implementation object of the parking module API.

The return value is the instance that should be used by the client for accessing the parking module functionality. View the IParkingApi specifications.

1
fun provide(): IParkingApi

This method provides a concrete implementation object of the parking module API.

The commerceApi parameter implementation for IParkingCommerceApi.

It returns The instance that should be used by the client for accessing the parking module functionality. View the IParkingApi specifications.

1
fun provide(commerceApi: IParkingCommerceApi): IParkingApi

The client is responsible to provide an implementation of IParkingUserServiceProvider and IParkingPaymentServiceProvider interfaces.

Here is the code on how to initialize the parking service using the ParkingManagerProvider.

1
2
3
4
5
6
7
ParkingManagerProvider.provide().init(
    apiEndpoint,
    apiKey,
    apiKeySecret,
    object : IParkingUserServiceProvider {},
    object : IParkingPaymentServiceProvider {}
)

IParkingUserServiceProvider

The IParkingUserServiceProvider interface defines the user data related methods that are requested for a proper running of the parking service. The client is responsible to provide an implementation of this interface.

1
2
3
4
5
6
7
8
interface IParkingUserServiceProvider {

    fun hasLicensePlate(): Boolean

    fun hasPhoneNumber(): Boolean

    fun getUserToken(): String
}

The hasLicensePlate method confirms if the user has license plate.

It returns "true" if the user has license plate, otherwise it returns "false". 

1
fun hasLicensePlate(): Boolean


The hasPhoneNumber method confirms if the user has phone number.

It returns "true" if the user has phone number, otherwise it returns "false".

1
fun hasPhoneNumber(): Boolean


The getUserToken method retrieves the user token.

It returns a string value.

1
fun getUserToken(): String


Implementation example for User Service Provider

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
object : IParkingUserServiceProvider {
    override fun getUserToken(): String {
        return UserWrapper.getUserToken(context)
    }

    override fun hasLicensePlate(): Boolean {
        return true
    }

    override fun hasPhoneNumber(): Boolean {
        return true
    }
}


IParkingPaymentServiceProvider

The IParkingPaymentServiceProvider interface defines the payment data related methods that are requested for a proper running of the parking service. The Client is responsible to provide an implementation of this interface.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
interface IParkingPaymentServiceProvider {

    suspend fun pay(
        priceInfo: PriceInfo,
        orderId: String,
        clientSecret: String
    ): CommerceResponse<String>

    fun hasPaymentCard(): Boolean

    fun getCard(): Card
}

The pay method returns the status of the confirm payment action. The orderId parameter represents the id of the current parking order.

The priceInfo parameter represents the PriceInfo of the current parking order.

The clientSecret is a temporary token which facilitates the validation of the user in the P97 database.

It returns a String object holding the payment response in a json format.

1
2
3
4
5
suspend fun pay(
        priceInfo: PriceInfo,
        orderId: String,
        clientSecret: String
    ): CommerceResponse<String>

The hasPaymentCard method confirms if the user has a payment card.

It returns "true" if the user has a payment card, otherwise it returns "false".

1
fun hasPaymentCard(): Boolean


The getCard method retrieves the user Card.

1
fun getCard(): Card


Implementation example for Payment Service Provider

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
object : IParkingPaymentServiceProvider {
    override suspend fun pay(
        priceInfo: PriceInfo,
        orderId: String,
        clientSecret: String
    ): CommerceResponse<String> {
        return PaymentManagerProvider.provide().pay(priceInfo, clientSecret, orderId)
    }

    override fun getCard(): String {
        return Card("1232", "Debit", "Visa", "US", 12, 2025, 4035)
    }

    override fun hasPaymentCard(): Boolean {
        return true
    }
}

2.2 Initialization of the Parking Service with a IParkingCommerceApi provided by the client

If the client needs a specific SDK (network) configuration, they can initialize the parking service passing their own instance of IParkingCommerceApi. 

1
2
3
4
5
6
7
ParkingManagerProvider.provide(parkingCommerceApi).init(
    apiEndpoint,
    apiKey,
    apiKeySecret,
    object : IParkingUserServiceProvider {},
    object : IParkingPaymentServiceProvider {}
)

IParkingCommerceApi represents the entry point in commerce service regarding the parking flow. It exposes the APIs needed in order to get parking specific information.

IParkingCommerceApi

The IParkingCommerceApi interface represents the entry point to Commerce Service regrading the parking flow. It exposes APIs needed for getting parking specific information.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
interface IParkingCommerceApi {

    fun setConfiguration(configuration: SdkConfiguration)

    //...

    suspend fun getQuoteForParking(
        parkingId: String,
        parkingTime: ParkingTime
    ): CommerceResponse<Quote>

    suspend fun cancelParkingReservationById(
        orderId: String
    ): CommerceResponse<Status>

    suspend fun emptyCart(): CommerceResponse<StatusResponse>

    suspend fun addParkingReservation(
        parkingId: String,
        parkingTime: ParkingTime,
        quoteReference: String
    ): CommerceResponse<StatusResponse>

    suspend fun placeOrder(@Body paymentRequest: PaymentRequest): CommerceResponse<ParkingOrderResponse>

    suspend fun getParkingHistory(
        sorting: String,
        limit: Int? = null
    ): CommerceResponse<List<ParkingOrderInformation>>
}


The setConfiguration updates the IHttpApi instance with the given configuration to be used in the communication with commerce service. Here are the configuration parameters to be used:

1
fun setConfiguration(configuration: SdkConfiguration)

The getQuoteForParking returns the quote for the parking place with the given id in the time interval between the given start time and end time.

The parkingId parameter represents the id of the parking place for which the price info should be returned.

The parkingTime parameter contains:

  • the enter date and time for parking reservation as destination timezone, in ISO 8601 format: 'yyyy-mm-ddThh:mm:ss' and
  • the end date and time for parking reservation as destination timezone, in ISO 8601 format: 'yyyy-mm-ddThh:mm:ss'

It returns the Quote for the requested parking place.

1
2
3
4
suspend fun getQuoteForParking(
        parkingId: String,
        parkingTime: ParkingTime
    ): CommerceResponse<Quote>

The cancelParkingReservationById method cancels the parking reservation with the given order id.

The orderId parameter represents the id of the parking reservation that should be canceled.

The CommerceResponse returns the status of the cancel operation.

1
2
3
suspend fun cancelParkingReservationById(
        orderId: String
    ): CommerceResponse<Status>

The emptyCart clears the current shopping cart.

1
suspend fun emptyCart(): CommerceResponse<StatusResponse>


The addParkingReservation adds a parking reservation to your shopping cart.

The parkingId parameter is the id of the parking where you want to book a parking spot.

The parkingTime parameter is an object containing the start time and end time of the parking together with the timezone.

The quoteReference parameter is the quote reference id retrieved from the getQuoteForParking call.

It returns the status of the API call, together with the message received from the server.

1
2
3
4
5
suspend fun addParkingReservation(
        parkingId: String,
        parkingTime: ParkingTime,
        quoteReference: String
    ): CommerceResponse<StatusResponse>


The placeOrder method places the order that was previously added in the shopping cart.

The paymentReques is an object containing the payment method.

It returns the status of the API call, together with the message received from the server.

1
suspend fun placeOrder(@Body paymentRequest: PaymentRequest): CommerceResponse<ParkingOrderResponse>

The getParkingHistory method returns all the parking orders satisfying the given conditions.

The sorting parameter represents the way the results is sorted. The values are presented in Sorting section.

The default is descending Sorting.DESCENDING.

It returns a list of ParkingOrderInformation reservations of the provided user.

1
2
3
4
suspend fun getParkingHistory(
        sorting: String,
        limit: Int? = null
    ): CommerceResponse<List<ParkingOrderInformation>>