Articles in this section

JRNI API Best Practices

bookinglab
  • Updated
Follow

Dates / Times

The API uses ISO 8601 and therefore uses UTC. The JRNI platform allows you to configure time zones per Company ID (location) in the Admin UI and via Admin API calls. When creating services or events you should set the Date / Time per the location time with correct UTC offset.

Pagination

JRNI GET calls for data use pagination (page and per_page parameters) to ensure performance of the API responses. Please see the guidelines detailed in the online JRNI documentation.

Supported TLS versions

JRNI only accepts API connections using Transport Security Layer (TLS) v1.2. Different Operating Systems, Browsers and applications still use ciphers that only support 128 bit encryption, ie SSL / TLS v1 and v1.1. Please ensure you use TLS v1.2 as your minimum standard when connecting to all JRNI API environments.

Basket or Booking API call

The Booking API call allows for a single booking only and does not allow the time slot selected to be reserved for the user. The Basket API call allows you to let your customers make more than a single booking at a time and reserves the selected time slot until they confirm the booking with the Checkout API call.

Time Data (v1) or Times (v3) API calls

JRNI Configuration items which impact the Time Data response:

  1. Service Minimum Advance time - set to a specific min/hour/day/week.

  2. Service has Booking Steps turned on / off for different services.

  3. Whether the service is configured to have both People & Resource as mandatory (or either simply a Person or a Resource as mandatory)

  4. If the Service, Person or Resource is set up as Bookable.

  5. Including the Auth-Token in the HTTP will treat the results as an Admin booking and ignore Min Advance times and show results for non-bookable services, people, etc.

Times (v3) / Time Data (v1) API calls

The Times call allows you to find available dates and times for bookings. It filters the response using the various parameters. The Times response will be different if the Service is configured with Booking Steps. If Booking steps are turned on for a Service, the Times response will display all results with set time intervals and block out time intervals as unavailable as bookings are made. Without Booking Steps turned on in JRNI, unavailable time slots will not be returned in the API response.

Day Data and Times / Time Data

It is best practice to limit the data range for the Times call to ensure performance and efficiency of the API response. If your use case requires the return of multiple dates in a calendar with available booking slots, best practice is to use the Day Data call to show the current date / future dates with availability and once the user selects a particular date, call the time data / times call to display the details of the available time slots on the selected date.

Admin API Bookings

The Admin API booking call functions the same as manually making a booking in JRNI via an Admin login. When making the booking the user will be able to bypass / override any booking rules such as minimum time in advance, min cancel times and also allow to book outside available times setup in JRNI.

Admin API Reporting

The GET Admin Bookings call can be used for reporting for adhoc queries.

The SEARCH Admin Bookings (v3) calls should be used for larger volumes of calls. These calls use Elastic Search queries and can be run on the various JRNI entities to meet your reporting requirements.

Webhooks

Webhooks or Push APIs can be used to provide on-demand updates to bookings, eg new bookings, updates to bookings and cancellations of bookings regardless of the change the booking was made from.

This can require commercials, speak to your Account Manager.

Single Sign On

Ensure you include and correctly set the Expiry Date and Time when creating the SSO Token.

Auth-Tokens

Admin:

Auth-Tokens returned from JRNI API login (Member or Admin) calls or SSO login calls are valid for 24 hours. A HTTP 401 error is returned when the Auth-Token has expired. A new Auth-Token is issued every time you submit the SSO or API login call and each login user will be issued their own Auth-Token.

Public:

For Public API booking journeys, an Auth-Token is issued when an item is added to the basket. The Auth-Token issued here must be used in the basket checkout within the same user session.

GET Method

Use parameters in the API Endpoint / URI. In Postman, these are located in “Params” section of the call screen.

curl -X GET \ 'https://{{host}}/api/v1/{{company_id}}/day_data?service_id=48355&date=2019-10-25&edate=2019-11-01

POST and PUT Methods

Only useJSON Payloadsto add additional data to the API call. In Postman, this is located in the “Body” section of the call screen.

'{
"entire_basket": "true",
"service_id": "48351",
"date": "2019-08-17",
"time": "540"
}'

Capturing Booking Information

Booking Questions

This should be used for specific service related queries such as “Do you have your child’s measurements?” as a conditional question. If yes then additional questions are displayed for the measurements to be entered. These must be setup in JRNI Admin Portal first however questions can be retrieved via the API and answers are updated in Add Basket API call for the Customer front end journey integration.

 

curl --location --request POST 'https://somecustomer.com/api/v3/37016/basket/add_item' \
--header 'Accept: application/json' \
--header 'App-id: 4cd9bfe0c44ff458b2bace9f2166cfa50419e5a70d04' \
--header 'Auth-Token: SQEIvn9L2SmEN5uQ98dMLw' \
--header 'Cache-Control: no-cache' \
--header 'Content-Type: application/json' \
--header 'Content-Type: text/plain' \
--data-raw '{
 "entire_basket": "true",
 "service_id": "48394",
 "person_id": "15342",
 "date": "2020-04-08",
 "time": "{{env_time}}",
 "questions":[
 {
 "id": "3",
 "answer": "Repair"
 }
 ]
}'

 

Business Questions (User Defined Fields)

“User Defined fields” allow you to set data against a Company, Service, Event, Resource or Person in JNRI.

These must be setup in JRNI Admin Portal however answers can be updated via the relevant entity Admin API Update call.

Examples:- Return a location specific contact email address or phone number Store the Staff Member’s full name in a single field.

 

curl -X PUT \
https://sblackburn-training.bookingbug.com/api/v1/admin/37000/company \
-H 'Accept: application/json' \
-H 'App-Id: 4cd9bfe0c44ff458b2bace9f2166cfa50419e5a70d04' \
-H 'Auth-Token: H82aWYKgBfVflGpX6zioqQ' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \
-d '{
"embed": null,
"name": "New Parent Name",
"description": "Description of Parent Company",
"extra": {
"businessquestion2_company": "Updated Business Question 2 - Parent Level",
"childcompanybusinessq_cust": "Updated to Business Question - Child Level"
}
}

Referencing External Systems

  • Most entities in the JRNI platform allow for a customer specific reference. eg Company, Person, Customer, which you can link to your system’s reference number.

  • The example to the right shows the response to the GET Company call showing the reference is stored against the company.

  • There are “Find_by_ref” API calls to simplify locating the correct record in JRNI. Using this call will only return the single response with that reference.

 

curl --location --request GET 
'https://customer.jrni..com/api/v3/company/37000' \
RESPONSE
{
 "id": 37003,
 "name": "Amsterdam",
 "description": "Amsterdam Store",
 "address_id": 2,
….
 "ref": "Amsterdam",
 "created_at": "2020-04-07T10:38:47Z",
 "updated_at": "2020-05-29T19:08:26Z",
 .... }

 

curl --location --request GET 
'https://customer.bookingbug.com/api/v3/company/fin
d_by_ref/amsterdam' \

 

For Bookings, use the “Settings” block to add additional bespoke data fields. The Settings block can be passed in Webhook notifications to external systems.

The Settings block can be used in the Add Basket, Basket Checkout or Update Booking calls.

 

"settings": {
"obfuscated_id": "7NfARvcwbV02naAj"
"external_id": "CRM ID",
"update_notes": "extra field for testing",
“blah blah”: “you can name these properties
what you want to”,
“qr_code”: “0123456” 
},

 

curl --location --request POST 
'https://customer..jrni.com/api/v3/37010/basket' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{
 "entire_basket": "true",
 "service_id": "48470",
 "person_id": " ",
 "datetime": "2020-06-05",
 "settings": {
 "salesforce_id": "customer contact id in salesforce",
 "oracle_task_id": "your Oracle Task ID",
 "qr_code": "0123456" 
 }
 }'

 

API Reporting Options (v3)

The Bookings and Client endpoints allow Elastic Search API calls.

The standard payload shown allows you to set your own search criteria on any of the data elements stored in JRNI against the client

Alternatively, event driven reporting can be achieved using JRNI’s webhook / Push API capabilities

 

curl --location --request POST 
'https://sblackburn-training.bookingbug.com/api/v3/admin/search/clie
nt' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{
 "query": {
 "bool":{
 "must":[
 {"match":
 {"name": "Liam"}
 }
 ]
 }
 }
}'

Related articles

Comments

0 comments

Article is closed for comments.

Powered by Zendesk