In order to complete the rental process, you'll need the following data: - A Resource ID, which is the boat ID - A Slot ID, which is the time period ID - A User ID, which is the boat renter / client ID
You'll want to follow this workflow: 1. Search for a suitable boat 2. Get rental durations for the selected boat 3. Get time slots for the selected boat 4. Initiate the rental 5. Get user information 6. Attach user to rental 7. Pay downpayment 8. Confirm rental
You can search for boats using the /resources endpoint. To perform the
actual search, you can specify many filters, such as price, power, or
geographical coordinates. Please consult the technical documentation
for an exhaustive list.
Boats can be rented for different durations. A small electric boat
might be rentable for a few hours only, while a large motorboat might
be rentable for an entire week. You can retrieve durations using the
/resources/<resourceId>/durations endpoint.
Once you know of the available durations, you can search for an actual
time slot, using the
/resources/<resourceId>/slots?date=<date>&duration=<duration>
endpoint.
You now have enough information to initiate the rental. You can
initiate the rental by sending a POST message to the /rentals
endpoint. Please note that you still need to provide a user ID later.
Furthermore, any pending rental will automatically expire after 15
minutes.
Gather user information using your own means. Once you have the
information required, you can create a new user by sending a POST
message to the /users endpoint. Please consult the technical
documentation to know exactly which information you need to provide in
order to create a user.
Once you have created your user, you can attach it to the rental by
sending a POST message to the /rentals/<rentalID>/user. Please note
that you can't change the rental user once it is set, so please be
extra careful during this step.
Although not mandatory, it is good practice to pay at least the
downpayment before confirming the rental. The payment itself is
handled by third-parties. However, we still offer a way to log payments
into our database. To do so, send a POST message to the
/rental/<rentalId>/payments endpoint. To know how much you need to
pay, you can use the /rental/<rentalId>/resource endpoint.
Once you have set everything you wanted to set, it is time to confirm
the rental. You can set more than just a user. You can attach optional
goods and services to a rental. For instance, you can buy a lunch box
to enjoy while sailing. Please consult the technical documentation as
well as the extensive workflow documentation for more information. You
can confirm the rental by attempting to change its status, by sending a
PUT message to the /rentals/<rentalId> endpoint.
In order to book a rental, you need the following pieces of information: - A resource ID. Resources represent boats, so of course you would need one to identify the one boat you want to rent. - A time slot ID. Time slots represent specific time periods. They not only specify when a rental starts and ends, but also contains extra information, such as the options available for that time period. - A user ID. Users represent boat renters, clients. You do not need to specify a user when initiating the rental, but you do need to specify it later down the rental process.
Here's the workflow we recommend. Of course, this is but a recommendation: feel free to adapt it to better suit your desired user experience.
First: you need to get your hands on the perfect boat! Boats are resources, and so the boat's ID is the resource ID you'll need to provide when initiating the rental.
You can access boats through the /resources family of endpoints. You
can filter boats using a wide variety of filters, including but not
limited to:
- Base price
- Power
- Geographical coordinates
- And many more!
For instance, here's how you would retrieve a list of boats that can be handled without a mandatory boating license:
GET https://api.digital-nautic.fr/v3/resources?onlyWithoutLicense=true
Please consult the technical documentation for an exhaustive list of available filters.
If you want to build your own search engine over those filters, we also provide a way to check for boat availability. We require you to specify a rental duration. More information on rental durations can be found on the next section of this document, so please come back here when you've gotten familiar with them.
There is a special endpoint, /resources/availabilities that can be
used to check for availability of list of boats. You use it by
specifying a list of boat IDs, a date, and a duration, like so:
GET https://api.digital-nautic.com/v3/resources/availabilities
?resourceIds=1,2,3
&date=2019-07-10
&duration=DAYS,1
This example would check availabilities for boats of ID 1, 2 and 3, for the 10th of July, 2019, for a rental of a single day. For instance, you may implement it in your search engine by returning boats corresponding to the selected filters immediately, and then updating availability on the fly.
Boats can be rented for different durations. For instance, a small electric boat might be rentable for a few hours only, while a large motorboat might be rentable for an entire week! In practice, boat rental durations are set partly by their types (the aforementioned electric and motor boats for instance), and partly by the company renting the boat.
As such, you need to retrieve durations on a per-boat basis. Here's an example that will return durations for the resource with ID 1:
GET https://api.digital-nautic.com/v3/resources/1/durations
Once you have durations, you can search for time slots. Time slots represent time periods, available for rental. They mark the start and end of a rental, and include additional information, such as additional options.
Here’s an example of how to list time slots for resource ID 1, the 10th of July 2019, and one day:
GET https://api.digital-nautic.com/v3/resources/1/slots
?date=2019-07-10
&duration=DAYS,1
Once you have the resource ID and slot ID, you can initiate a rental. Please note that you’re only initiating a rental at this point: you’ll still need to confirm it later. Furthermore, any pending rental will automatically expire after 15 minutes.
To initiate a rental, you need to send a POST message to the /rentals
endpoint:
POST https://api.digital-nautic.com/v3/rentals
{ “resourceId”: 1, “slotId”: “<slotId>” }
You’ll then need to gather user information. Once you have gathered
enough information, you’ll need to register the user to DNAPI, and
finally attach it to the rental. You can create a user by sending a
POST message to the /users endpoint:
POST https://api.digital-nautic.com/v3/
{ /* user data */ }
Once you’ve saved a user into the API, you can attach it to the rental. Please note that once the user is attached to the rental, you cannot attach a different user, nor remove the user, and so you’ll have to be extra careful when using this endpoint.
POST https://api.digital-nautic.com/v3/rentals/1/user
{ “userId”: 1 }
The penultimate step is to pay for the rental. You do not need to pay a minimum amount in order to confirm the rental, but it is good practice to pay at least the downpayment amount. Of course, in cases where the downpayment amount is lower than the full rental price, you then don't have to pay the full rental in advance.
To know how much you'll have to pay, you can use the following endpoint:
GET https://api.digital-nautic.com/v3/rentals/1/resource
However, it should be noted that we don't handle payments ourselves. Payment is done though third-parties. However, we still offer a way to log those payments into our database.
In order to log one such payment, you need to send a POST request to
the /rentals/<rentalID>/payments endpoint, as follow:
POST https://api.digital-nautic.com/v3/rentals/1/payments
{
"method": {
"id": 2192,
"name": "Online payment",
},
"reference": "third-party-payment-reference-123",
"price": 299.99,
"currency": "EUR",
}
Finally, once you’ve set all that you want to set to the rental, you need to confirm it. In order to do that, you need to edit the rental and try to change its status. For instance, here’s how you’ll confirm the rental ID 1:
PUT https://api.digital-nautic.com/v3/rentals/1
{ “status”: “VALIDATED” }