Partner Web Services Get License Service Manual Get License v2 Service Reference Manual 5 2...

Partner Web Services

Get License

Service Manual

AUTODESK Get License v2 Service Reference Manual 2

Contents 1 Revision History .................................................................................................................................... 4

2 Introduction .......................................................................................................................................... 5

2.1 Overview ....................................................................................................................................... 5

2.2 Supporting Resources ................................................................................................................... 5

3 Service Overview ................................................................................................................................... 5

4 Service Endpoints .................................................................................................................................. 7

5 Request/Response Schema ................................................................................................................... 8

5.1 Request ......................................................................................................................................... 8

5.1.1 Detailed Request JSON Structure .......................................................................................... 8

5.1.2 Detailed Response JSON Structure ....................................................................................... 9

6 Sample Requests/Responses .............................................................................................................. 15

6.1 Get License by Serial Number and Product Line Code................................................................ 15

6.2 Generic Error ............................................................................................................................... 16

7 Formatting standards .......................................................................................................................... 18

8 Error Messages.................................................................................................................................... 18

8.1 Error codes .................................................................................................................................. 18

8.2 Service Error codes ..................................................................................................................... 19

a. Appendix: Serial Number Business logic ............................................................................................. 20

b. Appendix: Asset status ........................................................................................................................ 21


Tables

Table 1: Request/Response behavior .................................................................................................................. 6

Table 2: Service endpoints ...................................................................................................................................... 7

Table 3: Detailed JSON Request Structure ........................................................................................................ 8

Table 4: Detailed JSON Response Structure .....................................................................................................14

Table 5: Authentication Error Codes .................................................................................................................. 18

Table 6: Application Error Codes ......................................................................................................................... 19

Table 7: Business concepts .................................................................................................................................. 20

Table 8: Asset status descriptions ...................................................................................................................... 21

Figures

Figure 1: Get License Service response structure............................................................................................. 6

Figure 2: Serial Number Business logic ............................................................................................................ 20


1 Revision History

Version Date Author Comments

2.1.3 Feb 17, 2017 Jordi Gilabert • Rewrote v2.1.2 version of Get

License v2 API

• Included response behavior based

on input parameters in section 3

• Updated input serial number and

product code formats in section

5.1.1

• Added appendix with Business

logic information

2.1.4 Mar 20, 2017 Jordi Gilabert • Document Reformatting

• Added service endpoints table in

section 4

2.1.5 Apr 25, 2017 Jordi Gilabert • Updated section 6.2 with examples

for all possible Business Errors

• Updated the description for the

Serial_Number field in the Error

group of the service response

(section 5.1.2)

• Updated Table 4 with column

“Visibility” indicating which

partners can see the returned

fields.

• Error block description updated in

Table 4

2.1.6 Aug 11, 2017 Oscar Lopez • Added License Status description

under appendix b

• Added reference to appendix b on

page 11

2.1.7 Aug 14, 2017 Oscar Lopez • Maximum S/N limit (Table 3)

• Asset Status description (Table 8)

2.1.8 Aug 21, 2017 Jordi Gilabert • Minor format changes

• Cross-references fixing


2 Introduction

2.1 Overview

Autodesk’s Partner Web Services is an automation solution for order placement directly from its partners

to Autodesk, all with low-touch from partners and zero-touch from Autodesk. This new business capability

enables true B2B web service transactions between partners and Autodesk.

For partners to effectively implement Autodesk’s web services, partner developers should be familiar with

REST web services, OAuth, and JSON.

2.2 Supporting Resources

Autodesk Partner Developer Portal: The Autodesk Partner Developer Portal offers a place for partner

developers to build and test their own applications by subscribing to Autodesk web services and helps

partners get connected with Autodesk. The Partner Developer Portal features a robust repository of

service documentation, provides an ongoing conduit to the services to support partner teams, and

features a community to allow partner developers to share insights and information with each other. A

partner administrator can invite and keep track of all the developers associated with the account and all

the details of the applications they submit. Developers can then explore the information related to a

service, understand the way the service works, and test the service to see how it works with their

applications. For more information, please visit Partner Developer Center.

Authentication API Documentation: This documentation guides partners through the process of

generating credentials, signatures, and access tokens necessary for utilizing service APIs. It also covers the

development of a partner’s integrating application. It provides basic information on web service

integration and demonstrates the development of a typical application. For more information, please

check the latest version of the API Authentication Guide.

3 Service Overview

GetLicense Service is an informational service designed to return license information based on the inputs

of serial number and/or product line code. Serial number is the mandatory input parameter and Product

line code is optional. A participating distributor or reseller, as a part of their own business process, can

submit to Autodesk a specific product serial number and have returned pertinent license information for

that product.

A single request message can ask for information about multiple serial numbers and up to 20 serial

numbers can be served with a single request.

https://partner.developer-qa.autodesk.com/products

https://partner.developer-qa.autodesk.com/products#auth-title


Partners can request License details by sending one of the following sets of request parameters:

Set of Request Parameters Type of Response

Serial Number Only Returns all products related with the Serial Number(s) passed in the Request. Various Serial Numbers

Serial Number and Product Line Code (separated by a pipe | char)

Returns all products related with the Serial Number(s) that match with the specific Product Line Code(s) passed in the Request. Various Serial Numbers and Product Line Codes

(separated by a pipe | char) Table 1: Request/Response behavior

Please note that when getLicense service is queried with a Serial Number tied to a Collection, response

will include as many items as products nested inside the Collection plus the Collection itself. The Collection

item will be identified based on the Product Line Code, as the service will return a “plain” structure

(Collection and related products will share the same root).

Figure 1: Get License Service response structure

This service can be invoked by Distributors and Resellers. When invoked by a Non-Reseller of Record,

following fields will not be returned:


• contact_emailaddress

• contact_first_name

• contact_last_name

• contract_term

• account_address

4 Service Endpoints

Environment URL

Staging https://enterprise-api-stg.autodesk.com/ddws/v2/license

QA https://enterprise-api-qa.autodesk.com/ddws/v2/license

Production https://enterprise-api.autodesk.com/ddws/v2/license Table 2: Service endpoints


5 Request/Response Schema

5.1 Request

5.1.1 Detailed Request JSON Structure

The following table explains the schema for the Request of the API service. Since this is a “GET” service, the parameters are sent as HEADER and

QUERY parameters.

* Please note that Bold elements denote Groups. Plain elements denote Input Fields.

Payload Structure Cardinality Description / Condition Data Type Length Example

serialnumber_productlinecode M The value of this field is used to query Autodesk systems for the requested license(s). Valid structures are:

• Serial Number only:

XXX-XXXXXXXX

• Serial Number and Product Line Code

(separated by a pipe char):

XXX-XXXXXXXX|AAAAA

• Various Serial Numbers:

XXX-XXXXXXXX, YYY-YYYYYYYY, …

• Various Serial Numbers and Product

Line Codes (separated by a pipe

char):

XXX-XXXXXXXX|AAAAA, YYY-

YYYYYYYY|BBBBB, …

• Serial number limit: 20 serial

numbers.

String - Free Text 255 712-30069452|CIV3D

Table 3: Detailed JSON Request Structure


5.1.2 Detailed Response JSON Structure

The following table explains the schema for the Response of the API service.

* Please note that Bold elements denote Groups. Plain elements denote Input Fields.

Payload Structure Cardinality Description / Condition Visibility Data Type Length Example

status M The status confirming if request event has started processing or encountered an error. Please note that the status depends on the status of each individual event in the order.

All String - Free Text 35

transaction_id M This field is used to indicate the transaction id of the service, It is a unique value across all the services. Calculated as a combination of “LIC”, Serial number and time stamp

All String - Free Text 35 LIC50770000001444078583

message[ M - All Array - Object -

{ 0..N - - Object -

contract_number O Contract/Agreement Number All String - Free Text 30 110001245365

asset_subscription_start_date

O Actual start date of this particular asset. MM/DD/YYYY

All String - Standard US Date format

10 06/06/16

asset_subscription_end_date

O Actual end date of this particular asset. MM/DD/YYYY


10 06/05/17

contract_end_date

O End date of the whole Contract holding this license. MM/DD/YYYY


10 06/05/17

contract_start_date

O Start date of the whole Contract holding this license. MM/DD/YYYY


10 06/06/16


group_number O Group number have no meaning in current state, this was legacy data. There might be existing old assets which might still carry legacy reference numbers.


euaccountame M End user account name All String - Free Text 100 Utywtorreyfadel

euaccount_number O End user account CSN All String - Free Text 30 5125008849

deployment

O • Autodesk Hosted

• Multi-Stand Alone

• Third Party Hosted

• Networked

• Package

• Session Specific Network

• StandAlone

String - LoV 250 Standalone

description O Product Description All String - Free Text 100 autodesk 3dxmax 2016 Non-

Language Specific

group_name O Group Name is used to group the products for a customer. This will be on request by customer.


license_behavior

O • NO,Flexlm Alias

• Permanent

• Term / Term Multi-Flex

• Term Extendable

• Term Non-Extendable

• Term To Own

• Trial

All String - LoV 30 Term Extendable

license_type

O • Autofulfilled

• Crossgrade

• Migration w/o old serial number

• New

• Upgrade

All String - LoV 30 New

part_number O SKU number All String - Free Text 50 128H1-WW4315-L520

product_key O First 5 characters from SKU All String - Free Text 30 128H1

product_line M Product line All String - Free Text 100 autodesk 3dxmax


product_line_code

O Product line code. In case of a collection item, collection will be identified as follows:

• AEC: AECCOL

• M&E: MECOLL

• PD: PDCOLL

All String - Free Text 40 3DSMAX

registered_date O Asset registered date All String - Standard US Date format

10 06/06/16

seats O Seat count All Number - Integer - 1

serial_number O Serial number of the asset All String - Free Text 12 712-10014268

status

O License status:

• Registered

• Active

• Unregistered

• Returned

• Upgraded

• Inactive Please see Appendix B for more info

All String - Free Text 30 Upgraded

subscription_flag O True if the Contract start date matches the current date, else false

All String - Free Text 10 FALSE

usage_type

O • Commercial Product

• Education Market Ready

• Educational Product

• Entitlement

• Media Kit

• N/A

• Not For Resale

All String - LoV 30 Commercial Product

listofmessages

relationship_from{ O Parent Asset information All Object -

relationship[ O - All Array - Object -

{ 1..N - - Object -

group_name O - All String - Free Text 255


product_name O Product Description All String - Free Text 100 autodesk 3dxmax 2016 Non-

Language Specific

seats O Number of seats All Number - Integer - 1


status

O License status:

• Registered

• Active

• Unregistered

• Returned

• Upgraded

• Inactive

All String - LoV 30 Upgraded

} - - - - -

] - - - - -

} - - - - -

relationship_to{ O New Asset information All Object -

relationship[ O - All Array - Object -

{ 1..N - - Object -

group_name O - All String - Free Text 255

product_name O Product Description All String - Free Text 100 autodesk 3dxmax 2015 Non-

Language Specific

seats O Number of seats All Number - Integer - 1


status

O License status:

• Registered

• Active

• Unregistered

• Returned

• Upgraded

• Inactive

All String - LoV 30 Registered

} - - - - -

] - - - - -


} - - - - -

contact_emailaddress

O Contact email address. Not returned when service triggered by Non-Reseller of Record.

RoR only String - Free Text 100 [email protected]

subscription_program_type

M • Gold Subscription

• Silver Subscription

All String - LoV 100 Silver Subscription

contact_first_name

M Contact first name Not returned when service triggered by Non-Reseller of Record.

RoR only String - Free Text 50 Devcontactone1

contact_last_name

M Contact last name Not returned when service triggered by Non-Reseller of Record.

RoR only String - Free Text 50 Devcontactone2

recent_activation_date O The most recent date of activating the license All String - Standard US Date format

10

licensing_model

O • TERM

• EFLEX

• MFLEX

• TFLEX

All String - LoV 30 TERM

contract_term

O • A01 Annual

• A02 Monthly

• A03 Quarterly

• A04 Half Yearly

• A05 2-Year

• A06 3-YearNot returned when service triggered by Non-Reseller of Record.

RoR only String - LoV 30 A02

account_address

O Account address. Not returned when service triggered by Non-Reseller of Record.

RoR only String - Free Text 100 93444 Kian Trace, San Rafael, CA, 94903, United

States

} - - - - -


{ 0..N Error block. Will be returned only in the event of an internal Error.

- Object -

serial_number O Serial number sent in the request. Only returned when the Serial Number has passed all the semantic validation (i.e. valid format) but a Business Error has occurred (i.e. the serial number is not found in the system)


error_code M Refer to section 8 for details All String - LoV 100

error_message M Refer to section 8 for details All String - Free Text 100

} - - - - -

] - - - - -

Table 4: Detailed JSON Response Structure


6 Sample Requests/Responses

Below some sample requests are provided as a reference. Please note that there are lots of other

combinations possible.

6.1 Get License by Serial Number and Product Line Code

The details of the expected fields in the request URL are located in the following table. The response for

this request is represented in the below screenshot:

https://enterprise-api-qa.autodesk.com/ddws/v2/license?serialnumber_productlinecode=339-80423258|ACD

{

"status": "OK",

"transaction_id": "LIC701765101435569265",

"message": [

{

"ContractNumber": "110000081291",

"AssetSubscriptionStartDate": "12/08/2014",

"AssetSubscriptionEndDate": "12/07/2015",

"ContractEndDate": "12/07/2015",

"ContractStartDate": "12/08/2014",

"EUAccountame": "RESn-Tech Data Prod MGT Commercial VAR",

"EUAccountNumber": "0070176510",

"Deployment": "Standalone",

"Description": "001F1-WWR111-1001 Autodesk AutoCAD 2014 Non-Language Specific",

"LicenseBehavior": "Permanent ",

"LicenseType": null,

"PartNumber": "001F1-WWR111-1001",

"ProductKey": "001F1",

"ProductLine": "Autodesk AutoCAD",

"ProductLineCode": "ACD",

"RegisteredDate": "12/08/2014",

"Seats": "1",

"SerialNumber": "339-80423258",

"Status": "Upgraded",

"SubscriptionFlag": "true",

"UsageType": "Commercial Product",

"ListOfMessage": null,

"RelationshipFrom": null,

"RelationshipTo": {

"Relationship": {


"ProductName": "Autodesk AutoCAD 2015 Global Non-Specific 2",

"Seats": "25",

"SerialNumber": "394-58797869",

"Status": "Registered"

}

},

"SubscriptionProgramType": "Silver Subscription",

"LicensingModel": null

}

]

}

6.2 Generic Error

Error response when the Serial Number is not passed in the request:

https://enterprise-api.autodesk.com/v2/license

{

"status": "Error",

"transaction_id": null,

"message": [ {

"error_code": "UAN-GEN-00108",

"error_message": "Please enter Serial Number"

}]

}

Error response when the Serial Number passed in the request exceeds 12 characters:

https://enterprise-api.autodesk.com/v2/license?serialnumber_productlinecode=561-429752451

{

"status": "Error",


"message": [ {


"error_message": "Serial Number may not exceed 12 characters. Please check your entry and try

again"

}]


Error response when the Serial Number has invalid characters:

https://enterprise-api.autodesk.com/v2/license?serialnumber_productlinecode=561-4297524X

{

"status": "Error",


"message": [ {


"error_message": "Serial Number has invalid characters. Please check your entry and try again"

}]

}

Error response when the Serial Number is not in a valid format (123-12345678):

https://enterprise-api.autodesk.com/v2/license?serialnumber_productlinecode=561042975241

{

"status": "Error",


"message": [ {


"error_message": "Serial Number is not in valid format. Please check your entry and try again"

}]

}

Error response when the Serial Number is not found in the system:

https://enterprise-api.autodesk.com/v2/license?serialnumber_productlinecode=561-42975245

{

"status": "OK",


"message": [ {

"serial_number": "561-42975245",

"error_code": "SOA-License-006",

"error_message": "Serial Number not found in Autodesk Systems."

}]

}


7 Formatting standards

UUID Version 4 – Unique randomly generate string

https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_.28random.29

ISO 8601 – YYYY-MM-DD date format

http://www.iso.org/iso/home/standards/iso8601.htm

ISO 639-1 - Two letter language code

http://www.iso.org/iso/home/store/catalogue_tc/catalogue_detail.htm?csnumber=22109

ISO 3166-1 alpha-2 format – two letter country code form

http://www.iso.org/iso/country_codes

8 Error Messages

Prior to reaching Autodesk systems, the service validates the request for authorization of services and

authentication of the requester. Below is a list of error codes and their mapping to messages for scenarios

such as when a request is not authorized or if the requester is not authenticated.

8.1 Error codes

HTTP Status Code Autodesk Error Code

Internal Message

200 – OK

201 – Created

304 – Not Modified

400 – Bad Request Error: 4000 Incorrect or malformed request

401 - Unauthorized Error: 4100 No CSN was passed in the request

401 - Unauthorized Error: 4101 No HMAC Signature passed in the request

401 – Unauthorized Error: 4102 No HMAC Client ID passed in the request

401 – Unauthorized Error: 4103 No HMAC Timestamp passed in the request

401 – Unauthorized Error: 4104 No Authorization passed in the request

401 – Unauthorized Error: 4105 Invalid token

401 – Unauthorized Error: 4106 Something went wrong generating the token

403 – Forbidden Error: 4301 HMAC signature was passed, but not a correct one

403 – Forbidden Error: 4302 HMAC timestamp was passed, but not a correct one

403 – Forbidden Error: 4300 CSN was passed, but not a correct one Table 5: Authentication Error Codes

http://www.iso.org/iso/country_codes


8.2 Service Error codes

HTTP Status Code Status Code Message

200 – OK OK N/A Response JSON with required fields

200 – OK OK SOA-License-006 Serial Number not found in Autodesk Systems.

400 – Bad Request error UAN-GEN-00108 Please enter Serial Number.

400 – Bad Request error UAN-GEN-00123 Serial Number may not exceed 12 characters. Please check your entry and try again.

400 – Bad Request error UAN-GEN-00119 Serial Number has invalid characters. Please check your entry and try again

400 – Bad Request error UAN-GEN-00119 Serial Number is not in valid format. Please check your entry and try again

400 – Bad Request error UAN-LIC-00002 Number of Serial numbers should not exceed more than 20 in request.

400 – Bad Request error UAN-GEN-00123 Product Line Code may not exceed 40 characters. Please check your entry and try again

400 – Bad Request error UAN-GEN-00119 Product Line Code has invalid characters. Please check your entry and try again

400 – Bad Request error UAN-LIC-00001 Duplicate Serial Numbers found in the request with Serial Number <<>> and Product line Code<>>combination

400 – Bad Request error UAN-GEN-00122 System Issue Preventing Processing. Please Try Again Later.

Table 6: Application Error Codes


a. Appendix: Serial Number Business logic

Figure 2: Serial Number Business logic

Item Description

Agreement (or Subscription Contract) Defines the licenses purchased with Maintenance Subscription, Desktop Subscription or Cloud Service Subscription and the associated benefits as defined in the Autodesk Subscription Program offering, identifying a particular set of licenses associated with subscription.

Product Anything a customer or partner/reseller can order from Autodesk, including trial/lab software, finished software programs, software bundles, services, subscriptions, marketing materials, and applications.

Industry Collection Selection of the most essential Autodesk software used in the different Industries that is licensed together.

License Is the agreement applicable to many Autodesk products pursuant to which Autodesk grants its Customers the right to install, access, and use those products and associated services. Each License is tied to one single Serial Number.

Serial Number Unique numeric identifier of a licensed product. Each Serial Number is randomly generated at the time of a transaction, and is used to register, activate, and up-grade or cross-grade a product. For Industry Collections, Industry Collection item and all its corresponding Bundled Products while share the same Serial Number.

Table 7: Business concepts


b. Appendix: Asset status

Item Description

Active Current asset that the customer can use.

Inactive Asset is not under an open contract, customer does not have access to it

Registered The asset has a contract on it.

Unregistered Asset is purchased, but not yet registered.

Returned Purchase has been returned. Customer no longer has access to it.

Upgraded The product has been upgraded from another product or it was upgraded to the newest release.

Table 8: Asset status descriptions

Partner Web Services Get License Service Manual Get License v2 Service Reference Manual 5 2...

Documents

Transcript of Partner Web Services Get License Service Manual Get License v2 Service Reference Manual 5 2...