Partner Web Services. Get License Service Manual

Transcription

1 Partner Web Services Get License Service Manual

2 Contents 1 Revision History Introduction Overview Supporting Resources Service Overview Service Endpoints Request/Response Schema Request Detailed Request JSON Structure Detailed Response JSON Structure Sample Requests/Responses Get License by Serial Number and Product Line Code Generic Error Formatting standards Error Messages Error codes Service Error codes a. Appendix: Serial Number Business logic b. Appendix: Asset status AUTODESK Get License v2 Service Reference Manual 2

3 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 Table 6: Application Error Codes Table 7: Business concepts Table 8: Asset status descriptions Figures Figure 1: Get License Service response structure... 6 Figure 2: Serial Number Business logic AUTODESK Get License v2 Service Reference Manual 3

4 1 Revision History Version Date Author Comments 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 Added appendix with Business logic information Mar 20, 2017 Jordi Gilabert Document Reformatting Added service endpoints table in section 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 Aug 11, 2017 Oscar Lopez Added License Status description under appendix b Added reference to appendix b on page Aug 14, 2017 Oscar Lopez Maximum S/N limit (Table 3) Asset Status description (Table 8) Aug 21, 2017 Jordi Gilabert Minor format changes Cross-references fixing AUTODESK Get License v2 Service Reference Manual 4

5 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. AUTODESK Get License v2 Service Reference Manual 5

6 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 Various Serial Numbers Number(s) passed in the Request. Serial Number and Product Line Code (separated Returns all products related with the Serial by a pipe char) Number(s) that match with the specific Product Various Serial Numbers and Product Line Codes Line Code(s) passed in the Request. (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: AUTODESK Get License v2 Service Reference Manual 6

7 contact_ address contact_first_name contact_last_name contract_term account_address 4 Service Endpoints Environment Staging QA Production URL Table 2: Service endpoints AUTODESK Get License v2 Service Reference Manual 7

8 5 Request/Response Schema 5.1 Request 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. Table 3: Detailed JSON Request Structure String - Free Text CIV3D AUTODESK Get License v2 Service Reference Manual 8

9 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. All String - Free Text 35 Please note that the status depends on the status of each individual event in the order. transaction_id M This field is used to indicate the transaction id of All String - Free Text 35 LIC the service, It is a unique value across all the services. Calculated as a combination of LIC, Serial number and time stamp message[ M - All Array - Object - { 0..N - - Object - contract_number O Contract/Agreement Number All String - Free Text 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 All String - Standard US Date format 10 06/05/17 contract_end_date O End date of the whole Contract holding this license. MM/DD/YYYY All String - Standard US Date format 10 06/05/17 contract_start_date O Start date of the whole Contract holding this license. MM/DD/YYYY All String - Standard US Date format 10 06/06/16 AUTODESK Get License v2 Service Reference Manual 9

10 group_number O Group number have no meaning in current All String - Free Text 50 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 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. All String - Free Text 255 license_behavior O NO,Flexlm Alias All String - LoV 30 Term Extendable Permanent Term / Term Multi-Flex Term Extendable Term Non-Extendable Term To Own Trial 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 H1-WW4315- L520 product_key O First 5 characters from SKU All String - Free Text H1 product_line M Product line All String - Free Text 100 autodesk 3dxmax AUTODESK Get License v2 Service Reference Manual 10

11 product_line_code O Product line code. All String - Free Text 40 3DSMAX In case of a collection item, collection will be identified as follows: AEC: AECCOL M&E: MECOLL PD: PDCOLL registered_date O Asset registered date All String - Standard 10 06/06/16 US Date format seats O Seat count All Number - Integer - 1 serial_number O Serial number of the asset All String - Free Text status O License status: Registered Active Unregistered Returned Upgraded Inactive Please see Appendix B for more info subscription_flag O True if the Contract start date matches the current date, else false usage_type O Commercial Product Education Market Ready Educational Product Entitlement Media Kit N/A Not For Resale listofmessages All String - Free Text 30 Upgraded All String - Free Text 10 FALSE All String - LoV 30 Commercial Product relationship_from{ O Parent Asset information All Object - relationship[ O - All Array - Object - { 1..N - - Object - group_name O - All String - Free Text 255 AUTODESK Get License v2 Service Reference Manual 11

12 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 serial_number O Serial number of the asset All String - Free Text 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 serial_number O Serial number of the asset All String - Free Text status O License status: Registered Active Unregistered Returned Upgraded Inactive All String - LoV 30 Registered } ] AUTODESK Get License v2 Service Reference Manual 12

13 } contact_ address O Contact address. Not returned when service triggered by Non- Reseller of Record. RoR only String - Free Text 100 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. contact_last_name M Contact last name RoR only String - Free Text 50 Devcontactone1 RoR only String - Free Text 50 Devcontactone2 Not returned when service triggered by Non- Reseller of Record. recent_activation_date O The most recent date of activating the license All String - Standard US Date format licensing_model O TERM EFLEX MFLEX TFLEX contract_term O A01 Annual A02 Monthly A03 Quarterly A04 Half Yearly A05 2-Year A06 3-Year Not returned when service triggered by Non- Reseller of Record. All String - LoV 30 TERM 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 Kian Trace, San Rafael, CA, 94903, United States } AUTODESK Get License v2 Service Reference Manual 13

14 { 0..N Error block. Will be returned only in the event of an internal Error. serial_number O Serial number sent in the request. - Object - All String - Free Text 12 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 AUTODESK Get License v2 Service Reference Manual 14

15 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: ACD { "status": "OK", "transaction_id": "LIC ", "message": [ { "ContractNumber": " ", "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": " ", "Deployment": "Standalone", "Description": "001F1-WWR Autodesk AutoCAD 2014 Non-Language Specific", "LicenseBehavior": "Permanent ", "LicenseType": null, "PartNumber": "001F1-WWR ", "ProductKey": "001F1", "ProductLine": "Autodesk AutoCAD", "ProductLineCode": "ACD", "RegisteredDate": "12/08/2014", "Seats": "1", "SerialNumber": " ", "Status": "Upgraded", "SubscriptionFlag": "true", "UsageType": "Commercial Product", "ListOfMessage": null, "RelationshipFrom": null, "RelationshipTo": { "Relationship": { AUTODESK Get License v2 Service Reference Manual 15

16 } ] } "ProductName": "Autodesk AutoCAD 2015 Global Non-Specific 2", "Seats": "25", "SerialNumber": " ", "Status": "Registered" } }, "SubscriptionProgramType": "Silver Subscription", "LicensingModel": null 6.2 Generic Error Error response when the Serial Number is not passed in the request: { "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: { "status": "Error", "transaction_id": null, "message": [ { "error_code": "UAN-GEN-00123", "error_message": "Serial Number may not exceed 12 characters. Please check your entry and try again" }] AUTODESK Get License v2 Service Reference Manual 16

17 Error response when the Serial Number has invalid characters: { "status": "Error", "transaction_id": null, "message": [ { "error_code": "UAN-GEN-00119", "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 ( ): { "status": "Error", "transaction_id": null, "message": [ { "error_code": "UAN-GEN-00119", "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: { "status": "OK", "transaction_id": null, "message": [ { "serial_number": " ", "error_code": "SOA-License-006", "error_message": "Serial Number not found in Autodesk Systems." }] } AUTODESK Get License v2 Service Reference Manual 17

18 7 Formatting standards UUID Version 4 Unique randomly generate string ISO 8601 YYYY-MM-DD date format ISO Two letter language code ISO alpha-2 format two letter country code form 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 Internal Message Error Code 200 OK 201 Created 304 Not Modified 400 Bad Request Error: 4000 Incorrect or malformed request Unauthorized Error: 4100 No CSN was passed in the request 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 AUTODESK Get License v2 Service Reference Manual 18

19 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 Please enter Serial Number. 400 Bad Request error UAN-GEN Serial Number may not exceed 12 characters. Please check your entry and try again. 400 Bad Request error UAN-GEN Serial Number has invalid characters. Please check your entry and try again 400 Bad Request error UAN-GEN Serial Number is not in valid format. Please check your entry and try again 400 Bad Request error UAN-LIC Number of Serial numbers should not exceed more than 20 in request. 400 Bad Request error UAN-GEN Product Line Code may not exceed 40 characters. Please check your entry and try again 400 Bad Request error UAN-GEN Product Line Code has invalid characters. Please check your entry and try again 400 Bad Request error UAN-LIC Duplicate Serial Numbers found in the request with Serial Number <<>> and Product line Code<>>combination 400 Bad Request error UAN-GEN System Issue Preventing Processing. Please Try Again Later. Table 6: Application Error Codes AUTODESK Get License v2 Service Reference Manual 19

20 a. Appendix: Serial Number Business logic Figure 2: Serial Number Business logic Item Agreement (or Subscription Contract) Product Industry Collection License Serial Number Description 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. 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. Selection of the most essential Autodesk software used in the different Industries that is licensed together. 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. 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 upgrade 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 AUTODESK Get License v2 Service Reference Manual 20

21 b. Appendix: Asset status Item Active Inactive Registered Unregistered Returned Upgraded Description Current asset that the customer can use. Asset is not under an open contract, customer does not have access to it The asset has a contract on it. Asset is purchased, but not yet registered. Purchase has been returned. Customer no longer has access to it. The product has been upgraded from another product or it was upgraded to the newest release. Table 8: Asset status descriptions AUTODESK Get License v2 Service Reference Manual 21