visbook-api v10.1.5

Visbook API typescript and javascript library

Basic library wrapping requests to Visbook API

Project setup

Library is provided as a ES module, it requres an environment which supports ES modules for development. Typically it is installed via npm:

npm install visbook-api

After which you can import it or its components into your own modules via import statement:

import Visbook from 'visbook-api' //import library class
import Visbook, {Countries} from 'visbook-api' //import library class and a few components

Library source is written on typescript and typescript definitions should be automatically registered by npm. Alternatively you can use visbook-bundled.js from /dist folder, which is a library and its dependencies bundled together in a single module. You can then import it as a module directly on your pages:

<script type="module">
  import Visbook from './js/visbook-bundled.js';
  let visbook = new Visbook('https://ws.visbook.com/api', IDENTITY_ID);
</script>

Which can be more useful if you do not want to install node environment, your environment still have to support ES modules though.

Usage

Currently most of library functionality is making requests to Visbook endpoints and returning a call promise. To start, you need to create an instance of primary library class Visbook, which is a default export from library:

let visbook = new Visbook('https://ws.visbook.com/api', IDENTITY_ID);

Both arguments used in a constructor are required, first argument is a string defining an API url, it should be a valid url pointing to API base, second argument is a web identity id. Web identity id is used to identify your company and should be taken from one of web entities that your company owns. You can use any of your web identities for that, but if that identity will be removed, library will not be able to authenticate, so you should use identity that is unlikely to ever be removed.

After you have created an instance, you can call its base methods to retrieve data. For example to retrieve company information:

visbook.GET_company()
  .then((response)=> { console.log(response) });

Visbook is using Axios library to make requests and returns Axios responses with an extra "result" property which will have reponse data in a specific model, you can also access "data" property to get plain data parsed by Axios.

To retrieve user-related data you need to use a "user" component of Visbook, all its methods except "requestToken" require user to be authenticated. Users are authenticated by sending a verification token to their email via "requestToken" and then validating token via "validateEmailToken":

visbook.SEND_email('user@example.com');
let token = retrieve_token_from_user();
visbook.GET_validationEmail(token);

Successfull response from "GET_validationEmail" means that your customer has been validated, answer will also have a response cookie which will be used to authenticate user in other requests. As soon as your user's browser will have that cookie, you can request other user methods for data:

visbook.GET_user().then((response)=>{ console.log(response) });  //get user's profile
visbook.GET_orders().then((response)=>{ console.log(response) });  //get user's orders
visbook.GET_ordersById(123).then((response)=>{ console.log(response) })  //get specific order;