Introductie Webservices

Text only available in english

The 2BA Webservices are elementary, lightweight and fast services to allow your systems to integrate with the 2BA database. We offer services to search our database, retrieve product- or article details and services to, for example, download your selection profiles automatically. Our webservice is not intended for bulk downloads, it is intended to update a targeted number of articles quickly. For bulk downloads we recommend direct downloads or the use of 2BA selection profiles.

We offer our services via JSON (Rest services) and SOAP (XML service). The advantages of JSON in comparison to SOAP are, among others, reduced overhead and simplicity. For both JSON and SOAP services, most development environments either offer libraries or have the support built-in.  

Access

An application (the client) wishing to communicate with the services requires a ClientId and accompanying ClientSecret. Each application requires its own ClientId. The ClientId and secret of the application are used in conjunction with the username and password during authentication. With the ClientId name we can identfy the application or organisation who uses our webservices. Your software might already have a ClientId and secret in use, please contact your software partner.

If you want to use Webservices you will need a clientid/secret and a 2BA username/password.

Registered 2BA clients can request a ClientId and ClientSecret for use with 2BA webservice via email: Request ClientId and ClientSecret or this form.

Security

To secure our Webservices, we use the open standard OAuth2. In a nutshell, this means that a previously acquired “accesstoken” is sent in an HTTP-header when invoking the service. The authentication can be built manually, but there are plenty of libraries available for this purpose.

View the code examples for authorizing and invoking the Webservices: Example 1: Resource Owner Password Credentials Grant and Example 2: Authorization Code

Structure

The structure of a service URL is: http(s)://api.2ba.nl/<major versionnumber>/<protocol>/<servicename>/<function>?<parameters>
Example: https://api.2ba.nl/1/json/Product/Search?query=kabelgoot

Versioning

The versioning is based on “semantic versioning“. This means that there will be no breaking changes within each major version number; the endpoint remains the same. For more information, see the changelog. 

Current Service Endpoints and SOAP WSDL

The service endpoint is constructed with only the major version number in it. E.g.: https://api.2ba.nl/1/json/Product/Search

Example

To give you an impression of the API, we have provided a small C# code sample in which the function DetailsByGLNAndTradeItemId from the Product service is invoked via JSON.

var postData = string.Format("?gln={0}&tradeItemId={1}", item.SupplierGLN, item.SuppliersTradeItemId);
var requestUri =  "/json/Product/DetailsByGLNAndTradeItemId" + postData;
var request = (HttpWebRequest)WebRequest.Create(Settings.Default.ApiUrl + requestUri);

request.Method = "GET";
request.Headers.Add("Authorization", "Bearer " + AuthorisationService.CurrentAuthorisation.AccessToken);

var responseStream = request.GetResponse().GetResponseStream();
var reader = new StreamReader(responseStream);
var data = reader.ReadToEnd();

var jobj = JObject.Parse(data);
item.ManufacturerName = (string)jobj["Manufacture"];
item.ManufacturerTradeItemId = (string)jobj["Productcode"];// ...