How to import the collection

1. Ensure you are using the latest version of Postman to avoid possible incompatibilities.
2. Open Postman.
3. Select file -> Import in the left navigation menu.
4. Click on upload files and browse for the file named: Livn v2.x Tours & Activities API.
5. Open the file and then finally click the import button.

How to use the collection

Once the collection is imported you’ll find the following structure under Postman.

Security / Authentication

To start we recommend you familiarize yourself with the security of the API as seen in https://dev.livnapi.com/public/Livn_API_v2.0_Developer_Guide.pdf Section 3.

As explained in the section we provide two forms of authentication (1) Basic HTTP authentication and (2) JSON Web Tokens (JWT).

For convenience, we recommend the use of Basic HTTP authentication for the postman collections because it’ll make the configuration easier.

In order to set the Basic HTTP authentication, click on the collection name and make sure to fill in your API username and password as seen in the image below:

This will automatically apply the same API username and password for the collection.

While you are there, under variables you will see one variable already defined baseUrl for the API URL. This is set to: https://dev.livnapi.com, which is our development and test endpoint.

Once the Authentication is set up, you can start exploring the different endpoints provided by the API. For all endpoints, you’ll find an Example under OK.

After looking at the security section of the developer guide you should be familiar with how to use the login and logout endpoints, and how to use JWT for further authentication in other endpoints in case you are not using a secure backend where you can save your API credentials.

Getting into the flow

A normal booking flow will generally start with the following steps:

1. Product search. You can find the product search endpoint under the products folder and search.
   

This endpoint has an already configured body that you’ll need to modify according to the required filter criteria. You can check the example which will retrieve all products in a 100km radius of Sydney airport with a minimum duration of 20 minutes and only those belonging to those category id’s included. The results will be ordered in ascending order by the product id and a maximum of 3 results per page will be returned.

This endpoint has an already configured body that you’ll need to modify according to the required filter criteria. You can check the example which will retrieve all products in a 100km radius of Sydney airport with a minimum duration of 20 minutes and only those belonging to those category id’s included. The results will be ordered in ascending order by the product id and a maximum of 3 results per page will be returned.

1. You can retrieve any page of an existing product search with the GET endpoint: GET-​/api/products/search by providing the desired parameters.
2.  After a product search usually follows the step to get the product details, this can be achieved by using the products endpoints specifically GET-/api/products/:productId?includeDisabled=false, this postman collection will automatically retrieve a demo product with id = 1.
   While you are in the products folder you can check all the other endpoints for example:

• GET-/api/products/categories which will retrieve all the existing product categories.
• POST-/api/products/cities which will retrieve a list of product cities that appear as a product search reference start location, i.e. `Product.locationsStart`. You can configure the required filters in the body in order to receive a reduced set or just send an empty payload to receive all.

1. After the product information is loaded you’ll need to find the dates where this product is available, this can be done with the following endpoint:
   GET-/api/products/:productId/departures?startDate=&endDate=&includeDisabled=false
   This endpoint has been configured to retrieve availability for the next 10 days from the current date for the demo product with id = 1.
2. From here you usually start a new booking flow by posting the product id and desired available date from the previous step with the following endpoint from the flows folder.:
   POST-/api/flows?back=false&includeAllSteps=true
   We recommend using our Alice tool (https://alice.livnapi.com)  in order to test the booking flow because its behaviour is dynamic and the responses can be different depending on multiple parameters.
3. We provide similar functionality in the suppliers folder so you will be able to load a supplier by id, perform a supplier search and also an important endpoint that can be found under suppliers and can be used to retrieve all the product ids grouped by the supplier id, the product status can be any of the following: ALL, DISABLED_ONLY, NON_DISABLED_ONLY
   GET-/api/suppliers/productMinDetails?productStatus=NON_DISABLED_ONLY
   
   
4. After the booking flow is completed you can use the bookings and the tickets endpoints in this collection.
   
   Bookings endpoints:

• Retrieve an existing booking via a search with multiple optional filters:
  GET-/api/bookings?anyReference=&id=&supplierIds=&productIds=&livnReference=&clientReference=&supplierReference=&partyName=&partyEmailAddress=&confirmedFrom=&confirmedTo=&travelFrom=&travelTo=&order=ID&orderDescending=true&resultsPerPage=100&currentPage=1&includeChannel=false&includeDistributor=false
• Cancel an existing booking:
  DEL-/api/bookings/:bookingId?reason=Reason for cancelling the booking
  Note: In the response, you’ll receive a cancellation object which will only contain a confirmed timestamp in case of a successful cancellation or a cancellation object with an error in case of a failed cancellation. 
• Generate a PDF version of the booking voucher:
  GET-/api/bookings/pdf/:bookingId?sellerInfo=seller info to override
  The optional sellerInfo query parameter can be used to override the seller information printed on the voucher (if any, top right corner). Use %0D%0A (Windows CRLF) or %0A (Unix LF) for line breaks.

Tickets endpoints:

• Retrieve an existing ticket via a search with multiple optional filters:
  GET-/api/tickets?anyReference=&id&supplierReference=&passengerName=&order=ID&orderDescending=false&resultsPerPage=100&currentPage=1
• Generate a PDF version of the ticket voucher:
  GET-/api/tickets/pdf/:ticketId?sellerInfo=seller info to override
  The optional sellerInfo query parameter can be used to override the seller information printed on the voucher (if any, top right corner). Use %0D%0A (Windows CRLF) or %0A (Unix LF) for line breaks.