Bertram Web Services Guide

learningsnortSecurity

Nov 3, 2013 (3 years and 10 months ago)

51 views

Bertram Web Services Guide































Overview of available services


Need a definition of web services? Go
here
.


Currently
Bertram
B
ooks offer three web services:




Price and Av
ailability.



Order Request and Response.



Order Cancellation.


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.


In order to

use these web services all
that is

need
ed

is an account with Bertram’s and a computer that’s
connected to the
I
nternet. To make use of the web service
it’s

just a case on entering a web
address which

tells us the information
Bertram’s
needs

to know to
com
plete

request

required
.



For example if
the

stock of
‘Harry Potter & The Philosophers Stone’
was required
using the P&A (Price
and Availability) web service

this information could be obtained

and more just by typing in the below web
address:


http://bert
rams.com/Panda/PandaHTTP?ClientID=UserID&ClientPassword=Password&AccountIDType=0
2&AccountIDValue=
12345
/1&EAN13= 9780747595830


All of the web services follow standards set out by an independent organisation know as ‘BIC’ (
B
ook
I
ndustry
C
ommunication). Full

details of the standards can be found at
http://www.bic.org.uk/ecommerce
-
webservices.html


Each web service usage is

broken down into more detail
in the following sections.























Price and Availability

Web Service


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




The Price.



The discount percentage
that will be obtained.



Height, De
pth and Width of the item.



Expected Ship date of the book.



How many Bertram’s has in stock.


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


http://bertrams.com/Panda/PandaHTTP?ClientID=
UserID
&ClientPassword=
Password
&AccountIDType=
0
2
&AccountIDValue=
12345/1
&EAN13=
9780747595830


The sections of the address that are highlighted
will
be
require
d:


ClientID
-

enter the

user id wh
ich you have been supplied with by your Bertram’s sales rep.

ClientPassword
-

entry the

passw
ord which you have
been given by your Bertram’s sales rep.
.

AccountIDType
-


this is

the
type of account you have
generally

this remains as ‘02’

AccountIDValue
-

enter

the account and branch information
of your business
so if your account number is
45 and

your based at branch one this section of the address will be ‘45/1’
. You can find this information on
a Bertrams’s sales invoice or the account details section on Bertrams.com.

EAN13


this is the EAN13

(ISBN13)

of the item you wish to request information

of, so for this example
this was the
“H
arry
P
otter


book which has the EAN13

9780747595830
’.


A
fter

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 for
m of an XML document to the
web browser that invoked orginal request:


<?xml version='1.0' encoding='UTF
-
8' ?>


<PriceAvailabilityResponse version="1.1">


<header>


<accountIdentifier>


<IDValue>909088/1</IDValue>


<accountIDType>02<
/accountIDType>


</accountIdentifier>


<currencyCode>GBP</currencyCode>


<issueDateTime>20080828</issueDateTime>


<senderIdentifier>


<IDValue>5030670143733</IDValue>


<senderIDType>06</senderIDType>


</senderIdentifi
er>


</header>


<productPriceAvailability>


<PriceAvailabilityResponseProduct>


<EAN13>9780563384311</EAN13>


<depth>29</depth>


<height>283</height>


<supplierPriceAvailability>


<discountPercent>35.00</disc
ountPercent>


<expectedShipDate>20080903</expectedShipDate>


<inStock>01</inStock>


<packQuantity>10</packQuantity>


<productAvailability>31</productAvailability>


<retailPrice>


<currencyCode>GBP</cu
rrencyCode>


<priceAmount>16.99</priceAmount>


</retailPrice>


<supplyQuantity>99</supplyQuantity>


</supplierPriceAvailability>


<unitWeight>1170</unitWeight>


<width>223</width>


</PriceAvailabilityR
esponseProduct>


</productPriceAvailability>


</PriceAvailabilityResponse>



When the response has been
received
and following the XML schema supplied by

BIC
, processing c
an start

on XML

elements that have been returned.
Such as:



<supplyQuantity>99</supplyQuantity>


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


<priceAmount>16.99</priceAmount>

<discountPercent>35.00</discountPercent>


This

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
































Ordering

Web
S
ervice.


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




Order items from
Bertram’s

stock range.



Order any book in print if your Bertram’s sales rep has enabled your account for Bertram’s “Any
Book Service”.



Backorder items from
Bertram’s

range.



Apply promotions to
the

order

at a header level.



All orders placed using this service can be viewed using
Bertram’s

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 t
he URL you would

use

to place a simple order
is shown below:


http://bertrams.com/orderResponseWebService/OrderRequestHTTP?ClientID=
UserID
&ClientPassword=
P
assword
&AccountIDType=
02
&AccountIDValue=
12345/1
&OrderQuantity=
Q
ty
&OrderNumber=
R
ef
&EA
N13=
9780747595830


ClientID
-

enter the user id which you
Bertram’s has supllied.

ClientPassword
-

password for the above account.

AccountIDType

-

this is type of account.

AccountIDValue
-

enter the account and branch information of
the

business so if
the

account number

is 45
and
the business is

based at branch
‘1’

this section of the address will be ‘45/1’
.

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 identifie
r for this
order.

EAN13


this is the EAN13 of the item
where the information is required
for this example this was the
Harry

P
otter book which has the EAN13 ‘9780747595830’.


Response:


<?xml version='1.0' encoding='UTF
-
8' ?>


<OrderResponse version="0.
9">


<Header>


<AccountIdentifier>


<IDValue>909088/1</IDValue>


<AccountIDType>02</AccountIDType>


</AccountIdentifier>


<IssueDateTime>20080903T0927Z</IssueDateTime>


<OrderStatus>02</OrderStatus>


<ResponseNumbe
r>435080</ResponseNumber>


<ResponsePurposeCode>02</ResponsePurposeCode>


<SenderIdentifier>


<IDTypeName>EAN
-
UCC GLN</IDTypeName>


<IDValue>5030670143733</IDValue>


<SenderIDType>06</SenderIDType>


</SenderIdentifier>



</Header>


<ItemDetail>


<EAN13>9780091767952</EAN13>


<BackorderedQuantity>5</BackorderedQuantity>


<CanceledQuantity>0</CanceledQuantity>


<ExpectedShipDate>20080909</ExpectedShipDate>


<ItemDescription>


<TitleDetai
l>Bens Big Book Of Cars</TitleDetail>


</ItemDescription>


<LineNumber>1</LineNumber>


<OrderLineStatusCoded>


<StatusCode>AcceptedBackordered</StatusCode>


<StatusCodeType>02</StatusCodeType>


</OrderLineStatusCoded>



<OrderQuantity>5</OrderQuantity>


<PricingDetail>


<DiscountPercentage>35.00</DiscountPercentage>


<Price>


<CurrencyCode>GBP</CurrencyCode>


<MonetaryAmount>8.99</MonetaryAmount>


<PriceQualifierCode>01</Pri
ceQualifierCode>


</Price>


</PricingDetail>


<PricingDetail>


<Price>


<CurrencyCode>GBP</CurrencyCode>


<MonetaryAmount>5.84</MonetaryAmount>


<PriceQualifierCode>03</PriceQualifierCode>


</Price>


</PricingDetail>


<PublisherAvailabilityCode>30</PublisherAvailabilityCode>


<PublishingStatusCode>04</PublishingStatusCode>


<QuantityShipping>0</QuantityShipping>


<ReferenceCoded>


<ReferenceNumber>114911</ReferenceNumb
er>


<ReferenceTypeCode>12</ReferenceTypeCode>


</ReferenceCoded>


</ItemDetail>


</OrderResponse>


Again using the specification set up by
BIC
, process
ing t
he response can start



<QuantityShipping>0</QuantityShipping>

<BackorderedQuantity>5</BackorderedQuantity>

<CanceledQuantity>0</CanceledQuantity>


<PricingDetail>



<Price>



<CurrencyCode>GBP</CurrencyCode>



<MonetaryAmount>5.84</MonetaryAmount>




<PriceQualifierCode>03</PriceQualifierCode>



</Price>

</PricingDetail>













The ordering web service does have more functions it can offer, briefly below this guide will go over
some
of
these functions. In order to see a full list of the functi
onality
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 us
er

to
specify how Bertram’s will proceed with
the
order
.

S
hould 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 avai
lable


(Please note at the time of writing this guide (09/08)
only
fill terms codes 03 and 06 are currently
supported)


As an example
if the order request was for
20 copies of ‘Harry Potter & The Philosophers Stone’ and
it was
required that

Bertram’s
was
t
o 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://bertrams.com/orderResponseWebService/OrderRequestHTTP?ClientID=user&ClientPassword=pass
word&AccountIDType=02&
AccountIDValue=12345/1&OrderQuantity=20&OrderNumber=123465789&
EAN13= 9780747532743
&FillTermsCode=03


<BackorderedQuantity>0</BackorderedQuantity>

<CanceledQuantity>5</CanceledQuantity>

<QuantityShipping>15</QuantityShipping>


As shown above in the response

as Bertram’s only had 15 in stock so 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
t
he 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 refere
nce 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 Explore
r”


You must make sure that the promotion code is correct, if the promotion code is not valid the order will still
be placed.





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



http://bertrams.com/orderResponseWebService/OrderReque
stHTTP?ClientID=user&ClientPassword=pass
word&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 yo
u 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 o
rder Lines
cannot

be cancelled if
they are
at
the following status:




In the process of bein
g picked.



In the process of being supplied.



If they have been cancelled. (some lines will get cancelled at the time of order)



URL to use for invoking the service:


http://bertrams.com/BICWSOrderCancellation/OrderCancellationH
TTP?ClientID=userID&ClientPassword
=password&AccountIDType=02&AccountIDValue=909088&BuyersOrderNumber=lineRef&RequestType
=02&BuyersOrderLineNumber=lineNumber&ProductIDType=productType&ProductIDValue=productID



Using the above URL the following parameters
must be completed:


ClientID: The login
which has been supplied by Bertram’s.

ClientPassword:
The password associated with this account

AccountIDType:
Account type
, e.g. 02

AccountIDValue:
A
ccount
/San

number e.8. 12345


BuyersOrderNumber: order line refer
ence (known as customer ref when in the order tracker
o
n
bertrams.com)

RequestType:

02




this is the only type bertrams support currently
, which is to cancel one line of an order.

BuyersOrderLineNumber



the line number where cancellation is required.

Pro
ductIDType:

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, this order was for three lines. Note

that all the
lines details have been returned
, and that the second line of the order which matched the EAN13 supplied
in the above example URL has been cancelled.



<?xml version='1.0' ?> <OrderCancellationResponse>


<Header>


<AccountIdentifier>


<IDValue>12345</IDValue>


<AccountIDType>02</AccountIDType>


</AccountIdentifier>


<IssueDateTime>20080930</IssueDateTime>


<OrderCancellationResponseNumber>44721</OrderCancellationResponseNumber>


<ReferenceCoded>



<ReferenceDateTime>20080930</ReferenceDateTime>


<ReferenceNumber/>


<ReferenceTypeCode>01</ReferenceTypeCode>


</ReferenceCoded>


<ReferenceCoded>


<ReferenceNumber>test34</ReferenceNumber>


<ReferenceTypeCode>11</
ReferenceTypeCode>


</ReferenceCoded>


<SenderIdentifier>


<IDTypeName>Company Name</IDTypeName>


<IDValue>Bertram Group</IDValue>


<SenderIDType>02</SenderIDType>


</SenderIdentifier>


</Header>


<ItemDetail>



<EAN13>9780751312812</EAN13>


<CancelledQuantity>0</CancelledQuantity>


<ItemDescription/>


<LineNumber>1</LineNumber>


<ReferenceCoded>


<ReferenceNumber>test34</ReferenceNumber>


<ReferenceTypeCode>11</ReferenceTypeCod
e>


</ReferenceCoded>


<ReferenceCoded>


<ReferenceNumber>3</ReferenceNumber>


<ReferenceTypeCode>12</ReferenceTypeCode>


</ReferenceCoded>


<ReferenceCoded>


<ReferenceNumber>1</ReferenceNumber>


<ReferenceT
ypeCode>13</ReferenceTypeCode>


</ReferenceCoded>


<ResponseCoded>


<ResponseType>13</ResponseType>


<ResponseTypeDescription/>


</ResponseCoded>


</ItemDetail>


<ItemDetail>


<EAN13>9781844212828</EAN13>


<Canc
elledQuantity>22</CancelledQuantity>


<ItemDescription/>


<LineNumber>2</LineNumber>


<ReferenceCoded>


<ReferenceNumber>test34</ReferenceNumber>


<ReferenceTypeCode>11</ReferenceTypeCode>


</ReferenceCoded>


<Referen
ceCoded>


<ReferenceNumber>2</ReferenceNumber>


<ReferenceTypeCode>12</ReferenceTypeCode>


</ReferenceCoded>


<ReferenceCoded>


<ReferenceNumber>2</ReferenceNumber>


<ReferenceTypeCode>13</ReferenceTypeCode>


</Re
ferenceCoded>


<ResponseCoded>


<ResponseType>21</ResponseType>


<ResponseTypeDescription/>


</ResponseCoded>


</ItemDetail>


<ItemDetail>


<EAN13>9781861268389</EAN13>


<CancelledQuantity>0</CancelledQuantity>



<ItemDescription/>


<LineNumber>3</LineNumber>


<ReferenceCoded>


<ReferenceNumber>test34</ReferenceNumber>


<ReferenceTypeCode>11</ReferenceTypeCode>


</ReferenceCoded>


<ReferenceCoded>


<ReferenceNumber>1</Refer
enceNumber>


<ReferenceTypeCode>12</ReferenceTypeCode>


</ReferenceCoded>


<ReferenceCoded>


<ReferenceNumber>3</ReferenceNumber>


<ReferenceTypeCode>13</ReferenceTypeCode>


</ReferenceCoded>


<ResponseCoded>



<ResponseType>13</ResponseType>


<ResponseTypeDescription/>


</ResponseCoded>


</ItemDetail>


</OrderCancellationResponse>































Using SOAP for web services.
(Advanced)


The examples of using these web services
so f
ar
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 request
s are

more secure, so for web services

requests
where passwords are being exchanged

it’s

not
always desirable for

these to be parsed into
the URL
.

In generic terms here
are

a few
reasons

why
it’s

good
to use SOAP:

Advantages



Using SOAP over
HTT
P

allows for easier communicatio
n through proxies and firewalls.



SOAP is platform independent.



SOAP is language independent.



SOAP is simple and extensible.

B
ecause SOAP uses XML to communicate it allows for more complex request information, this means
when

it comes to using Bertram’s web services you
could place an order for multiple lines

or get price and
availability information on se
ver
al books with one request
. This could potentially reduce traffic/ processing
when it comes to large orders as they can b
e 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/cancellin
g any live orders. Below are the URLs to these services.



REST Services:


Panda :
http://beta.bertrams.com/Panda/PandaHTTP

Order Cancellation :
http://beta.bertrams.com/BICWSOrderCancellation/OrderCancellationHTTP

Ordering Service :
http://beta.bertrams.com/orderResponseWebService/Or
derRequestHTTP


SOAP Service endpoints:


Panda :
http://beta.bertrams.com/Panda/services/portSOAP

Order Cancellation :
http://beta.bertrams.com/BICWSOrderCancellation/services/portRequest

Order Service :
http://beta.bertrams.com/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.