Partner Web Services. GetMyPrice Service Manual

Transcription

1 Partner Web Services GetMyPrice Service Manual

2 Contents 1 Introduction Overview Supporting Resources Service Overview Benefits of GetMyPrice Service Service Endpoints Request/Response Schema Request Detailed Request JSON Structure Response Detailed Response JSON Structure Sample Requests/Responses GetMyPrice with Customer number, part number and date GetMyPrice with Customer number, part number, date and agreement number Generic Error applicable for all request types Formatting standards Error Messages System Error codes Service Error Codes Tables Table 1: Service endpoints... 7 Table 2: Detailed JSON Request Structure... 8 Table 3: Detailed JSON Response Structure... 9 Table 4: Authentication Error Codes Table 5: Application Error Codes AUTODESK GetMyPrice Service Reference Manual 2

3 Figures Figure 1: Price sync process... 6 Figure 2: Product sync process... 6 AUTODESK GetMyPrice Service Reference Manual 3

4 Revision History Version Date Author Comments 2.2 Oct 22, 2015 AR Added Revision History section 2.3 Nov 3, 2015 AR Corrected Utilization to display Optional instead of Mptional for the quantity field 2.4 Dec 22, 2015 AR Updated Response Messages 2.5 Mar 16, 2016 PL Updated Error Codes and Messages Aug 31, 2017 Jordi Gilabert API name format fixed Sep 1, 2017 Jordi Gilabert Full document re-format Oct 03, 2017 Oscar Lopez Removed all QA references AUTODESK GetMyPrice Service Reference Manual 4

5 1 Introduction 1.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. 1.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. 2 Service Overview The purpose of the GetMyPrice service is to allow for the following: Provide Disti/DVAR with their purchase price Provide non-direct Partners with SRP During order creation (via PlaceOrder), provide the price that the Partner is paying on that particular order (e.g. if adding to an existing contract, the price on the order may need to be pro-rated.) AUTODESK GetMyPrice Service Reference Manual 5

6 Figure 1: Price sync process Figure 2: Product sync process 2.1 Benefits of GetMyPrice Service A lightweight REST web service that can be consumed easily from any application via HTTP(s) connection. Provides correct pricing by Partner and SKU. Assists with order entry and validation Improves data quality by retrieving real time price information. AUTODESK GetMyPrice Service Reference Manual 6

7 3 Service Endpoints Environment Staging Production URL Table 1: Service endpoints 4 Request/Response Schema 4.1 Request The Request Schema for GetMyPrice has the following Fields as inputs. The fields customer_number, part_number and price_date must be included in a Partner s request, along with one of the following combinations of the remaining fields: None of them (quantity of 1 will be assumed) agreement_number (quantity of 1 will be assumed) opportunity_number (quantity of 1 will be assumed) quantity agreement_number, quantity opportunity_number, quantity AUTODESK GetMyPrice Service Reference Manual 7

8 4.1.1 Detailed Request JSON Structure The following table explains the schema for the Request of the API service. * Please note that Bold elements denote Groups. Plain elements denote Input Fields. Payload Structure Cardinality Description / Condition Data Type Length Example part_number O / M The SKU of the product String - Free Text J1-WW8695-T548 customer_number M CSN Number of the partner, who is calling the service String - Free Text opportunity_number O A code which would entitle the customer to a discount String - Free Text 10 A agreement_number O The agreement number of an order String - Free Text price_date M The date where the given price is valid. Has to be current or in the future. String - Date ISO 8601 format quantity O Assumed to be 1 if not provided Number - Integer 13 5 Table 2: Detailed JSON Request Structure 4.2 Response 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. AUTODESK GetMyPrice Service Reference Manual 8

9 Payload Structure Cardinality Description / Condition Data Type Length Example status_code M Status Code of the request Number - Integer Set to "200" if no error has product HTTP Error Code in case of error status M Status of the Request OK: Service returned successfully Error: An error was produced message M Static value set to "Price" if status is OK. Blank if status is Error String - LoV - OK Object - Price { - If status is Error, then error_code and error_message are returned error_code M The error code Please refer to Table 5 error_message M A short description of the error String - LoV - UAN-GEN String - Free Text - PartNumber not found Please refer to Table 5 } response M - Object - - { - If status is OK, then net_price, currency and - - formatted_net_price are returned net_price M The net price of the product(s) Number - Fraction currency M The 3 digit currency code as defined in ISO 4217 String - ISO Currency - USD Code formatted_net_price M The net price with the appropriate currency sign String - Free Text - $ } Table 3: Detailed JSON Response Structure AUTODESK GetMyPrice Service Reference Manual 9

10 5 Sample Requests/Responses Below some sample requests are provided as a reference. Please note that there are lots of other combinations possible. 5.1 GetMyPrice with Customer number, part number and date Request v1/sku/prices?part_number=057j1-ww8695-t548&customer_number= &price_date= &quantity=1 Response with no errors { } "status_code": 200, "status": "OK", "message": "Price", "response": { "net_price": 296.4, "currency": "USD", "formatted_net_price": "$296.40" } 5.2 GetMyPrice with Customer number, part number, date and agreement number Request v1/sku/prices?part_number=827i1-ww7097- T148&customer_number= &agreement_number= &price_date= &quantity=1 Response with no errors { "status_code": 200, "status": "OK", "message": "Price", "response": { "net_price": 296.4, AUTODESK GetMyPrice Service Reference Manual 10

11 } } "currency": "USD", "formatted_net_price": "$296.40" 5.3 Generic Error applicable for all request types { } "status_code": 400, "status": "Error", "message": { "error_code": "UAN-GEN-00108", "error_message": "PartNumber not found" }, "response": {} 6 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 7 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. AUTODESK GetMyPrice Service Reference Manual 11

12 7.1 System Error codes The following table shows the system error codes generated for any system issues in Autodesk environment and their respective error messages present in response messages: 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 4: Authentication Error Codes 7.2 Service Error Codes Table below lists the possible error codes returned by the GetMyPrice Service due to Business Logic or Data related errors: Error Code APG-DWS-INV- 002 UAN-GEN UAN-GEN UAN-GEN UAN-GEN UAN-GEN UAN-GEN Error Message Provided customer number is invalid. Customer number is required. Please enter SKU number Invalid Customer number. Please check your entry and try again Please provide a valid parameters combination Please provide the right parameters names Order number should be exact 10 characters. Please check your entry and try again Table 5: Application Error Codes AUTODESK GetMyPrice Service Reference Manual 12