Documents

Get started

Overview

Welcome to the BoB Developer Toolkit. These tools make it possible to build solutions that automate the use of BoB in third-party interfaces. The solutions presented below are designed to adapt to different use cases and levels of integration, in order to achieve the appropriate solution for each context. Currently we have 2 integration solutions:

1. API REST
2. Widget tag

The API REST option allows for total customization of the user experience. The Widget tag option is a faster integration option, by inserting a javascript script in the integrator source code, with the counterpart of offering less customization. Both solutions can be combined to achieve the desired solution.

Below we offer documentation to use the desired tools.

Before you can use any of these solutions, you must obtain your access credentials, as explained.

Get your credentials

First, you need to contact us here to get your login credentials.

Our certification process is very agile, and once your application is approved, you will have access to staging environments so that you can check that all your integrations work correctly.

Using your credentials

Once you have obtained your credentials, you can see how to Authenticate in the API authentication section

API REST

Introduction

Our API REST is designed to be able to create third-party applications that can show the availability of BoB Services at different locations and times, then create Service Orders that adapt to these needs and contexts, under full customization of the user experience that developers want to design at their applications.

You will be able to use 2 main groups of requests to define an Order flow in BoB. On the one hand, you can use the query requests, the purpose of which is to know if a BoB service is operable under certain circumstances, and on the other hand, you can use the creation requests, to be able to create and confirm the orders in the BoB.

API Authentication

You can see the instructions in our API Explorer sections

https://developer.api.bob.io/#section/Authentication

https://developer.api.bob.io/#operation/alive

API Workflows

The API design has been built under REST specifications, with the philosophy that you can use BoB resources in the chronological order in which you need them, according to your workflow.

Under this premise, we can differentiate 2 main cases of data use:

A) Use of query requests: Requests of this type can be used in the chronological order that the developer defines appropriate. They are resources intended to respond if a BoB Service is operable according to a single context, such as the location of the Service, pick-up and delivery times, products available for a flight, availability by Area, etc.

These requests may or may not be used prior to requesting a purchase Order. Its use is not mandatory, but it is recommended to know if the future Order is going to be successful when it is created. You can see the possible errors when creating an order from the API Explorer section.

B) Use of creation requests: Once we have decided that we want to send a Service Order to BoB because all the conditions of availability of the Service are met, we can use the Order resources enabled for this purpose. The logical way to use the Order resources is, a) first to create an Order, b) second to confirm the previously created Order.

The creation of the Order and its confirmation can be simultaneous or if preferred, delayed in time. The reason for having these 2 steps is to enable asynchronous flows related to payments and the control of their possible errors in the flows of third-party applications.

An important point to keep in mind is that a Service will not be operable until the Order that contains it is not confirmed over the confirmOrder request, available on the Order resource.

By way of illustration, this would be a possible complete flow scheme for creating an Order:

API explorer

You can explore interactively all our API documentation and find specific methods, arguments, error codes, and sample code to build your applications.

Postman collections

We would like to make your integration work easier with our API, so we thought that having an accessible and updated collection of requests in Postman could help you 😇 .

Widget tag

Introduction

Our Widget tag is designed to be able to generate BoB Orders in third-party interfaces without using large development resources. Insert a script in the source code of the page where you want to show BoB or through a tag manager, such as Google Tag Manager, and instantly you will have a complete experience so that your users can hire all the services available in BoB.

Some of the design considerations for the widget have been performance and security, assuring that any external code doesn’t impact your page performance and all the highest security requirements are met after third-party external due diligence of our code.

Here you have a general overview of how the widget works in terms of architecture

Widget testing

This use case is designed to test the BoB Widget. You will be able to place Orders in a fake environment at BoB and you won’t have to access the details of those. If you need the information on how to use it, please refer to the next section Using a BoB developer ID

Widget tag installation

Using a BoB developer ID

If you want to apply to our developer program and you are interested in using our Widget with your own credentials in order to control and access to your users Order purchase details, commission fees, extra custom tools, etc, please, contact us to provide you with developer ID for your Widget tag and more details.

Widget customization

You can pass parameters to the widget to make it easier for your users to fill their data, control its behavior and customize UI. Just add valid parameters on your widget src URL code as standard query params. You can check the next example using informative placeholders.

Example:

<script type="text/javascript" src="https://booking.bob.io/widget/main.js?lang=en&widget-owner=<YOUR-BOB-ID>&widget-airlines=<AIRLINE1-CODE>&widget-airlines=<AIRLINE2-CODE>&affiliate=<AFFILIATE-NAME>&promocode=<YOUR-PROMOCODE>&marketer=<MARKETER-NAME>&bookername=<YOUR-NAME>&bookersurname=<YOUR-SURNAME>" id="bob-widget-script"></script>

Here you have a list of possible parameters:

Color code for BoB development roadmap:

Under planification -> Planned -> Work in progress -> Active

To be able to use Widget customization, please contact us to give you full support.

Interact with the widget

To trigger some actions in the widget it exposes some methods to be called withing your page.

Due to the asyncronous nature of the widget these methods are available only when the widget has loaded, to avoid errors an to ensure that no information is lost you must pass that method calls to the widget ready event callback.

    document.addEventListener('bobWidget.ready', () => {
      BoBWidget.setBookerPersonalInfo({...});
      BoBWidget.sendFlightList([...]);
    });

Send Flight List

To send a list of flights instead of a single one you can use this method.

BoBWidget.sendFlightList([
  { segments: ['MAD','BCN'], flights: [{ number: 'AL1234', date: '2022-05-27T07:51:57.209Z' }]},
  { segments: ['MAD','BCN'], flights: [{ number: 'AL1000', date: '2022-05-28T07:51:57.209Z' }]},
  { segments: ['MAD','BCN','IBZ'], flights: [{ number: 'AL3041', date: '2022-05-29T07:51:57.209Z' }, { number: 'AL2000', date: '2022-05-29T07:51:57.209Z' }]},
])

The widget will parse that list and select the first eligible flight to pass it to our booking process.

The dates must be in  ISO 8601 calendar date extended format in UTC (YYYY-MM-DDTHH:mm:ss.sssZ) or short date format YYYY-MM-DD.

Send Booker info to the widget

In order to send booker info to pre-populate those fields in the widget and avoid this work being done by the session user, integrators can pass that data to the widget over a secure connection.

For that case, it is necessary to use a post method in order to create a direct communication from the browser to the widget, avoiding then privacy and security issues.

The method should be used after the widget script is loaded.

Here you have the code to run on your browser in order to achieve this connection:

BoBWidget.setBookerPersonalInfo({
  pickupAddress: "...",
  pickupAddressExtra: "...",
  name: "...",
  surname: "...",
  email: "...",
});

As a developer and depending on the use of some of the parameters exposed above, you can send information to the widget in order to control the UX and screens that a user will see. Depending on this data the user flow can be modified as the following chart indicates

Gather widget events

The widget allows the gathering of some information about its behavior by the emission of events. The events that the widget creates and its description are:

• show -> there was a trigger to open the widget
• ready -> the widget is loaded
• hide -> there was a trigger to close the widget
• orderCreated -> the user finished the widget flow for and a Order was created
• bookingReady -> the user accept the terms of service and the booking process started.

There is only one way of gathering the info from these events.

Listening to the events the widget emits

In order to be able to track events and data from our widget, we have set a system of events firing on your site (on document). Therefore, you can perform actions when the widget is open, ready closed, and when an order is created

The events fired on the host are:

'bobWidget.show' // on widget Opening
'bobWidget.ready' // on widget Ready
'bobWidget.hide' // on widget Closing
'bobWidget.orderCreated' // when an order is created within the widget
'bobWidget.bookingReady' // on click accept terms of service
'bobWidget.parseFlightList' // the flight list received by the sendFlightList method was parsed and selected the first operable flight

An example of event information sent in each event:

'bobWidget.show': null
'bobWidget.ready': null
'bobWidget.hide': null
'bobWidget.bookingReady': null
'bobWidget.orderCreated': {
  bookingCode: "8FWNXG",
  language: "es",
  numBags: 1,
  orderId: "5f994c73df857d99bd202cfb",
  price: 20,
  type: "checkin",
  isSubsidized: true,
  status: "awaiting"
}
'bobWidget.parseFlightList': {
{
    "flightList": [
        {
            "segments": [
                "MAD",
                "BCN"
            ],
            "flights": [
                {
                    "number": "AL1000",
                    "date": "2022-05-28T07:51:57.209Z"
                }
            ]
        }
    ],
    "flightParams": {
        "from": "MAD",
        "to": "BCN",
        "date": "2022-05-28",
        "flightcode": "AL1000"
    }
}
}

 <script type="text/javascript">
    document.addEventListener('bobWidget.open', () => {
      console.info('Widget - Open');
    });
    document.addEventListener('bobWidget.ready', () => {
      console.info('Widget - Ready');
    });
    document.addEventListener('bobWidget.closed', () => {
      console.info('Widget - Closed');
    });
    document.addEventListener('bobWidget.bookingReady', () => {
      console.info('Widget - Booking ready');
    });
    document.addEventListener('bobWidget.orderCreated', ({ detail }) => {
      console.info('Widget - Order Created', detail);
    });
    document.addEventListener('bobWidget.parseFlightList', ({ detail }) => {
      console.info('Widget - flight list parsed', detail);
    });
  </script>

Open and close widget

By default the widget will be displayed when is loaded, to have more control over its visibility, two methods are exposed in order to control that behavior:

BoBWidget.hide() // hides widget UI 
BoBWidget.show() // shows widget UI 

Use cases

No code integration

For quick access to your users, we recommend the use of our widget tag. This can be made following the instructions on the section related.

Full user experience customization

We recommend the use of our API REST.

Glossary

A

Area is referred as the set of operable postal codes for pick-up and delivery that BoB operates for its Services.

Authentication is referred as the need to validate that you have a registered user ID for developer purposes as using private resources for the API or Widget.

Authorization is referred to as the permissions you have been granted over your user ID for developing specific requests.

G

Google Tag Manager or GTM is a Google service that allows managing from an integrated and centralized interface, third-party code on your source code.

O

Order is referred as the set of Services and Products that a user books at the same moment, under a specific price. An Order can be composed with 1 or more Services.

P

Postman is a software development tool. It enables people to test calls to APIs. You can find more documentation on its webpage

Product is referred as a specific action or good with its own characteristics that a user can buy, defined by a unique SKU. Products at BoB are delivered to users under specific conditions, defined on the Services entity. You can check the list of the available Products at its API Explorer response schema. Current available Products are:

• checkin
• transfer
• cityDelivery
• skipBaggegeClaim

R

Resource is referred as a set of methods related to one specific object schema.

S

Service is referred as the operational instructions BoB needs to deliver a Product or Products to a user.

• Airport delivery
• Check-in
• City delivery
• Skip baggage claim

T

Tag Manager is referred as a tool to manage tags. See Google Tag Manager as an example.

Tag is referred as a third-party script that invokes external functionalities of your code.

W

Widget is referred as a third-party application that runs on your interface using a tag inserted in your code.