Partner Web Services GetOrderStatus Version 1 Service Manual
Contents 1 Introduction... 4 1.1 Overview... 4 1.2 Supporting Resources... 4 2 Service Overview... 4 3 Service Endpoints... 5 4 Request/Response Schema... 6 4.1 Request... 6 4.1.1 Detailed Request JSON Structure... 6 4.2 Response... 7 4.2.1 Detailed Response JSON Structure... 7 5 Sample Requests/Responses... 11 5.1 GetOrderStatus... 12 6 Formatting standards... 12 7 Error Messages... 13 7.1 Error codes... 13 Tables Table 1: Service endpoints... 5 Table 2: Detailed JSON Request Structure... 6 Table 3: Detailed JSON Response Structure... 7 Table 4: GetOrderStatus responses for successful orders (v1 and v2)... 8 Table 5: GetOrderStatus responses for failed orders (v1)... 10 Table 6: GetOrderStatus responses for failed orders (v2)... 11 Table 7: Authentication Error Codes... 13 Figures Figure 1: GetOrderStatus process flow... 5 AUTODESK GetOrderStatus Service Reference Manual 2
Revision History Version Date Author Comments 1.0.0 Nov 08, 2017 Jordi Gilabert Initial version of GetOrderStatus Service documentation 1.0.1 Nov 15, 2017 Shantnu Jain Formatted the document AUTODESK GetOrderStatus Service Reference Manual 3
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 GetOrderStatus is used along with PlaceOrder versions 1 and 2 to check what is the current status of an order request. It supports all PlaceOrder scenarios, for both Recurring and Renewable business models. To retrieve the status of a particular transaction, the reference id of that transaction is required. Since our PlaceOrder API is asynchronous, it takes 30-120 secs to process an order. GetOrderStatus API is intended to be used right after submitting any order related transaction. Order processing time may differ for each transaction but its recommended to loop with an interval of 30 secs until the GetOrderStatus API returns a successful or failed status. AUTODESK GetOrderStatus Service Reference Manual 4
Figure 1: GetOrderStatus process flow 3 Service Endpoints Environment Staging Production URL https://enterprise-api-stg.autodesk.com/v1/orders/status/ https://enterprise-api.autodesk.com/v1/orders/status/ Table 1: Service endpoints AUTODESK GetOrderStatus Service Reference Manual 5
4 Request/Response Schema 4.1 Request 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. Request Fields Cardinality Description / Condition Data Type Length Example reference number M Reference ID returned by the PlaceOrder service String 40 5123454340-705786004296- 1450719941 Table 2: Detailed JSON Request Structure AUTODESK GetOrderStatus Service Reference Manual 6
4.2 Response 4.2.1 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. Response Structure Cardinality Description / Condition Data Type Length Example status M The status to indicate if the order was processed String - processing successfully. Please check section 4.2.1.1 for possible status values message M A detailed description of the status. String - Free Text - Order is processing. Please check section 4.2.1.1 for possible messages last updated M The last change of status for the order. String - Datetime ISO 8601 format Table 3: Detailed JSON Response Structure - 2016-07-14 13:02:42 UTC AUTODESK GetOrderStatus Service Reference Manual 7
4.2.1.1 Response Statuses and Messages behavior The tables below contain all possible scenarios and the expected message the partner will receive when making a GetOrderStatus call. Consider that there can be multiple, unique scenarios that can be grouped into returning the same or similar partner-facing messages when reviewing the following error scenarios & messages. (a) Order Successful (PlaceOrder v1 and v2) Event Version 1 Version 2 Status Message Status Message SL* synchronous validations are done & until we receive SNS notification from TIBCO OK Order Processing processing Order is processing. TIBCO sends SNS notification when order is created. Export Control blocked on order submit to SAP SNS notification on ZSBL Sync from Tibco (New Final Status) Note: This will not happen until any Credit hold or Export Control Block is removed on Orders ACCEPTED Order was created successfully. processing Order is created. - - processing Order is under export control review. - - accepted Order is accepted. *SL Service Layer Table 4: GetOrderStatus responses for successful orders (v1 and v2) (b) Order Failed (PlaceOrder v1) Version 1 Event All up-front validation failures in Service Layer before the "processing" response is sent to the partner and is placed into the queue for order fulfillment. Message Order submission failure. {{0}} Please resubmit once error is corrected. (error code 73) AUTODESK GetOrderStatus Service Reference Manual 8
Ex. incorrect price, duplicate payload, invalid contract number, etc. All other errors encountered during up-front order validations that generates a hard failure in the Service Layer. Ex. Internal Server Errors (unable to connect to downstream services). Order fulfillment failed and a case is NOT created in Salesforce. Ex. the response sent back from Salesforce is in an invalid format and Service Layer is unable to interpret whether or not it is a success of failure Order fulfillment or creation failed, a case IS created in Salesforce, and it is logged as a possible retriable scenario. Ex. unable to receive a response from Salesforce, Salesforce is unavailable, Salesforce or TIBCO call times out after 60 seconds The request payload has an invalid primary account CSN for action add products. Hard failure and non-retriable scenario in Service Layer after an order is picked up from the queue for order processing. Ex. Internal Server Errors SAP SNS failure message matches any of the below messages (see below mapping tables for context around numerical error codes): CustomerMessageRecurring-011- CustomerMessageRecurring-022- CustomerMessageRecurring-036- SAP SNS failure message matches any of the below messages (see below mapping tables for context around numerical error codes): Internal Server Error Autodesk (error code 71) Autodesk CASE#{{0}} Invalid Primary Account CSN. Please retry with a different CSN. Autodesk has encountered an error, please try again later. (error code 72) Autodesk has encountered an error, please try again later. (error code 72) Order validation failure. Please correct errors and resubmit your order. (error code 74) Autodesk (error code 75) CustomerMessageRecurring-012- CustomerMessageRecurring-027- CustomerMessageRecurring-037- CustomerMessageRecurring-038- CustomerMessageRecurring-039- CustomerMessageRecurring-040- AUTODESK GetOrderStatus Service Reference Manual 9
CustomerMessageRecurring-041- CustomerMessageRecurring-042- CustomerMessageRecurring-043- CustomerMessageRecurring-044- CustomerMessageRecurring-045- SAP SNS failure message doesn't match any of the above messages (e.g. all unhandled exceptions). Table 5: GetOrderStatus responses for failed orders (v1) Autodesk (error code 71) (c) Order Failed (PlaceOrder v2) Version 2 Event All up-front validation failures in Service Layer before the "processing" response is sent to the partner and is placed into the queue for order fulfillment. Ex. incorrect price, duplicate payload, invalid contract number, etc. All other errors encountered during up-front order validations that generates a hard failure in the Service Layer. Ex. Internal Server Errors (unable to connect to downstream services). The request payload is not valid. Ex. Seats Cannot be Negative. Ex. The product you are trying to remove has already been removed/cancelled. Failed after maximum retries and case generated in SL and also logged in Autodesk as possible retriable scenario (Case number available). Ex. When SFDC response is not successful. Ex. Tibco order creation status is not 'received'. Order fulfillment or creation failed, a case IS created in Salesforce, and it is logged as a possible retriable scenario. Ex. unable to receive a response from Salesforce, Salesforce is unavailable, Salesforce or TIBCO call times out after 60 seconds. SAP SNS failure message matches any of the below messages (see below mapping tables for context around numerical error codes): Message Order submission failure. {{0}} Please resubmit once error is corrected. (error code 73) Internal Server Error Order validation failure. Please correct errors and resubmit your order. (error code 74) Autodesk (error code 71) Autodesk CASE#{{0}} Order validation failure. Please correct errors and resubmit your order. (error code 74) AUTODESK GetOrderStatus Service Reference Manual 10
CustomerMessageRecurring-011- CustomerMessageRecurring-022- CustomerMessageRecurring-036- SAP SNS failure message matches any of the below messages (see below mapping tables for context around numerical error codes): Autodesk (error code 75) CustomerMessageRecurring-012- CustomerMessageRecurring-027- CustomerMessageRecurring-037- CustomerMessageRecurring-038- CustomerMessageRecurring-039- CustomerMessageRecurring-040- CustomerMessageRecurring-041- CustomerMessageRecurring-042- CustomerMessageRecurring-043- CustomerMessageRecurring-044- CustomerMessageRecurring-045- SAP SNS failure message doesn't match any of the above messages (e.g. all unhandled exceptions). Table 6: GetOrderStatus responses for failed orders (v2) Autodesk (error code 71) 5 Sample Requests/Responses AUTODESK GetOrderStatus Service Reference Manual 11
Below some sample requests are provided as a reference. Please note that there are lots of other combinations possible. 5.1 GetOrderStatus Retrieve the Status of an order given its reference Id (transaction number) Request GET /v1/orders/status/90630f35-4d2e-49e5-8f2b-83ab92501e16 Response with no errors { } "status": "processing", "message": "Order is processing.", "last_updated": "2017-11-14 14:27:12 UTC" Response with errors { } "status": "FAILED", "message": " Autodesk (error code 71)", "last_updated": "2017-08-22 14:55:37 UTC" 6 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 AUTODESK GetOrderStatus Service Reference Manual 12
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. 7.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 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 7: Authentication Error Codes AUTODESK GetOrderStatus Service Reference Manual 13