Embed Size (px)
Citation preview
Contract Admin Web Service CCW-Renewal Implementation Guidelines Message Type: JSON 5 March 2019 Version 1.1
2019 Cisco Systems, Inc. All rights reserved. Contract Admin Web Service V1 | 2
THE SPECIFICATIONS AND INFORMATION REGARDING THE PRODUCTS IN THIS MANUAL ARE SUBJECT TO
CHANGE WITHOUT NOTICE. ALL STATEMENTS, INFORMATION, AND RECOMMENDATIONS IN THIS MANUAL ARE
BELIEVED TO BE ACCURATE BUT ARE PRESENTED WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED.
USERS MUST TAKE FULL RESPONSIBILITY FOR THEIR APPLICATION OF ANY PRODUCTS.
THE SOFTWARE LICENSE AND LIMITED WARRANTY FOR THE ACCOMPANYING PRODUCT ARE SET FORTH IN THE
INFORMATION PACKET THAT IS SHIPPED WITH THE PRODUCT AND ARE INCORPORATED HEREIN BY THIS
REFERENCE. IF YOU ARE UNABLE TO LOCATE THE SOFTWARE LICENSE OR LIMITED WARRANTY, CONTACT
YOUR CISCO REPRESENTATIVE FOR A COPY.
NOTWITHSTANDING ANY OTHER WARRANTY HEREIN, ALL DOCUMENT FILES AND SOFTWARE OF THESE
SUPPLIERS ARE PROVIDED “AS IS” WITH ALL FAULTS. CISCO AND THE ABOVE-NAMED SUPPLIERS DISCLAIM
ALL WARRANTIES, EXPRESSED OR IMPLIED, INCLUDING, WITHOUT LIMITATION, THOSE OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NON INFRINGEMENT OR ARISING FROM A COURSE OF DEALING,
USAGE, OR TRADE PRACTICE.
IN NO EVENT SHALL CISCO OR ITS SUPPLIERS BE LIABLE FOR ANY INDIRECT, SPECIAL, CONSEQUENTIAL, OR
INCIDENTAL DAMAGES, INCLUDING, WITHOUT LIMITATION, LOST PROFITS OR LOSS OR DAMAGE TO DATA
ARISING OUT OF THE USE OR INABILITY TO USE THIS MANUAL, EVEN IF CISCO OR ITS SUPPLIERS HAVE BEEN
ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
CISCO AND THE CISCO LOGO ARE TRADEMARKS OF CISCO SYSTEMS, INC. AND/OR ITS AFFILIATES IN THE U.S.
AND OTHER COUNTRIES. A LISTING OF CISCO’S TRADEMARKS CAN BE FOUND AT
WWW.CISCO.COM/GO/TRADEMARKS. THIRD PARTY TRADEMARKS MENTIONED ARE THE PROPERTY OF
RESPECTIVE OWNERS. THE USE OF THE WORD PARTNER DOES NOT IMPLY A PARTNERSHIP RELATIONSHIP
BETWEEN CISCO AND ANY OTHER COMPANY. (1005R)
CISCO RESERVES THE RIGHT TO MAKE UPDATES TO THIS API AT ANY TIME. SHOULD AN UPDATE REQUIRE
NEW DEVELOPMENT OR UPDATES BY THE PARTNER, CISCO WILL PROVIDE YOU WITH 60 DAYS NOTICE. BY
USING THIS SERVICE, YOU AGREE TO COMPLY WITH SUCH A REQUEST WITHIN 60 DAYS, OR RISK LOSING
CONNECTIVITY TO THIS API.
© 2019 Cisco Systems, Inc. All rights reserved.
2019 Cisco Systems, Inc. All rights reserved. Contract Admin Web Service V1 | 3
LIST OF TABLES 4
LIST OF FIGURES 4
INTRODUCTION 5
1.1 Overview 5
1.2 Audience 6
1.3 Prerequisites 6
1.4 Scope 6
1.5 Guideline Annotations 6
CONNECTIVITY 7
2.1 Communication Protocol 7
2.2 Registration & Authentication 7
2.3 Endpoint URLs 8
2.4 HTTP Header 8
MESSAGE SPECIFICATION 9
3.1 Search API 9
3.1.1 Request Message 9
3.1.2 Response Message 11
3.2 Move API 24
3.2.1 Request Message 24
3.2.2 Response Message 25
3.3 Merge API 26
3.3.1 Request Message 26
3.3.2 Response Message 26
3.4 Transaction Header API 27
3.4.1 Request Message 27
3.4.2 Response Message 27
3.5 Transaction Line API 28
3.5.1 Request Message 28
3.5.2 Response Message 28
APPENDIX A: REFERENCES 30
REVISION HISTORY 31
GLOSSARY 32
Con
tent
2019 Cisco Systems, Inc. All rights reserved. Contract Admin Web Service V1 | 4
List of Tables
Table No. Tittle Page No.
1 Cardinality References 6
2 Endpoint URLs 8
3 HTTP Header 8
List of Figures
Figure No. Tittle Page No.
1 Contract Administration WS Process 5
2 Communication Protocol 7
2019 Cisco Systems, Inc. All rights reserved. Contract Admin Web Service V1 | 5
Introduction Contract Administration Web Service (WS) consists of three APIs that enable you to search, move, and merge
contracts. It also includes two APIs that enable you to request the Move and Merge Transactions information.
o Search API – Enables you to search for detailed information by either Instance Number, Serial Number, or Contract Number.
o Move API – Enables you to move product(s) to another contract.
o Merge API – Enables you to merge a contract by moving all products from one contract to another contract.
o Transaction Header API – Enables you receive the header level information of a Merge or a Move Transaction.
o Transaction Line API - Enables you receive the line level information of a Merge or a Move Transaction.
1.1 Overview The communication between your system and Cisco’s system is through JSON requests and subsequent
response messages. Figure 1 illustrates the overview of the Contract Administration WS process. When you
send your JSON request to Contract Administration WS, Cisco’s system will authenticate your credentials (See
Registration & Authentication) and validate your request. Upon successful validation, Cisco’s system will
response with a JSON message.
Figure 1: Contract Administration WS Process
2019 Cisco Systems, Inc. All rights reserved. Contract Admin Web Service V1 | 6
1.2 Audience This document is most useful to:
• Business analysts
• IT engineers
• Technical architects who are involved in the integration project
• Other stakeholders who wish to understand business and/or technical aspects of integration
1.3 Prerequisites Before the implementation process can begin, Partners must have:
• Some familiarity with Contract Administration WS process
• Formal/informal training on utilizing Cisco API Console
• Credentials (CCO ID) must be established to access Cisco API Console and Cisco’s WS infrastructure
• Registered application with Cisco’s API console
• Knowledge of how to create a token on the APIx platform
For more information on credential and/or token creation, please refer to Appendix A for URLs.
1.4 Scope This document describes the specifications, guidelines, attribute definitions, request and response JSONs,
dependencies, and assumptions of the Contract Administration Web Service.
1.5 Guideline Annotations Use Table 1 to reference the elements’ cardinality in Section 3.
Cardinality Value Semantics
1 Mandatory, only one instance
1…n Mandatory, one or more instances
0…1 Optional, only one instance
0…n Optional, one or more instances
Table 1: Cardinality References
2019 Cisco Systems, Inc. All rights reserved. Contract Admin Web Service V1 | 7
Connectivity
2.1 Communication Protocol Cisco supports the Contract Administration WS through Application Programming Interface (API) build on REST
Web Service framework. The interactions between the Partner systems and Cisco APIs are done by a ‘request
and response’ JSON interchange. By using REST as the means for information exchange, processes canrun on
disparate operating systems. Figure 2 below shows a high-level view of the communication protocol flow.
2.2 Registration & Authentication To interface with Cisco APIs, you need to register their applications with Cisco’s API console. This section
describes the registration and authentication process. See the Appendix for URLs to both Hello API and Create
Token API IGs for visual step-by-step instructions.
1. Go to https://apiconsole.cisco.com/ and login with a valid CCO ID and Password.
2. Once logged in, click the “My APIs” tab. Find CCWR Contract Administration. If the ‘Register’ Button appears next to this API, please skip to step #4.
3. Click on ‘Request Access’. An email template should pop up, please fill out the information in the email body. A confirmation email will be sent to you. Once access granted, repeat step #1.
4. Click the ‘Register’ button and give your application a name.
5. Under OAuth 2.0 Credentials, select the check box next to Resource Owner Credentials. NOTE: Make sure to select “Resource Owner Credentials”. If you select any other value, you will still be able to successfully generate a token. However, when using that token to call the CCWR Contract Administration API, you will receive an error.
6. Select the check box next to “Refresh Token”.
7. Under Select APIs, click the check boxes next to “CCWR Contract Administration API” and “CCWR Contract Administration API – POE”.
8. Under Terms of Service, click the check box next to “I agree to the Terms of Service”.
9. Click the “Register” button.
After the application registration is complete, the console window displays an “Application Registered”
message. Please note the Client ID and Client Secret, as these values will be needed to successfully generate
an access token. You may log out of the API Console, your application is now created.
Figure 2: Communication Protocol
2019 Cisco Systems, Inc. All rights reserved. Contract Admin Web Service V1 | 8
2.3 Endpoint URLs Endpoint URLs are the origin or destination of a session. The Production endpoint URLs for all APIs are listed in
Table 2. NOTE: Special connectivity such as VPN is not required.
Service Method URLs
Search API Post https://api.cisco.com/ccw/renewals/api/v1.0/search/lines
Move API Post https://api.cisco.com/ccw/renewals/api/v1.0/contract/move
Merge API Post https://api.cisco.com/ccw/renewals/api/v1.0/contract/merge
Transaction Header API Get https://api.cisco.com/ccw/renewals/api/v1.0/contract/transactions/{trxId}
Transaction Line API
Get https://api.cisco.com/ccw/renewals/api/v1.0/contract/transactions/{trxId}/lines
2.4 HTTP Header
Table 2: Endpoint URLs
Table 3: HTTP Header
Property Specification
Authorization Token for authorization Type: String Example: Authorization : Bearer yourToken
Accept Accepted Content type Type: String
Content-Type Application/json Type: String
Request-ID Type: Integer
Accept-Language en_us
2019 Cisco Systems, Inc. All rights reserved. Contract Admin Web Service V1 | 9
Message Specification The request and response tables below describes the cardinality structure and descriptions of each element in
Cisco Contract Administration APIs. Please refer to the reference Table 1 (Cardinality References) for
cardinality values assigned to each element.
3.1 Search API The Search API enables you to request detailed information for a product. You must input one of three criterias
(Instance Number, Serial Number, and Contract Number) in your search. You can also filter your search to
Major and Minor lines by using the “configuration” element (No. 6) in your request message.
3.1.1 Request Message
No. Element Cardinality Specifications
1 instanceNumbers 1…n
Instance Number (Cisco unique ID)
Type: Array Array values type: String
Example: “instanceNumbers”: [“12345”, “2345”]
2 serialNumbers 1…n Serial Number
Type: Array Array values type: String
Example: “serialNumbers”: [“NYF8743”, “NMVC2345”]
3 contracNumbers 1..n Contract Number
Type: Array Array values type: String
Example: “contractNumbers”: [“12345”, “2345”]
4 limit 0..1 Pagination
Specifies the number of lines will be returned in the response.
Type: Integer Mininumum: 1 Maximum: 1000 Default: 100
Example: “limit”: 100
5 offset 0..1 Pagination Starting Point
First line = 0 Type: Integer Mininumum: 0 Maximum: 999 Default: 0
Example: “offset”: 0
2019 Cisco Systems, Inc. All rights reserved. Contract Admin Web Service V1 | 10
No. Element Cardinality Specifications
6 configuration 0…1 Major/Minor Line
“True” = Return information for major AND minor lines.
“False” = Return information for ONLY major lines.
Type: Boolean Default: False
Example: “configuration”: “False”
2019 Cisco Systems, Inc. All rights reserved. Contract Admin Web Service V1 | 11
3.1.2 Response Message
No Element Cardinality Specifications
1 totalRecords 1
Total number of returned record(s)
Type: Integer
2 instances 1…n Instances
Type: Array
3 | items 1..n Type: Object
4 || lastDateOfSupport 1 Last Date of Support
Type: date-time
5 || lastDateOfSale 0..1 Last Date of Sale
Type: date-time
6 || serialNumber 1…n Serial Number Type: String
7 || parentSerialNumber 1…n Parent Serial Number
Type: String
8 || minor 1 Minor Line Indicator
True: This is the minor line. There is a parent line.
False: This is a parent line.
Type: Boolean
9 || instanceNumber 1…n Instance Number
Type: String
10 || parentInstanceNumber 1…n Parent Instance Number
Type: String
11 || installedBaseStatus 1…n Installed Base Status
Type: String
instances/endCustomer
12 || endCustomer 0…1 End customer information
13 ||| globalUltimate 0..1 GU details
14 |||| name 0…1 Party Name
Type: String
2019 Cisco Systems, Inc. All rights reserved. Contract Admin Web Service V1 | 12
No Element Cardinality Specifications
15 |||| id 0..1 Party ID
Type: String
16 |||| address
17 ||||| address1 0…1
Address 1
Type: String
18 ||||| address2 0…1 Address 2
Type: String
19 ||||| address3 0…1 Address 3
Type: String
20 ||||| address4 0…1 Address 4
Type: String
21 ||||| city
0…1 City
Type: String
22 ||||| country 0..1 Country
Type: String
23 ||||| postalCode 0..1 PostalCode
Type: String
24 ||||| state 0..1 State
Type: String
25 ||||| location 0..1 Address Unique Identifier
Type: String
26 ||||| name 0..1 Party Name on the Invoice
Type: String
27 ||||| orgId 0…1 Organization ID
Type: Integer
28 ||||| partySiteId 0…1 Party Site ID
Type: Integer
29 ||| id 0..1 End Customer ID
Type: String
30 ||| name 0..1 End Customer Name
2019 Cisco Systems, Inc. All rights reserved. Contract Admin Web Service V1 | 13
No Element Cardinality Specifications
Type: String
31 ||| address
32 |||| address1 0..1
Address 1
Type: String
33 |||| address2 0..1 Address 2
Type: String
34 |||| address3 0..1 Address 3
Type: String
35 |||| address4 0..1 Address 4
Type: String
36 |||| city
0…1 City
Type: String
37 |||| country 0…1 Country
Type: String
38 |||| postalCode 0…1 PostalCode
Type: String
39 |||| state 0…1 State
Type: String
40 |||| location 0…1 Address Unique Identifier
Type: String
41 |||| name 0..1 Party Name on the Invoice
Type: String
42 |||| orgId 0..1 Org ID
Type: Integer
43 |||| partySiteId 0..1 Party Site ID
Type: Integer
44 || serviceSKU 0..1 Service SKU
Type: String
45 || serviceLevel 0..1 Service Level
Type: String
46 || startDate 0…1 Site ID
2019 Cisco Systems, Inc. All rights reserved. Contract Admin Web Service V1 | 14
No Element Cardinality Specifications
Format: Date-Time
47 || endDate 0…1 End Date
Format: Date-Time
Instances/contract
48 || contract 1 Contract related information
49 ||| number 1 Contract Number of the Instance
Type: String
50 ||| lineStatus 1 Line Status
Type: String
51 ||| billToGlobalUltimate
52 |||| globalUltimate
53 ||||| name 1 Party Name
Type: String
54 ||||| id 1 Party ID
Type: String
55 ||||| address
56 |||||| address1 0..1
Address 1
Type: String
57 |||||| address2 0..1 Address 2
Type: String
58 |||||| address3 0..1 Address 3
Type: String
59 |||||| address4 0..1 Address 4
Type: String
60 |||||| city
0..1 City
Type: String
61 |||||| country 0..1 Country
Type: String
62 |||||| postalCode 0..1 PostalCode
Type: String
2019 Cisco Systems, Inc. All rights reserved. Contract Admin Web Service V1 | 15
No Element Cardinality Specifications
63 |||||| state 0..1 State
Type: String
64 |||||| location 0..1 Address Unique Identifier
Type: String
65 |||||| name 0..1 Party Name on the Invoice
Type: String
66 |||||| orgId 0..1 Org ID
Type: Integer
67 |||||| partySiteId 0..1 Party Site ID
Type: Integer
Instance/contract/billTo
68 ||| billTo
69 |||| address1 0..1
Address 1
Type: String
70 |||| address2 0..1 Address 2
Type: String
71 |||| address3 0..1 Address 3
Type: String
72 |||| address4 0..1 Address 4
Type: String
73 |||| city
0..1 City
Type: String
74 |||| country 0..1 Country
Type: String
75 |||| postalCode 0..1 PostalCode
Type: String
76 |||| state 0..1 State
Type: String
77 |||| location 0..1 Address Unique Identifier
Type: String
78 |||| name 0..1 Party Name on the Invoice
2019 Cisco Systems, Inc. All rights reserved. Contract Admin Web Service V1 | 16
No Element Cardinality Specifications
Type: String
79 |||| orgId 0..1 Org ID
Type: Integer
80 |||| partySiteId 0..1 Party Site ID
Type: Integer
81 || macId 0..1 Mac ID
Type: String
82 || cartonId 0..1 Carton ID
Type: String
83 || quantity 1…n Quantity
Type: Integer
84 || salesOrderNumber 0..1 Sales Order Number
Type: String
85 || purchaseOrderNumber 0..1 Purchase Order Number
Type: String
86 || maintenanceSalesOrderNumber 0..1 Maintenance Sales Order Number
Type: String
87 || maintenancePurchaseOrderNumber
0..1 Maintenance Purchase Order Number
Type: String
88 || replacementSerialNumber 0..1 Replacement Serial Number
Type: String
89 || product 1 Type: Object
90 ||| number 1 Product Number of the instance
Type: String
91 ||| description 1 Description
Type: String
92 ||| family 1 Family
Type: String
93 ||| group 1 Group
Type: String
2019 Cisco Systems, Inc. All rights reserved. Contract Admin Web Service V1 | 17
No Element Cardinality Specifications
94 ||| subType 1 Sub Type
Type: String
Instance/product/billTo
95 ||| billTo
96 |||| address1 0..1
Bill To Address 1
Type: String
97 |||| address2 0..1 Bill To Address 2
Type: String
98 |||| address3 0..1 Bill To Address 3
Type: String
99 |||| address4 0..1 Bill To Address 4
Type: String
100 |||| city 0..1 Bill To City
Type: String
101 |||| country 0..1 Bill To Country
Type: String
102 |||| postalCode 0..1 Bill To PostalCode
Type: String
103 |||| state 0..1 Bill To State
Type: String
104 |||| location 0..1 Bill To Address Unique Identifier
Type: String
105 |||| name 0..1 Bill To Party Name on the Invoice
Type: String
106 |||| orgId 0..1 Bill To Org ID
Type: Integer
107 |||| partySiteId 0..1 Bill To Party Site ID
Type: Integer
Instances/product/shipTo
108 ||| shipTo
109 |||| address1 0..1 Ship To Address 1
2019 Cisco Systems, Inc. All rights reserved. Contract Admin Web Service V1 | 18
No Element Cardinality Specifications
Type: String
110 |||| address2 0..1 Ship To Address 2
Type: String
111 |||| address3 0..1 Ship To Address 3
Type: String
112 |||| address4 0..1 Ship To Address 4
Type: String
113 |||| city 0..1 Ship To City
Type: String
114 |||| country 0..1 Ship To Country
Type: String
115 |||| postalCode 0..1 Ship To Postal Code
Type: String
116 |||| state 0..1 Ship To State
Type: String
117 |||| location 0..1 Ship To Address Unique Identifier
Type: String
118 |||| name 0..1 Ship To Party Name on the Invoice
Type: String
119 |||| orgId 0..1 Ship To Org ID
Type: Integer
120 |||| partySiteId 0..1 Ship To Party Site ID
Type: Integer
121 || itemType 0..1 Item Type
Type: String
instances/warranty
122 || warranty 1 Type: Object
123 ||| type 1 Warranty Type
Type: String
124 ||| status 1 Warranty Status
Type: String
2019 Cisco Systems, Inc. All rights reserved. Contract Admin Web Service V1 | 19
No Element Cardinality Specifications
125 ||| endDate 1 Warranty End Date
Format: Date-Time
126 || shipDate 0..1 Ship Date
Format: Date-Time
Instances/endUserGlobalUltimate
127 || endUserGlobalUltimate
128 |||| address1 0..1 Address 1
Type: String
129 |||| address2 0..1 Address 2
Type: String
130 |||| address3 0..1 Address 3
Type: String
131 |||| address4 0..1 Address 4
Type: String
132 |||| city 0..1 City
Type: String
133 |||| country 0..1 Country
Type: String
134 |||| postalCode 0..1 PostalCode
Type: String
135 |||| state 0..1 State
Type: String
136 |||| location 0..1 Address Unique Identifier
Type: String
137 |||| name 0..1 Party Name on the Invoice
Type: String
138 |||| orgId 0..1 Org ID
Type: Integer
139 |||| partySiteId 0..1 Party Site ID
Type: Integer
Instances/resellerGlobalUltimate
140 || resellerGlobalUltimate
2019 Cisco Systems, Inc. All rights reserved. Contract Admin Web Service V1 | 20
No Element Cardinality Specifications
141 ||| name 0..1 Party Name
Type: String
142 ||| id 0..1 Party Identification
Type: String
143 ||| address
144 |||| address1 0..1 Address 1
Type: String
145 |||| address2 0..1 Address 2
Type: String
146 ||| address3 0..1 Address 3
Type: String
147 |||| address4 0..1 Address 4
Type: String
148 |||| city 0..1 City
Type: String
149 |||| country 0..1 Country
Type: String
150 |||| postalCode 0..1 PostalCode
Type: String
151 |||| state 0..1 State
Type: String
152 |||| location 0..1 Address Unique Identifier
Type: String
153 |||| name 0..1 Party Name on the Invoice
Type: String
154 |||| orgId 0..1 Org ID
Type: Integer
155 |||| partySiteId 0..1 Party Site ID
Type: Integer
Instances/distributor
156 || distributor 0..1 Type = Object
2019 Cisco Systems, Inc. All rights reserved. Contract Admin Web Service V1 | 21
No Element Cardinality Specifications
157 ||| billToId 0..1 Bill To Identification
Type = String
158 ||| billToName 0..1 Bill To Name
Type = String
159 ||| billToAddress
160 |||| address1 0..1 Address 1
Type: String
161 |||| address2 0..1 Address 2
Type: String
162 |||| address3 0..1 Address 3
Type: String
163 |||| address4 0..1 Address 4
Type: String
164 |||| city 0..1 City
Type: String
165 |||| country 0..1 Country
Type: String
166 |||| postalCode 0..1 PostalCode
Type: String
167 |||| state 0..1 State
Type: String
168 |||| location 0..1 Address Unique Identifier
Type: String
169 |||| name 0..1 Party Name on the Invoice
Type: String
170 |||| orgId 0..1 Org ID
Type: Integer
171 |||| partySiteId 0..1 Party Site ID
Type: Integer
172 ||| billToGlobalUltimate
173 |||| name 0..1 Party Name
2019 Cisco Systems, Inc. All rights reserved. Contract Admin Web Service V1 | 22
No Element Cardinality Specifications
Type: String
174 |||| id 0..1 Party Identification
Type: String
175 |||| address
176 ||||| address1 0..1 Address 1
Type: String
177 ||||| address2 0..1 Address 2
Type: String
178 |||| address3 0..1 Address 3
Type: String
179 ||||| address4 0..1 Address 4
Type: String
180 ||||| city 0..1 City
Type: String
181 ||||| country 0..1 Country
Type: String
182 ||||| postalCode 0..1 PostalCode
Type: String
183 ||||| state 0..1 State
Type: String
184 ||||| location 0..1 Address Unique Identifier
Type: String
184 ||||| name 0..1 Party Name on the Invoice
Type: String
185 ||||| orgId 0..1 Org ID
Type: Integer
186 ||||| partySiteId 0..1 Party Site ID
Type: Integer
187 || ciscoCapitalBillToId 0..1 Bill to ID for Cisco Capital
Type = String
188 || takeOver 0..1 Type = Object
2019 Cisco Systems, Inc. All rights reserved. Contract Admin Web Service V1 | 23
No Element Cardinality Specifications
189 ||| isTakeOver 1 Is Take Over
True = Ownership of the contract moved to different party
Type: Boolean
190 ||| reason 0..1 Reason for Take Over
Type = String
191 || inactiveLine 1 Inactive Line
Null = Active Not Null = Inactive
Type = Object
192 ||| reason 0..1 Reason for Inactive
Only populated when inactiveLine is not null.
Type = String
2019 Cisco Systems, Inc. All rights reserved. Contract Admin Web Service V1 | 24
3.2 Move API The Move API enables you to perform site or product move through two transactions:
• Contract to contract • Site to site
3.2.1 Request Message
No Element Cardinality Specifications
1 transactionType 1
Transaction Type
Type: String Use: C2C – Contract to Contract S2S – Site to Site
Example: “transactionType”: C2C
2 transactionLevel 0 Transaction Level
Type: String
Use: SITE – Transaction at site level INSTANCE – Transaction at product level
Example: “transactionLevel”: SITE
3 contractLineSources 1 Contract Line Sources
Type: Array
4 | items 1 Type: Object
5 || sourceContractNumber
1 Source Contract Number
Original contract number before the move Type: String
Example: “sourceContractNumber”: 0
6 || sourceServiceLevel 0 Service Level of the item to be moved
Service levels: Technical Service, Software Service.
Type: String
Example: “sourceServiceLevel”: Technical Service
7 || instanceNumbers Required when: transactionLevel = INSTANCE
Type: Array
8 ||| items Instance Numbers to be moved
Type: String
9 || serialNumbers Required when: transactionLevel = INSTANCE
Type: Array
2019 Cisco Systems, Inc. All rights reserved. Contract Admin Web Service V1 | 25
No Element Cardinality Specifications
10 ||| items Serial Numbers to be moved
Type: String
11 || sourceSiteIds Required when: transactionLevel = SITE
Type: Array
12 ||| items Site ID to be moved
Type: String
13 || targetContractNumber
Required when: transactionType = C2C
Target Contract Number
Move old contract number to this new (target) contract number. Type: String
Example: “targetContractNumber”: “123456”
14 || targetSiteId Required when: transactionType = S2S
Target Site ID
Move old Site ID to this new (target) Site ID. Type: String
Example: “targetSiteId”: “123456”
3.2.2 Response Message
No Element Cardinality Specifications
1 transactionId 1 Transaction ID
Type: String
2 transactionStatus 1 Transaction Status
Type: String
3 transactionType 1 Transaction Type
Type: String
2019 Cisco Systems, Inc. All rights reserved. Contract Admin Web Service V1 | 26
3.3 Merge API Merge API enables you to merge all products within one or more contract onto another contract. This API
supports more than one contract per request.
3.3.1 Request Message
No Element Cardinality Specifications
1 mergeContractSources 1 Transaction Type
Type: Array
2 | items 1 Merge Information
One particular merge of the entire transaction.
Type: Object
3 || sourceContractNumbers 1 Type: Array
4 ||| items 1 Contract Numbers to be moved
Type: String
5 || targetContractNumber 1 Target Contract Number
Move old contract number to this new (target) contract number.
Type: String
Example: “targetContractNumber”: “123456”
3.3.2 Response Message
No Element Cardinality Specifications
1 transactionId 1 Transaction ID
Type: String
2 transactionStatus 1 Transaction Level
Type: String
3 transactionType 1 Transaction Type
Type: String
2019 Cisco Systems, Inc. All rights reserved. Contract Admin Web Service V1 | 27
3.4 Transaction Header API Transaction Header API enables you receive the header level information of a Merge or a Move Transaction.
3.4.1 Request Message When successfully called the Merge/Move API, the Transaction ID is returned to you in the response message.
You can call the Transaction Header API by submitting request to this URL:
https://api.cisco.com/ccw/renewals/api/v1.0/contract/transactions/{trxId}
Note: {trxID} = transactionID.
3.4.2 Response Message
No Element Cardinality Specifications
1 transactionId 1 Transaction ID
Type: String
2 transactionStatus 1 Transaction Level
Type: String
3 transactionType 1 Transaction Type
Specifies the transaction is either C2C – Contract to Contract S2S – Site to Site
Type: String
4 creationDate 1 Creation Date
Type: Date-Time
5 createdByUser 1 User Created
Type: String
6 lastupdatedDate 1 Last Updated Date
Type: Date-Time
7 lastUpdatedByUser 1 User Last Updated
Type: String
8 creationSource 1 Creation Source
Transaction creation source; either through API or UI.
2019 Cisco Systems, Inc. All rights reserved. Contract Admin Web Service V1 | 28
3.5 Transaction Line API Transaction Line API enables you receive the line level information of a Merge or a Move Transaction.
3.5.1 Request Message When call is successful to the Merge/Move API, the Transaction ID is returned to you in the response message.
You can call the Transaction Header API by submitting request to this URL:
https://api.cisco.com/ccw/renewals/api/v1.0/contract/transactions/{trxId}/line
Note: {trxID} = transactionID.
3.5.2 Response Message
No Element Cardinality Specifications
1 transactionLines 1 Transaction ID
Type: String
2 | items 1 Type: Object
3 || instanceNumber 1 Instance Number
Type: String
4 || serialNumber 1 Serial Number
Type: String
5 || sourceContractNumber
1 Source Contract Number
Type: String
6 || sourceSiteId 1 Source Site ID
Type: String
7 || sourceServiceLevel 1 Source Service Level
Type: String
8 || targetContractNumber
1 Target Contract Number
Type: String
9 || targetSiteId 1 Target Site ID
Type: String
10 || reasonCode 0…1 Reason Code
S#2C-Dwngrd w/o proof of pay, S#2C-Dwngrd w/proof of pay, S#2C-Upgrd w/o proof of pay, S#2C-Upgrd w/proof of pay, S#2C-Same/similar svc lvl, C2C-Dwngrd w/o proof of pay, C2C-Dwngrd w/proof of pay,
2019 Cisco Systems, Inc. All rights reserved. Contract Admin Web Service V1 | 29
No Element Cardinality Specifications
C2C-Upgrd w/o proof of pay, C2C-Upgrd w/proof of pay, C2C-Same/similar svc lvl
11 || caseNumber 1 Case Number
Type: String
12 || success 1 Success
Type: Boolean
True = success, False = failed
13 || errors 0…1 Type: Array
14 ||| items 1 Type: Object
15 |||| failureCode 1 Failure Reason
Type: String
16 |||| failureReason 1 Failure Reason
Type: String
17 totalTransactionLines 1 Total Transaction Line (regardless of pagination)
Type: Integer
2019 Cisco Systems, Inc. All rights reserved. Contract Admin Web Service V1 | 30
Appendix A: References Search API
Request - By Instance Number
Type: Sample Format: JSON
Response - By Instance Number
Type: Sample Format: JSON
Request
Type: Schema Format: JSON
Response
Type: Schema Format: JSON
Move API
Request
Type: Sample Format: JSON
Response
Type: Sample Format: JSON
Request
Type: Schema Format: JSON
Response
Type: Schema Format: JSON
Merge API
Request
Type: Sample Format: JSON
Request
Type: Schema Format: JSON
Transaction Header API
Response
Type: Sample Format: JSON
Response
Type: Schema Format: JSON
Transaction Line API
Response
Type: Sample Format: JSON
Response
Type: Schema Format: JSON
Others
Generate Token – IG Format: PDF
Cisco Hello API - IG Format: PDF
2019 Cisco Systems, Inc. All rights reserved. Contract Admin Web Service V1 | 31
Revision History
Rev No. Date Description Location Revised By
1.1 5 March 2019 Added two rows in HTTP Header table: 1. Request-ID 2. Accepted-Language
HTTP Header Tri Nguyen
1 25 January 2019 IG creation Tri Nguyen
2019 Cisco Systems, Inc. All rights reserved. Contract Admin Web Service V1 | 32
Glossary
API Application Program Interface
C2C Contract to Contract S2S Site to Site
CCO ID Cisco Connection Online User ID (Cisco.com)
CCWR Cisco Commerce Renewal
UI User Interface
WS Web Service
