BHN WebPos Service Specifications

______________________________________________
Blackhawk BOSS Retailer Service Specification

Version Number: 1.6
Confidential
Blackhawk Network
______________________________________________
Revision History
Date
Revision Number
05/19/10
06/02/10
06/06/10
06/12/2010
06/16/2010
0.1
1.0
1.1
1.2
1.3
08/03/2010
1.4
08/06/2010
1.5
11/04/2010
1.6
Confidential
Description
First Draft
Reviewed with Biju B
Updates after discussion with webPos team
Modified the URL and Product search
Modmodified with response codes and description, updated Get
Store Detail by division Id with division id in response
MOIInclude partner code and partner type in request and
response for all services
Making the partner code and partner type mandatory for
All responses.
Updating the spec with Pagination details
Author
Dileep Prasad
Dileep Prasad
Dileep Prasad
Dileep Prasad
Dileep Prasad
Dileep Prasad
Dileep Prasad
Dileep Prasad
Blackhawk Network
Blackhawk Network
Version: 1.6
Date: 11/04/2010
Table of Contents
1.
Overview..........................................................................................................................................................4
2.
Using BOSS REST Retailer Services API.......................................................................................4

2.1
Get division List API................................................................................................. 4
2.2
Get division Detail by divisionId API.........................................................................6
2.3
Get Store List by division id API...............................................................................9
2.4
Get Store Detail by division Id and store id API....................................................11
2.5
Get UPC List API..................................................................................................... 13
2.6
Get UPC Detail API................................................................................................. 15
3.
Status info description......................................................................................................................................17
4.
Exception / Error response...............................................................................................................................18
5.
Response Code and Description......................................................................................................................18
Confidential
Blackhawk Network
Blackhawk Network
1.
Version: 1.6
Date: 11/04/2010
Overview
This document establishes the standard for message exchange by clients of the BOSS
web services provided by Blackhawk. This specification is based on use of the REST
(Representational State Transfer) API. This document describes partner and store
details look up services provided by BOSS to support the webPos migration project.
The audiences for this document from the client of these services are
2.
Application Developers,
System Architects
Network Engineers
Project Managers
Using BOSS REST Retailer Services API
The following describes the retailer service (based on REST API) that BOSS will be
exposing to the internal webPos system. It also describes the Request Message
Format and Response Message Format that the service will support.
2.1
Get division List API
This API method retrieves all the divisions that BOSS system has in its database. The
division details will contain division Id and division name . If the division list is above
the given limit of 500 divisions, the system will send the paginated result. The
pagination will be calculated based on the page number detail that comes through
the request. The total number of records found and the range of records in the
response will be mentioned in the status info tag of the response. The request is in
the form of HTTP Get and the response is in the form of an xml.
The divisions fetch logic currently done in two ways. This is done by passing a
division name or part division name or division id or part of division id search criteria.
If request contains both division name and division id, then division details with both
the above details will be fetched. If one of the request parameter is passed, then the
search will be done on that parameter.
The pagination will be done based on the pagenumber field in the request.
The Pagination will be done using the formula pagenumber * 500. If pagenumber is
not passed in the request , we will take 1 as the default page number.
URL:
http://10.6.10.2:9080/bossServices/outboundservices/getdivisions?name=<division
Name>&id=<division id>&partnerid=<partner Id>&partnertype=<Partner Type
Id>&pagenumber=<Range needed>
URL
http://10.6.10.2:9080/ bossServices/outboundservices/getdivisions
Confidential
Blackhawk Network
Blackhawk Network
Version: 1.6
Date: 11/04/2010
HTTP Method
GET
Authentication Required
False
Request Parameters
Attribut
es
name
Data
Type
String
M/O/
C
O
id
String
partnerid
partnerty
pe
String
String
O
O
pagenum
ber
String
Description
division name or part of the division name for which the
client wants the details
division id or part of the division id for which the client
wants the details
Partner code under which the division falls in
Partner type code
1 - Alliance Partner
3 - Card Partner.
Default is card partner. So if this parameter is not passed
we take it as a card partner call
Range of result looking for .Range is calculated as
pagenumber*500. If pagenumber is not passed in the
request , we will take 1 as the default page number.
*M/O/C = Mandatory/Optional/Conditional
Response Parameters
Attribut
es
Data
Type
Max.
Lengt
h
divisions
M/O/
C
Description
List of divisions. This is mandatory tag and

would be present even if no retailers are
present
division Id
division Name
Will return the partner Id if the request
comes with a partner Id other wise the
partner Id corresponding to the division
code
Will return the partner type id if the request
comes with a partner type id other wise the
partner type corresponding to the division
code
id
name
partneri
d
String
String
String
15
100
20
M
M
M
partnert
ype
String
Confidential
Blackhawk Network
Blackhawk Network
Version: 1.6
Date: 11/04/2010
Sample Request:
http:// 10.6.10.2:9080/bossServices/outboundservices/getdivisions?
name=SFWY&id=00651
d&partnerid=SFY&partnertype=3&pagenumber=1
Sample Response:
<?xml version="1.0" encoding="utf-8" ?>
<response>
<statusinfo>
<status>
<code>STL_000</code>
<description>SUCCESS</description>
<records>
<start>1</start>
<end>500</end>
<total>4000</total>
</records>
</status>
</statusinfo>
<divisions>
<division>
<id>00561</id >
< name>SWFY Stockton SWFY Vons</ name >
<partnerid>SFY</partnerid>
<partnertype>3</ partnertype >
</ division >
< division >
<id>00562</id >
<name>SWFY - Pleasanton</name>
<partnerid>SFY</partnerid>
</ division >
</ divisions>
</response>
2.2
Get division Detail by divisionId API
This API method retrieves all the divisions that BOSS system has with it using the
division Id as the search key. The division details will contain division name, merchant
address, division city, division country , division postal coded, division state . Due to
the restrictions on BOSS side we will be supplying only division name and division
country for the time being. The request is in the form of HTTP Get and the response is
in the form of an xml.
URL:
Confidential
Blackhawk Network
Blackhawk Network
Version: 1.6
Date: 11/04/2010
http://10.6.10.2:9080/bossServices/outboundservices/getdivision? id=<division
Id>&partnerid=<Partner Id>&partnertype=<partner type
id>&pagenumber=<Range needed>
URL
http://10.6.10.2:9080/bossServices/outboundservices/getdivision
HTTP Method
GET
False
Request Parameters
1.Below are the request parameter details for this service
Attribut
es
id
partnerid
partnerty
pe
Data
Type
String
String
String
M/O/
C
M
O
O
pagenum
ber
String
Description
division Id for the desired partner search
Partner Id for the division in the request
Partner type code
3 - Card Partner.
Response Parameters
Attribute
s
Data
Type
Max.
Lengt
h
divisions
name
addrtxt
city
countryco
de
postalcode
stateprovc
ode
partnerid
Confidential
M/O/
C
Description
M
String
String
String
String
100
500
50
5
M
O
0
0
List of divisions. This is mandatory tag

and would be present even if no retailers
are present
Division Name
Division address
Division city
Division Country
String
String
5
5
0
0
Division Zip Code

Division State Code
String
20

Blackhawk Network
Blackhawk Network
partnertyp
e
String
Version: 1.6
Date: 11/04/2010

partner Id corresponding to the division
code
Will return the partner type id if the
request comes with a partner type id
other wise the partner type corresponding
to the division code
Sample Request:
http://10.6.10.2:9080/bossServices/outboundservices/getdivision?
id=00561&partnerid=MACY&partnertype=3&pagenumber=1
Sample Response:
<response>
<statusinfo>
<status>
<records>
<start>1</start>
<end>500</end>
<total>4000</total>
</records>
</status>
</statusinfo>
< divisions>
< division>
<partnerid>MACY</partnerid>
<name>MACY - Stockton</name>
< addrtxt>123, Stockton</ addrtxt >
< city>Stockton</city>
< countrycode >USA</ countrycode >
< postalcode >93456</ postalcode >
<stateprovcode>CA</ stateprovcode >
</ division>
< division>
<id>00561</id >
<partnerid>MACY</partnerid>
<name>SWFY - Pleasanton</name>
< name>MACY - Pleasanton</name>
Confidential
Blackhawk Network
Blackhawk Network
Version: 1.6
Date: 11/04/2010
< addrtxt>123, Pleasanton</ addrtxt >

< city>Pleasanton</ city>
< countrycode>USA</ countrycode >
< postalcode>94588</ postalcode >
< stateprovcode >CA</ stateprovcode >
</ division>
</ divisions >
</response>
2.3
Get Store List by division id API
This API method retrieves all the store details that BOSS system has in it for this
division id in the request. The store details will contain store name and the store
code. If the store list is above the given limit of 500 stores, the system will send the
paginated result. The pagination will be calculated based on the page number detail
that comes through the request. The total number of records found and the range of
records in the response will be mentioned in the status info tag of the response. The
request is in the form of HTTP Get and the response is in the form of an xml.
The pagination will be done based on the pagenumber field in the request.
The Pagination will be done using the formula pagenumber * 500. If pagenumber is
not passed in the request , we will take 1 as the default page number.
URL:
http://10.6.10.2:9080/bossServices/outboundservices/getstores?divisionid=<Division
Id>&partnerid=<partner Id>&partnertype=<Partner Type
URL
http://10.6.10.2:9080/bossServices/outboundservices/getstores
HTTP Method
GET
Confidential
Blackhawk Network
Blackhawk Network
Version: 1.6
Date: 11/04/2010
False
Request Parameters
Attribut
es
divisionid
partnerid
partnerty
pe
Data
Type
String
String
String
M/O/
C
M
O
O
pagenum
ber
String
Description
division Id for the desired partner search
Partner type code
3 - Card Partner.
Response Parameters
Attribut
es
Data
Type
Max.
Lengt
h
Stores
M/O/
C
Description
List of stores. This is mandatory tag and

present
Store Code
Store Name
partner Id corresponding to the same store
will be returned
comes with a partner type id otherwise the
partner type corresponding to the same
store Id will be returned.
number
Name
partneri
d
String
String
String
10
100
20
M
M
M
partnert
ype
String
Sample Request:
http://10.6.10.2:9080/ bossServices/outboundservices/ getstores?
divisionid=00561&partnerid=CVS&partnertype=3&pagenumber=2
Sample Response:
Confidential
Blackhawk Network
Blackhawk Network
Version: 1.6
Date: 11/04/2010

<response>
<statusinfo>
<status>
<records>
<start>501</start>
<end>1000</end>
<total>4000</total>
</records>
</status>
</statusinfo>
< stores>
<store>
<partnerid>CVS</partnerid>
<number>05016</ number >
<name>CVS</ name >
</store>
<store>
< number >05017/ number >
< name >SVS</ name >
</store>
</ stores >
</response>
2.4
Get Store Detail by division Id and store id API
This API method retrieves the store details that BOSS system has in it for the division
id and store id in the request. Since the division Id is an optional parameter, if it is
passed in the request, the store search is narrowed by store id and division id. The
store details will contain store name, store number ,division code store address, store
city, store country code ,store postal code and store state code. The request is in the
form of HTTP Get and the response is in the form of an xml.
URL:
http://10.6.10.2:9080/bossServices/outboundservices/getstores? id=<Store Id>&
divisionid=<Division id>&partnerid=<partner Id>&partnertype=<Partner Type
URL
http://10.6.10.2:9080/bossServices/outboundservices/getstores
HTTP Method
GET
Confidential
Blackhawk Network
Blackhawk Network
Version: 1.6
Date: 11/04/2010
False
Request Parameters
Attribut
es
divisionid
id
partnerid
partnerty
pe
Data
Type
String
String
String
String
M/O/
C
O
M
O
O
pagenum
ber
String
Description
division Id for the desired store search
Store Id for the desired store search
Partner type code
3 - Card Partner.
Response Parameters
Attribute
s
Data
Type
Max.
Lengt
h
Stores
M/O/
C
Description
List of stores. This is mandatory tag and

present
Store Name
Store Code
Division code
Name
number
Division
code
partnerid
String
String
String
100
10
10
M
M
String
20
partnertyp
e
String
Confidential

partner Id corresponding to the same
store will be returned
request comes with a partner type id
otherwise the partner type corresponding
to the same store Id will be returned.
Blackhawk Network
Blackhawk Network
Addrtxt
City
countryco
de
postalcode
stateprovc
ode
Version: 1.6
Date: 11/04/2010
String
String
String
200
100
10
O
0
O
Store address
City of the store
County of the Store
String
String
5
5
O
O
Zip code of the store

State code for the store
Sample Request:
http://10.6.10.2:9080/ bossServices/outboundservices/getstores?id=
05016&divisionid=00561&partnerid=CVS&partnertype=3&pagenumber=2
Sample Response:
<response>
<statusinfo>
<status>
<records>
<start>501</start>
<end>1000</end>
<total>4000</total>
</records>
</status>
</statusinfo>
< stores>
<store>
<name>CVS </name >
<divisioncd>00050</divisioncd>
<addrtxt>123 Ingersol </addrtxt >
<city>Sacremanto </city >
<countrycode>USA </countrycode>
<postalcode>92345 </postalcode >
<stateprovcode>CA</stateprovcode >
</store>
<store>
< name >SVS</ name>
<divisioncd>00051</divisioncd>
< addrtxt >123 Ingersol</ addrtxt >
< city >Sacremanto</ city >
< countrycode >USA</ countrycode.
< postalcode >92345</ postalcode >
Confidential
Blackhawk Network
Blackhawk Network
Version: 1.6
Date: 11/04/2010
< stateprovcode >CA</ stateprovcode >

</store>
</ stores>
</response>
2.5
Get UPC List API
This API method returns the product details based on the UPC filter received through
the request. The product details will have UPC and UPC description. The UPC filer can
be either UPC code or UPC description or card partner id or division id. The search will
be decided based on the input element in the request. If the UPC, UPC description
and card partner id and division id are present in the request, the search with be
done for the UPC details with the UPC code, UPC description and card partner and
division id in the request. Any combination of request parameters will be driving the
search. If the request comes with any one of these elements, then the search will be
based on that element.
If all the request parameters are empty, an exception response will be returned. If the
product list is above the given limit of 500 products, the system will send the
paginated result. The pagination will be calculated based on the page number detail
that comes through the request. The total number of records found and the range of
records in the response will be mentioned in the status info tag of the response. The
request is in the form of HTTP Get and the response is in the form of an xml.
URL:
http://10.6.10.2:9080/bossServices/outboundservices/getprocucts?
productcode=<UPC>&productdesc=<UPS
desc>&partnerid=<partnerid>&partnertype=<Partner Type
URL
http://10.6.10.2:9080/bossServices/outboundservices/getprocucts
HTTP Method
GET
False
Request Parameters
Attributes
productcode
product
Confidential
Data
Type
String
Sting
M/O/
C
O
O
Description
UPC for the product details search
Description or part of description for the product
Blackhawk Network
Blackhawk Network
description
CardPartnerI
D
partnertype
divisionid
pagenumber
Version: 1.6
Date: 11/04/2010
String
Card partner id for the product details search
String
String
String
O
O
Partner type code

3 - Card Partner.
Default is card partner. So if this parameter is not
passed we take it as a card partner call
Division Id for the product details search
Response Parameters
Attribut
es
Data
Type
Max.
Lengt
h
M/O/
C
Description
Productli
st
String
List of products. This is mandatory tag and

would be present even if no products are
present
Will return the CardPartnerID if the request
partner id corresponding the product will be
returned.
comes with a partner type id otherwise the
partner type corresponding to the same
product will be returned
Complete product code
Complete product description for product
code
partneri
d
String
20
partnert
ype
String
code
descripti
on
String
String
15
200
M
M
Sample Request:
http://10.6.10.2:9080/bossServices/outboundservices/getproducts?productcod=
07675002293&productdesc=safeway&partnerid= 256860& partnertype=3
&divisionid=00567&pagenumber=1
Confidential
Blackhawk Network
Blackhawk Network
Version: 1.6
Date: 11/04/2010
Sample Response:
<response>
<statusinfo>
<status>
<records>
<start>1</start>
<end>500</end>
<total>4000</total>
</records>
</status>
</statusinfo>
<products>
<product>
<partnerid>AARP</partnerid>
< code>07675002293</ code >
< description > AARP BIG BENEFIT $29.50</ description >
</product>
</products>
</response>
2.6
Get UPC Detail API
This API method returns the product details based on the UPC passed through the
request. The product details will have UPCdescription, cardpartnerid, amount,
currency, isvariable flag, isredeemable flag, isreloadable flag, createtime and
updatetime. If the request parameter is empty, an exception response will be
returned. The request is in the form of HTTP Get and the response is in the form of an
xml.
URL:
http://10.6.10.2:9080/ bossServices/outboundservices/getproduct?
productcode=<UPC &partnered=<partner Id>&partnertype=<Partner Type
URL
http://10.6.10.2:9080/ bossServices/outboundservices /getproduct
HTTP Method
Confidential
Blackhawk Network
Blackhawk Network
Version: 1.6
Date: 11/04/2010
GET
False
Request Parameters
Attributes
productcod
e
CardPartne
rID
partnertyp
e
pagenumb
er
Data
Type
String
M/O/
C
M
Description
String
Card partner id for the product details search
String
String
Partner type code

3 - Card Partner.
Default is card partner. So if this parameter is not
passed we take it as a card partner call
UPC for the product details search
Response Parameters
Attribute
s
Data
Type
Productlist
String
Code
descriptio
n
cardpartn
erid
partnertyp
e
Sting
String
15
200
M
M
String
20
String
amount
currency
isvariable
isredeema
ble
double
String
Boolen
Boolen
Confidential
Max.
Lengt
h
M/O/
C
Description
List of products. This is mandatory tag and

would be present even if no products are
present
UPC
Complete product description for product
code
Card partner id for the upc searched
O
M
O
O

request comes with a partner type id id
otherwise the partner type corresponding
to the same product will be returned
Amount associated with the upc
Currency code for the UPC
Indicates whether the upc is variable
Indicates whether the upc is redeemable
Blackhawk Network
Blackhawk Network
isreloadbl
e
createtim
e
updatetim
e
Version: 1.6
Date: 11/04/2010
Boolen
Indicates whether the upc is relodable
Date
Date
Indicate the time that upc was created in

mmddyyyy format
Indicate the time that upc was last
updated in mmddyyyy format
Sample Request:
http://10.6.10.2:9080/ bossServices/outboundservices/getproduct? productcode =
07675002293 &partnerid=AARP&partnertype=3&pagenumber=1
Sample Response:
<response>
<statusinfo>
<status>
<records>
<start>1</start>
<end>500</end>
<total>4000</total>
</records>
</status>
</statusinfo>
<products>
<product>
<code> 07675002293</code>
< description> AARP BIG BENEFIT $29.50</< description >
< cardpartnerid> AARP</ cardpartnerid>
< amount>20</ amount>
< currency>USD</ currency>
<isvariable>true</ isvariable >
<isredeemable>false</ isredeemable>
<isreloadable>false</ isreloadable>
<createtime>5/14/2009</ createtime >
<lastupdatetime>7/23/2009</ lastupdatetime >
</product>
</products>
</response>
3.
Status info description
Confidential
Blackhawk Network
Blackhawk Network
Version: 1.6
Date: 11/04/2010
Each of the successful service response will go with a status response tag in it.
Below are the contents of the status info tag
Attribu
tes
Status
Code
descripti
on
records
start
Data
Type
String
String
String
Max.
Length
10
100
M/O/
C
M
M
O
String
integer
M
M
end
Integer
10
Total
Integer
10
Description
Response code for the status
Response description.
Starting row number of the record in the
response for the search
Last row number of the record in the
response for the search
Total number of records found for search.
Sample :
<statusinfo>
<status>
<records>
<start>1</start>
<end>500</end>
<total>4000</total>
</records>
</status>
</statusinfo>
4.
Exception / Error response
Incase of any exceptions / Errors , the BOSS service will respond with the below
response format.
<response>
<statusinfo>
<status>
<description>FAILED - REASON</description>
</status>
</statusinfo>
</response>
Confidential
Blackhawk Network
Blackhawk Network
5.
Version: 1.6
Date: 11/04/2010
Response Code and Description
Response Code
Response description
STL100
STL001
STL002
STL003
STL010
SUCCESS
TECHNICAL_DIFFICULTIES
BOSS Internal Error
Invalid parameters in request
Could not find divions for the request
data
Could not find stores for the request data
Could not find PRODUCTS for the request
data
STL011
STL012
Confidential
Blackhawk Network

BHN WebPos Service Specifications

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

BHN WebPos Service Specifications

Uploaded by

Copyright:

Available Formats

______________________________________________

Blackhawk BOSS Retailer Service Specification

Using BOSS REST Retailer Services API.......................................................................................4

Get division List API................................................................................................. 4

Get division Detail by divisionId API.........................................................................6

Get Store List by division id API...............................................................................9

Get Store Detail by division Id and store id API....................................................11

Get UPC List API..................................................................................................... 13

Get UPC Detail API................................................................................................. 15

Status info description......................................................................................................................................17

Exception / Error response...............................................................................................................................18

Response Code and Description......................................................................................................................18

Using BOSS REST Retailer Services API

Get division List API

List of divisions. This is mandatory tag and

Get division Detail by divisionId API

List of divisions. This is mandatory tag

Division Zip Code

Will return the partner Id if the request

comes with a partner Id other wise the

< addrtxt>123, Pleasanton</ addrtxt >

Get Store List by division id API

List of stores. This is mandatory tag and

<?xml version="1.0" encoding="utf-8" ?>

Get Store Detail by division Id and store id API

List of stores. This is mandatory tag and

Will return the partner Id if the request

Zip code of the store

< stateprovcode >CA</ stateprovcode >

Get UPC List API

Card partner id for the product details search

Partner type code

List of products. This is mandatory tag and

Get UPC Detail API

Card partner id for the product details search

Partner type code

UPC for the product details search

List of products. This is mandatory tag and

Will return the partner type id if the

Indicates whether the upc is relodable

Indicate the time that upc was created in

Status info description

Exception / Error response

Response Code and Description

You might also like