BHN WebPos Service Specifications

BHN webPos service Specifications

______________________________________________

Blackhawk BOSS Retailer Service Specification

Version Number: 1.6Revision History

DateRevision NumberDescriptionAuthor

05/19/100.1First DraftDileep Prasad

06/02/101.0Reviewed with Biju BDileep Prasad

06/06/101.1Updates after discussion with webPos teamDileep Prasad

06/12/20101.2Modified the URL and Product searchDileep Prasad

06/16/20101.3Modmodified with response codes and description, updated Get Store Detail by division Id with division id in responseDileep Prasad

08/03/20101.4MOIInclude partner code and partner type in request and response for all servicesDileep Prasad

08/06/20101.5Making the partner code and partner type mandatory for All responses.Dileep Prasad

11/04/20101.6Updating the spec with Pagination detailsDileep Prasad

Table of Contents

41.Overview

42.Using BOSS REST Retailer Services API

42.1Get division List API

62.2Get division Detail by divisionId API

92.3Get Store List by division id API

112.4Get Store Detail by division Id and store id API

132.5Get UPC List API

152.6Get UPC Detail API

173.Status info description

184.Exception / Error response

185.Response Code and Description

1. 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

Application Developers,

System Architects

Network Engineers

Project Managers

2. 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 APIThis 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=&id=&partnerid=&partnertype=&pagenumber=URL

http://10.6.10.2:9080/ bossServices/outboundservices/getdivisionsHTTP Method

GETAuthentication RequiredFalse

Request Parameters

AttributesData TypeM/O/CDescription

nameStringOdivision name or part of the division name for which the client wants the details

idStringOdivision id or part of the division id for which the client wants the details

partneridStringOPartner code under which the division falls in

partnertype StringOPartner type code1 - Alliance Partner

3 - Card Partner.

Default is card partner. So if this parameter is not passed we take it as a card partner call

pagenumberStringORange 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 ParametersAttributesData TypeMax. LengthM/O/CDescription

divisionsMList of divisions. This is mandatory tag and would be present even if no retailers are present

idString15Mdivision Id

nameString100Mdivision Name

partneridString20MWill return the partner Id if the request comes with a partner Id other wise the partner Id corresponding to the division code

partnertype String5MWill 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/getdivisions? name=SFWY&id=00651d&partnerid=SFY&partnertype=3&pagenumber=1Sample Response:

STL_000

SUCCESS

1

500

4000

00561

< name>SWFY Stockton SWFY Vons SFY

3

< division >

00562

SWFY - Pleasanton

SFY

3

2.2 Get division Detail by divisionId APIThis 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:

http://10.6.10.2:9080/bossServices/outboundservices/getdivision? id=&partnerid=&partnertype=&pagenumber=URL

http://10.6.10.2:9080/bossServices/outboundservices/getdivisionHTTP Method


Request Parameters

1.Below are the request parameter details for this service


idStringMdivision Id for the desired partner search

partneridStringOPartner Id for the division in the request

partnertypeStringOPartner type code

1 - Alliance Partner

3 - Card Partner.




Response Parameters

AttributesData TypeMax. LengthM/O/CDescription

divisionsMList of divisions. This is mandatory tag and would be present even if no retailers are present

nameString100MDivision Name

addrtxtString500ODivision address

cityString500Division city

countrycodeString50Division Country

postalcodeString50Division Zip Code

stateprovcodeString50Division State Code

partneridString20MWill return the partner Id if the request comes with a partner Id other wise the partner Id corresponding to the division code

partnertype String5MWill 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=1Sample Response:

STL_000

SUCCESS

1

500

4000

< divisions>

< division> MACY

3

MACY - Stockton

< addrtxt>123, Stockton

< city>Stockton

< countrycode >USA

< postalcode >93456

CA

< division> 00561 MACY

3

SWFY - Pleasanton

< name>MACY - Pleasanton

< addrtxt>123, Pleasanton

< city>Pleasanton

< countrycode>USA

< postalcode>94588

< stateprovcode >CA

2.3 Get Store List by division id APIThis 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=&partnerid=&partnertype=&pagenumber=URL

http://10.6.10.2:9080/bossServices/outboundservices/getstoresHTTP Method


Request Parameters



divisionidStringMdivision Id for the desired partner search




3 - Card Partner.




Response Parameters


StoresMList of stores. This is mandatory tag and would be present even if no retailers are present

numberString10MStore Code

NameString100MStore Name

partneridString20MWill return the partner Id if the request comes with a partner Id other wise the partner Id corresponding to the same store will be returned

partnertype String5MWill return the partner type id if the request comes with a partner type id otherwise the partner type corresponding to the same store Id will be returned.

Sample Request:

http://10.6.10.2:9080/ bossServices/outboundservices/ getstores? divisionid=00561&partnerid=CVS&partnertype=3&pagenumber=2Sample Response:

STL_000

SUCCESS

501

1000

4000

< stores>

CVS

3

05016

CVS

CVS

3

< number >05017/ number >

< name >SVS

2.4 Get Store Detail by division Id and store id APIThis 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=& divisionid=&partnerid=&partnertype=&pagenumber=URL

http://10.6.10.2:9080/bossServices/outboundservices/getstoresHTTP Method


Request Parameters



divisionidStringOdivision Id for the desired store search

idStringMStore Id for the desired store search




3 - Card Partner.




Response Parameters


StoresMList of stores. This is mandatory tag and would be present even if no retailers are present

NameString100MStore Name

numberString10MStore Code

Division codeString10Division code

partneridString20MWill return the partner Id if the request comes with a partner Id other wise the partner Id corresponding to the same store will be returned

partnertype String5MWill return the partner type id if the request comes with a partner type id otherwise the partner type corresponding to the same store Id will be returned.

AddrtxtString200OStore address

CityString1000City of the store

countrycodeString10OCounty of the Store

postalcodeString5OZip code of the store

stateprovcodeString5OState code for the store

Sample Request:

http://10.6.10.2:9080/ bossServices/outboundservices/getstores?id= 05016&divisionid=00561&partnerid=CVS&partnertype=3&pagenumber=2Sample Response:

STL_000

SUCCESS

501

1000

4000

< stores>

CVS

05016

00050

CVS

3

123 Ingersol

Sacremanto

USA 92345

CA

< name >SVS

05016 00051

CVS

3

< addrtxt >123 Ingersol

< city >Sacremanto

< countrycode >USA92345

< stateprovcode >CA

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=&productdesc=&partnerid=&partnertype=&pagenumber=URL

http://10.6.10.2:9080/bossServices/outboundservices/getprocuctsHTTP Method


Request Parameters



productcodeStringOUPC for the product details search

product descriptionStingODescription or part of description for the product

CardPartnerIDStringOCard partner id for the product details search



3 - Card Partner.


divisionidStringODivision Id for the product details search



Response Parameters


ProductlistStringMList of products. This is mandatory tag and would be present even if no products are present

partneridString20MWill return the CardPartnerID if the request comes with a partner Id other wise the partner id corresponding the product will be returned.

partnertype String5MWill return the partner type id if the request comes with a partner type id otherwise the partner type corresponding to the same product will be returned

codeString15MComplete product code

descriptionString200MComplete product description for product code

Sample Request:

http://10.6.10.2:9080/bossServices/outboundservices/getproducts?productcod= 07675002293&productdesc=safeway&partnerid= 256860& partnertype=3 &divisionid=00567&pagenumber=1Sample Response:

STL_000

SUCCESS

1

500

4000

AARP

3

< code>07675002293

< description > AARP BIG BENEFIT $29.50

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= AARP BIG BENEFIT $29.50

< cardpartnerid> AARP

3

< amount>20

< currency>USD

true

false

false

5/14/2009

7/23/2009

3. Status info description

Each of the successful service response will go with a status response tag in it. Below are the contents of the status info tag


StatusStringM

CodeString10MResponse code for the status

descriptionString100OResponse description.

recordsStringM

startinteger5MStarting row number of the record in the response for the search

end Integer10MLast row number of the record in the response for the search

TotalInteger10MTotal number of records found for search.

Sample :

STL_000

SUCCESS

1

500

4000

4. Exception / Error response

Incase of any exceptions / Errors , the BOSS service will respond with the below response format.

STL_100

FAILED - REASON

5. Response Code and Description

Response Code Response description

STL100SUCCESS

STL001TECHNICAL_DIFFICULTIES

STL002BOSS Internal Error

STL003Invalid parameters in request

STL010Could not find divions for the request data

STL011Could not find stores for the request data

STL012Could not find PRODUCTS for the request data

Confidential

Blackhawk Network

Documents

BHN WebPos Service Specifications