Introduction and overview of available web services

Need a definition of web services? Try here.

Currently Bertrams offer three web services:

These web services allow you to in a matter of seconds request price and availability information of an item, place orders and should you need to cancel them you can do that as well.

All of the examples shown in this guide use REST (Representational State Transfer) for sending requests to the services, also using SOAP (Simple Object Access Protocol) requests are supported by Bertrams for more information regarding this protocol click here.

In order to use these web services all that is needed is an account with Bertrams and a computer that's connected to the Internet. To make use of the web service it's just a case on entering a web address which tells us the information Bertrams needs to know to complete request required.

For example if the book "Harry Potter & The Deathly Hallows" was required using the P&A (Price and Availability) web service availability information could be obtained and more just by typing in the below web address:

http://panda1.bertrams.com/Panda/PandaHTTPv1_1?ClientID=UserID&ClientPassword=Password&AccountIDType=02&AccountIDValue=12345/1&EAN13=9780747595830

All of the web services follow standards set out by an independent organisation know as "BIC" (Book Industry Communication). Full details of the standards can be found at http://www.bic.org.uk/21/Web-Services/

Each web service usage is broken down into more detail in the following sections.

General Notes

  • For REST requests urls should be well-formed. In particular non-alphanumeric characters, such as (but not limited to) space, ampersand or equals, should be url-encoded.
  • All urls and parameter names are case-sensitive.
  • We do not support encrypting usernames and passwords.
  • All prices/values quoted are in GBP, unless explicitly stated otherwise.
  • Any empty elements may be omitted from the response, so you need to allow for them not being there.
  • EANs sent in requests should not contain any embedded punctuation such as spaces or hyphens.

ClientID and ClientPassword are the same for each webservice, but the AccountID used differs in some services, so see details within the relevant service's description.

  • ClientID - enter your user id for Bertrams' website. If you do not have a website username and password please contact your sales rep.
  • ClientPassword - enter your password for Bertrams' website.

Price and Availability Web Service

As mentioned earlier the P&A service gives visibility of an ISBN's price and availability at Bertrams. This includes the following information:

  • The price.
  • The discount percentage that will be obtained.
  • Height, Depth and Width of the item.
  • Expected Ship date of the item.
  • How many Bertrams has in stock.

Earlier in this guide an example web address was shown for obtaining this information:

http://panda1.bertrams.com/Panda/PandaHTTPv1_1?ClientID=UserID&ClientPassword=Password&AccountIDType=02&AccountIDValue=12345/1&EAN13=9780747595830

The sections of the address that are highlighted will be required:

  • ClientID - enter your user id for Bertrams' website. If you do not have a website username and password please contact your sales rep.
  • ClientPassword - enter your password for Bertrams' website.
  • AccountIDType - enter "02" which means the value below is from a proprietary scheme
  • AccountIDValue - enter the account and branch information of your business so if your account number is 45 and you are based at branch 1 this section of the address will be "45/1". You can find this information on a Bertrams sales invoice or the account details section on Bertrams.com.
  • EAN13 - this is the EAN13 (ISBN13) of the item you wish to request information for, so for this example this was the "Harry Potter" book which has the EAN13 "9780747595830".

After the first P&A request the only thing that will change is the EAN of the item.

Once the request has been submitted a response will be sent back in the form of an XML document to the web browser that invoked orginal request:

		 version='1.0' encoding='UTF-8' ?>>
		 
		<PriceAvailabilityResponse version='1.1'>
		  
		    <AccountIdentifier>
		      <IDValue>12345/1IDValue
		      <AccountIDType>02AccountIDType>
		    AccountIdentifier>
		    <CurrencyCode>GBPCurrencyCode>
		    <IssueDateTime>20090109IssueDateTime>
		    <SenderIdentifier>
		      <IDValue>5030670143733IDValue>
		      <SenderIDType>06SenderIDType>
		    SenderIdentifier>
		  
		  <ProductPriceAvailability>
		    9780747595830
		    33
		    198
		    <SupplierPriceAvailability>
		      <DiscountPercent>35.00DiscountPercent>
		      <ExpectedShipDate>20090120ExpectedShipDate>
		      <InStock>01InStock>
		      <PackQuantity>32PackQuantity>
		      <ProductAvailability>21ProductAvailability>
		      <RetailPrice>
		        <CurrencyCode>GBPCurrencyCode>
		        <PriceAmount>8.99PriceAmount>
		      RetailPrice>
		      <SupplyQuantity>99SupplyQuantity>
		    SupplierPriceAvailability>
		    <UnitWeight>407UnitWeight>
		    129
		  ProductPriceAvailability>
		PriceAvailabilityResponse>

 

When the response has been received and following the XML schema supplied by BIC, processing can start on XML elements that have been returned. Such as:

	99

Represents how much stock is currently held of that particular item.

	8.9935.00

These represent the RRP of the item and what discount will be given for this item.

P&A Notes

  • We support the ability to enquire whether we have a particular quantity in stock. If this is omitted in stock/not in stock is returned.
  • Results are real-time, although a repeat request for the same product within a few seconds will return cached values for that product.
  • The default level of information returned is RRP, stock status (in stock/not in stock/requested quantity check), Onix status code and, if available, dimensions and weight.
  • If you require lead-time (expected delivery date in YYYYMMDD format), authority checking (whether the book is rights restricted, or otherwise blocked to you) or personal discount information you will need contact your sales manager to request activation of these features. This additional information is retrieved direct from our backend systems, so when those are offline this information will not be returned. If you are set up for this information you need to allow for this information being omitted.
  • We do not require PriceAvailabilityRequestNumber to be provided. If it is provided it is only used to reflect back to you, so formatting/values used are up to you.

Ordering Web Service.

The REST based ordering web service allows you to easily order individual lines. We recommend however that you implement the SOAP order message detailed later.

  • Order items from Bertrams' stock range.
  • Order any book in print if your Bertrams' sales rep has enabled your account for Bertrams' "Any Book Service".
  • Backorder items from Bertrams' range.
  • Apply promotions to the order at a header level.
  • All orders placed using this service can be viewed using Bertrams' website.
  • Provides an instant response which includes information such as how many units have been supplied, backordered and/or cancelled for each line.

An example of the URL you would use to place a simple order is shown below:

http://www.bertrams.com/orderResponseWebService/OrderRequestHTTP?ClientID=UserID&ClientPassword=Password&AccountIDType=02&AccountIDValue=12345/1&OrderQuantity=Qty&OrderNumber=Ref&EAN13=9780747595830

  • ClientID - enter your user id for Bertrams' website. If you do not have a website username and password please contact your sales rep.
  • ClientPassword - enter your password for Bertrams' website.
  • AccountIDType - enter "02" which means the value below is from a proprietary scheme
  • AccountIDValue - enter the account and branch information of your business so if your account number is 45 and you are based at branch 1 this section of the address will be "45/1". You can find this information on a Bertrams sales invoice or the account details section on Bertrams.com.
  • OrderQuantity - The amount of the given item to be placed on order.
  • OrderNumber - This reference for use by the customer, this parameter represents a unique identifier for this order.
  • EAN13 - this is the EAN13 (ISBN13) of the item you wish to order, so for this example this was the "Harry Potter" book which has the EAN13 "9780747595830".

Response:

		 version='1.0' encoding='UTF-8' ?>>
		 
		<OrderResponse version='0.9'>
		  
		    <AccountIdentifier>
		      <IDValue>12345/1IDValue
		      <AccountIDType>02AccountIDType>
		    AccountIdentifier>
		    <IssueDateTime>20090109T1110ZIssueDateTime>
		    <OrderStatus>02OrderStatus>
		    <ReferenceCoded>
		      <ReferenceNumber>MyTestOrderReferenceNumber>
		      <ReferenceTypeCode>11ReferenceTypeCode>
		    ReferenceCoded>
		    <ResponseNumber>2780594ResponseNumber>
		    <ResponsePurposeCode>01ResponsePurposeCode>
		    <SenderIdentifier>
		      <IDTypeName>EAN-UCC GLNIDTypeName>
		      <IDValue>5030670143733IDValue>
		      <SenderIDType>06SenderIDType>
		    SenderIdentifier>
		  
		  <ItemDetail>
		    9780747595830
		    <BackorderedQuantity>1BackorderedQuantity>
		    <CanceledQuantity>0CanceledQuantity>
		    <ExpectedShipDate>20090115ExpectedShipDate>
		    <ItemDescription>
		      <TitleDetail>HARRY POTTER AND THE DEATHLY HALLOWSTitleDetail>
		    ItemDescription>
		    <LineNumber>1LineNumber>
		    <OrderLineStatusCoded>
		      <StatusCode>AcceptedBackorderedStatusCode>
		      <StatusCodeType>02StatusCodeType>
		    OrderLineStatusCoded>
		    <OrderQuantity>1OrderQuantity>
		    <PricingDetail>
		      <DiscountPercentage>21.60DiscountPercentage>
		      
		        <CurrencyCode>GBPCurrencyCode>
		        <MonetaryAmount>8.99MonetaryAmount>
		        <PriceQualifierCode>01PriceQualifierCode>
		      
		    PricingDetail>
		    <PricingDetail>
		      
		        <CurrencyCode>GBPCurrencyCode>
		        <MonetaryAmount>7.05MonetaryAmount>
		        <PriceQualifierCode>03PriceQualifierCode>
		      
		    PricingDetail>
		    <PublisherAvailabilityCode>22PublisherAvailabilityCode>
		    <PublishingStatusCode>04PublishingStatusCode>
		    <QuantityShipping>0QuantityShipping>
		    <ReferenceCoded>
		      <ReferenceNumber>MyTestOrderReferenceNumber>
		      <ReferenceTypeCode>12ReferenceTypeCode>
		    ReferenceCoded>
		  ItemDetail>
		OrderResponse>

 

Again using the specification set up by BIC, processing the response can start

	010

The ordering web service does have more functions which is on offer, briefly below this guide will go over some of these functions. In order to see a full list of the functionality this service offers please visit the BIC website.

Fill Terms Code

Using the URL which was shown earlier and adding this parameter into the end it will allow the user to specify how Bertrams will proceed with the order. Should an item not be in stock the order action of cancelling all items if they are not in stock rather than backordering. Below is a breakdown of what codes can be applied to an order.

  • 01 Fill all or kill all
  • 02 Fill all or backorder all
  • 03 Fill available, kill remainder
  • 04 Fill available, kill remainder unless not yet published
  • 05 Fill available, backorder remainder and ship when complete
  • 06 Fill available, backorder remainder and ship as available

(Please note at the current time (Jan 2009) only fill terms codes 03 and 06 are currently supported by Bertram's)

As an example if the order request was for 20 copies of "Harry Potter & The Deathly Hallows" and it was required that Bertrams was to only supply what it can and cancel the rest the code "03" would be used, the URL for invoking the web service would look something like:

http://www.bertrams.com/orderResponseWebService/OrderRequestHTTP?ClientID=user&ClientPassword=password&AccountIDType=02&AccountIDValue=12345/1&OrderQuantity=20&OrderNumber=123465789&EAN13=9780747532743&FillTermsCode=03

	1505

As shown above in the response if Bertrams only had 15 in stock these are going to be shipped and the other 5 have been cancelled rather than being placed on backorder.

Reference Coded (Promotion codes)

Another important feature of the ordering web service is the ability to apply promotion codes to the order that is being placed. To do the web service needs to know that reference code in use is a promotion code and then specify what the code is (other codes can be applied, please see BIC for these). Visiting Bertram's website will give a list of what promotions are available for a given customer. You can apply a promotion code by adding &ReferenceTypeCode=17 to the URL, this specifies that the reference number you are about to add will be a promotion code. Then add the promotion code to the URL, &ReferenceNumber=321 where 321 is the promotion number.

A list of promotions can be obtained by logging onto Bertrams.com and clicking on "Promotion Explorer"

You must make sure that the promotion code is correct, if the promotion code is not valid the order will still be placed. In particular note that the codes are numeric, do not include any text with them.

An example of an URL with the promotion codes present is shown below:

http://www.bertrams.com/orderResponseWebService/OrderRequestHTTP?ClientID=user&ClientPassword=password&AccountIDType=02&AccountIDValue=12345/1&OrderQuantity=20&OrderNumber=123465789&EAN13=9781904994367&FillTermsCode=03&ReferenceTypeCode=17&ReferenceNumber=10340

As shown you can combine functions together, so you can apply a promotion and a fill terms code as well.

Order Cancellation Service

This web service gives the user the ability to cancel order lines, however order lines cannot be cancelled in the following circumstances:

  • They are in the process of being picked.
  • They are in the process of being supplied.
  • They have been cancelled. (some lines will get cancelled at the time of order)
  • They are a special order and the order has been placed with the supplier

URL to use for invoking the service:

http://www.bertrams.com/BICWSOrderCancellationv1_0/OrderCancellationHTTP?ClientID=userID&ClientPassword=password&AccountIDType=02&AccountIDValue=12345&BuyersOrderNumber=orderHeaderRef&RequestType=02&BuyersOrderLineNumber=orderLineRef&ProductIDType=productType&ProductIDValue=productID

Using the above URL the following parameters must be completed:

  • ClientID - enter your user id for Bertrams' website. If you do not have a website username and password please contact your sales rep.
  • ClientPassword - enter your password for Bertrams' website.
  • AccountIDType - enter "02" if you are sending your account number, which means the value below is from a proprietary scheme. If you are sending SAN instead use "07".
  • AccountIDValue - enter your account/San number e.g. 12345. You can find this information on a Bertrams sales invoice or the account details section on Bertrams.com. Note: this webservice should not have the branch number added
  • RequestType - '02' this is the only type bertrams support currently, which is to cancel one line of an order.
  • BuyersOrderNumber - order header reference (known as Customer Ref/Your PO Ref when in the order tracker on bertrams.com).
  • BuyersOrderLineNumber - the line reference for the line to be cancelled (known as Order Ref when in the order tracker on bertrams.com).
  • ProductIDType - type of product ID that will be used, "03" is for EAN13.
  • ProductIDValue - is the id for the item to be cancelled, for example for EAN13 "9781844212828".

A response from the cancellation service is shown below.

		 version='1.0' ?>>
		 
		<OrderCancellationResponse>
		  
		    <AccountIdentifier>
		      <IDValue>12345IDValue
		      <AccountIDType>02AccountIDType>
		    AccountIdentifier>
		    <IssueDateTime>20090109IssueDateTime>
		    44914
		    <ReferenceCoded>
		      <ReferenceDateTime>20090109ReferenceDateTime>
		      <ReferenceNumber />
		      <ReferenceTypeCode>01ReferenceTypeCode>
		    ReferenceCoded>
		    <ReferenceCoded>
		      <ReferenceNumber>CANTEST2ReferenceNumber>
		      <ReferenceTypeCode>11ReferenceTypeCode>
		    ReferenceCoded>
		    <SenderIdentifier>
		      <IDTypeName>Company NameIDTypeName>
		      <IDValue>Bertram GroupIDValue>
		      <SenderIDType>02SenderIDType>
		    SenderIdentifier>
		  
		  <ItemDetail>
		    9780752224220
		    <CancelledQuantity>2CancelledQuantity>
		    <ItemDescription />
		    <LineNumber>1LineNumber>
		    <ReferenceCoded>
		      <ReferenceNumber>CANTEST2ReferenceNumber>
		      <ReferenceTypeCode>11ReferenceTypeCode>
		    ReferenceCoded>
		    <ReferenceCoded>
		      <ReferenceNumber>CANTESTLINE1ReferenceNumber>
		      <ReferenceTypeCode>12ReferenceTypeCode>
		    ReferenceCoded>
		    <ReferenceCoded>
		      <ReferenceNumber>1ReferenceNumber>
		      <ReferenceTypeCode>13ReferenceTypeCode>
		    ReferenceCoded>
		    <ResponseCoded>
		      <ResponseType>21ResponseType>
		      <ResponseTypeDescription />
		    ResponseCoded>
		  ItemDetail>
		OrderCancellationResponse>

 

Order Cancellation Notes

  • For us to be able to properly locate your order, you must include both an order line and an order header reference.
  • All orders matching the provided EAN, order line and order header references will be fully cancelled if possible.

Using SOAP for web services (Advanced)

The examples of using these web services so far have all been using REST (Representational State Transfer) there is an alternative to using REST when it comes to web services. SOAP (Simple Object Access Protocol) is an XML based protocol for accessing web services.

Why would you want to use SOAP?

SOAP requests are more secure, so for web services requests where passwords are being exchanged it's not always desirable for these to be passed in the URL.

Because SOAP uses XML to communicate it allows for more complex request information, this means when it comes to using Bertrams' web services you could place an order for multiple lines or get price and availability information on several books with one request. This could potentially reduce traffic/ processing when it comes to large orders as they can be placed in one request, rather than many separate requests. Also from an account administration point of view it will be easier to manage your account if you bulk up orders where possible.

For a greater detail into SOAP please visit the W3C website and/or Emerging Technology Briefs: SOAP


For example code in various programming languages please visit our Google code site :

http://code.google.com/p/bicws/

Testing Implementations of Web Services.

Bertram's offer a version of all the services where you can safely test the entire web services suite without placing/cancelling any live orders. Below are the URLs to these services.

REST Services:

P&A : /Panda/PandaHTTPv1_1

Order Cancellation : /BICWSOrderCancellationv1_0/OrderCancellationHTTP

Ordering Service : /orderResponseWebService/OrderRequestHTTP

SOAP Service endpoints:

P&A : /Panda/services/portSOAP

Order Cancellation : /BICWSOrderCancellationv1_0/services/portRequest

Order Service : /orderResponseWebService/services/portRequest

Please note you may need to speak to your sales rep to get a user account set up for these test systems.

Live URLS.

Below are the URLs to these services on the live systems. Do not use these for testing purposes.

REST Services:

P&A : http://panda1.bertrams.com/Panda/PandaHTTPv1_1

Order Cancellation : http://www.bertrams.com/BICWSOrderCancellationv1_0/OrderCancellationHTTP

Ordering Service : http://www.bertrams.com/orderResponseWebService/OrderRequestHTTP

SOAP Service endpoints:

P&A : http://panda1.bertrams.com/Panda/services/portSOAP

Order Cancellation : http://www.bertrams.com/BICWSOrderCancellationv1_0/services/portRequest

Order Service : http://www.bertrams.com/orderResponseWebService/services/portRequest

You just need a username and password for www.bertrams.com to use these.