Documente Academic
Documente Profesional
Documente Cultură
Design Specification
Confidential
1 Change History
Date
11-Feb-2012
Version
1.0
Release
Owner
Ragini Bajpai
Description
Added details for posActivate API
Page 2 of 22
2 Table of Contents
1
Introduction ...................................................................................................................................................................................................................................... 4
3.1
Purpose ..................................................................................................................................................................................................................................... 4
3.2
Scope......................................................................................................................................................................................................................................... 4
3.3
3.4
References ................................................................................................................................................................................................................................ 4
Overview .................................................................................................................................................................................................................................... 6
3.5.1
3.5.1.1
Sample Request ......................................................................................................................................................................................................... 9
3.5.2
Response Structure ......................................................................................................................................................................................................... 11
4
3.5.2.1
Sample Response ..................................................................................................................................................................................................... 12
Design ............................................................................................................................................................................................................................................ 13
5.2
5.3
Class Diagram................................................................................................................................................................................................................................ 16
10
11
12
Page 3 of 22
3 Introduction
3.1
Purpose
posActivate API provides the ability to activate (unlock) a retail product. This is also referred to as point-of-sale (POS) activation.
Once the product is POS activated, only then can it be activated using the product key.
Earlier this API was created to provide support for Dixons (ePay) partner only. Now it is extended to support BlackHawk and Incomm integration providers
as well.
3.2
Scope
This document covers the design and application flow of posActivate API.
3.3
3.4
Description
Point Of Sale
References
3.4.1 Documents
Document
Version
//depot/Consumer_Online_Services/Core_API/olp_core/trunk/docs/
APIs/PosaService/PosActivate_Interface_Spec.docx
Staples POSA - High Level Solution Overview
1.0
Page 4 of 22
3.0
Date
Page 5 of 22
3.5
Overview
posActivate API is called by BlackHawk, Incomm and Dixons partners.
The basic flow of API in COLP is described below:
Page 6 of 22
Data Type
VendorInfo
Description
Vendor credentials.
Validation
Not null, and caller must have access.
Notes
Using
existing
validation
Version
requestInfo
Int
RequestInfo
Not null.
Using
existing
validation
psnIdentifier
PSNIdentifier
integrationProvider
Enum
Page 7 of 22
psnIdentifier
Element
Psn
partnerPSN
Data Type
ProductSerialNumber
PartnerProductSerialNumber
Description
Validation
.
Notes
RequestInfo
requestInfo is used to track requests including duplicates.
Element
requestID
Data Type
String
Description
String used to
identify requests.
Resend
Integer
Request count in
case of retry.
Validation
Not blank (Category 1, Status - 0005,
DetailedStatus 0507, Message EMPTY_REQUEST_ID).
String can contain up to 50 alpha numeric
characters. (Category 1, Status - 0005,
DetailedStatus 0508 MessageINVALID_REQUEST_ID_LENGTH).
Not null.
Notes
requestID must be unique for each successful
request. If a request has to be retried, same
requestID can be used but resend parameter should
be incremented by one. If a requestID is reused but
resend is not incremented, duplicate request error
code will be returned.
resend cannot be less than zero.This parameter
needs to be incremented by one in case of a request
retry.
VendorInfo
Element
vendorID
vendorPW
Data
Type
Int
String
int
Description
Validation
vendorSiteID
clientSystemID
String
endUserID
endUserType
String
String
Optional.
Optional.
Page 8 of 22
Notes
3.5.1.1
Sample Request
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ps="http://ps.webservices.symantec.com/">
<soapenv:Header/>
<soapenv:Body>
<ps:posActivate>
<!--Optional:-->
<posActivateRequest>
<requestInfo><resend/></requestInfo><requestVendor>
<vendorID>?</vendorID>
<vendorPW>?</vendorPW>
<vendorSiteID>?</vendorSiteID>
<!--Optional:-->
<clientSystemID>?</clientSystemID>
<!--Optional:-->
<endUserID>?</endUserID>
<!--Optional:-->
<endUserType>?</endUserType>
</requestVendor>
<!--Optional:-->
<version>?</version>
<integrationProvider>EPAY</integrationProvider>
<action>?</action>
<psnIdentifier>
<!--You have a CHOICE of the next 2 items at this level-->
<partnerPSN>
<partnerProductSerialNumber>?</partnerProductSerialNumber>
</partnerPSN>
<psn>
<productSerialNumber>?</productSerialNumber>
</psn>
</psnIdentifier>
<!--Optional:-->
<transactionTime>?</transactionTime>
<!--Optional:-->
<partnerSpecificDetails>
<!--1 or more repetitions:-->
Page 9 of 22
<nameValuePair>
<name>?</name>
<value>?</value>
</nameValuePair>
</partnerSpecificDetails>
</posActivateRequest>
</ps:posActivate>
</soapenv:Body>
</soapenv:Envelope>
Page 10 of 22
Data Type
String
Result
Date
NameValuePairList
Description
Status expected by the partner
COLP result
Server time.
Result
Element
category
status
detailedStatusList
detailedStatus
statusMessage
Data Type
String
String
List
String
String
Description
Category can be 0,1
Contains 1 or more detailStatus
Page 11 of 22
Notes
3.5.2.1
Sample Response
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ps="http://ps.webservices.symantec.com/">
<soapenv:Header/>
<soapenv:Body>
<ps:posActivateResponse>
<!--Optional:-->
<return>
<!--Optional:-->
<result>
<category>?</category>
<status>?</status>
<!--Optional:-->
<detailedStatusList>
<!--Zero or more repetitions:-->
<detailedStatus>?</detailedStatus>
</detailedStatusList>
<!--Optional:-->
<statusMessage>?</statusMessage>
</result>
<!--Optional:-->
<serverTimestamp>?</serverTimestamp>
<!--Optional:-->
<attributes>
<!--1 or more repetitions:-->
<nameValuePair>
<name>?</name>
<value>?</value>
</nameValuePair>
</attributes>
<posPartnerStatus>?</posPartnerStatus>
</return>
</ps:posActivateResponse>
</soapenv:Body>
</soapenv:Envelope>
Page 12 of 22
4 Design
Page 13 of 22
5 API Flow
To implement posActivate API, code has been categorized (as per COLP architecture) in following 4 layers:
5.1
Protocol
Application
Service
Domain
Protocol Layer
Protocol layer contains Request and Response objects of the API. This layer is responsible to convert protocol objects to domain objects and place
call to application layer for fulfilment of request.
Below validations are performed at this layer: (Need confirmation do we really need this validation or API will provide support for both psn/partnerPSN
irrespective of integration provider?)
5.2
If integration Provider is BLACKHAWK then partnerPSN identifier should be present in request otherwise return status-0005. DetailedStatus0556 and status Message INVALID_PID_FOR_PARTNER will be returned in response.
If integration Provider is INCOMM then psn identifier should be present in request. otherwise return status-0005. DetailedStatus-0556 and
status Message INVALID_PID_FOR_PARTNER will be returned in response.
If integration Provider is EPAY then partnerPSN identifier should be present in request. otherwise return status-0005. DetailedStatus-0556
and status Message INVALID_PID_FOR_PARTNER will be returned in response.
Application Layer
This layer has following features:
Page 14 of 22
5.3
Service Layer
This layer is responsible to implement the business logic behind the API. It also communicates with the domain layer to interact with the database.
Service layer supports features to load partner rule sheets, execute rules defined in XLS sheet and update status of Popcon to enabled and enableState of
Subscription_Current to enabled in DB.
Following are the steps performed on service layer on the basis of integration Provider provided in request:
Page 15 of 22
6 Database Operations:
S. No.
1.
Table Name
EBE_CODES
Operation
Write
Change
Inserted API details in EBE_CODES table before API execution
2
3.
4.
POPCON
POPCON_CURRENT
SUBSCRIPTION_CU
RRENT
EBE_SUB_TRANSAC
TION
Read/Update
Read
Read/Update
Read/Insert
7 Class Diagram
Pos Activate Specification Document
Page 16 of 22
Page 17 of 22
8 Sequence Diagram
Page 18 of 22
9 Common Flows
Page 19 of 22
10 Use Cases
Page 20 of 22
Code
Definition
0000
0001
0004
0005
SUCCESS
ERROR
INTERNAL_ERROR
VALIDATION_ERROR
Page 21 of 22
12 Detailed Status
Following are some of detailed return codes that this API will return:
Detailed
Status
Code
-
Category
posStatus
(BLACKHAWK)
posStatus
(Incomm)
Definition
0000
00
0000
12290
21
10030
12291
TBD
TBD
12292
04
TBD
12293
43
10083
07
TBD
12296
04
10038
0100
TBD
TBD
Invalid vendor
0150
TBD
TBD
21550
TBD
TBD
Invalid clientSystemID
20000
TBD
TBD
9102
TBD
TBD
21500
TBD
TBD
21501
TBD
TBD
21502
TBD
TBD
0001
TBD
TBD
Unhandled exception
0005
TBD
TBD
0556
Status
12295
Page 22 of 22