partner web services getorderstatus version 1 service manual

Partner Web Services

GetOrderStatus Version 1

Service Manual

AUTODESK GetOrderStatus Service Reference Manual 2

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

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

1.0.2 May 29, 2018 Jordi Gilabert Added M2S Error codes

Document re-format


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.

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

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


Figure 1: GetOrderStatus process flow

3 Service Endpoints

Environment URL

Staging https://enterprise-api-stg.autodesk.com/v1/orders/status/

Production https://enterprise-api.autodesk.com/v1/orders/status/ Table 1: Service endpoints


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


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 successfully. Please check section 4.2.1.1 for possible “status” values

String - processing

message M A detailed description of the status. Please check section 4.2.1.1 for possible messages

String - Free Text - Order is processing.

last updated M The last change of status for the order. String - Datetime ISO 8601 format

- 2016-07-14 13:02:42 UTC

Table 3: Detailed JSON Response Structure


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.

ACCEPTED Order was created successfully.

processing Order is created.

Export Control blocked on order submit to SAP

- - processing Order is under export control review.

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 *SL – Service Layer

- - accepted Order is accepted.

Table 4: GetOrderStatus responses for successful orders (v1 and v2)

(b) Order Failed (PlaceOrder v1)

Version 1 Event Message

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.

Order submission failure. {{0}} Please re-submit once error is corrected. (error code 73)


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).

Internal Server Error

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 processing error. Please contact Autodesk (error code 71)

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

Order processing error. Please contact Autodesk CASE#{{0}}

The request payload has an invalid primary account CSN for action add products.

Invalid Primary Account CSN. Please retry with a different CSN. Autodesk has encountered an error, please try again later. (error code 72)

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

Autodesk has encountered an error, please try again later. (error code 72)

SAP SNS failure message matches any of the below messages (see below mapping tables for context around numerical error codes):

CustomerMessageRecurring-011-



Order validation failure. Please correct errors and resubmit your order. (error code 74)















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)

(c) Order Failed (PlaceOrder v2)

Version 2 Event Message

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.

Order submission failure. {{0}} Please re-submit once error is corrected. (error code 73)

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).

Internal Server Error

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.

Order processing error. Please contact Autodesk CASE#{{0}}




















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)

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 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": "Order processing error. Please contact 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


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 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 7: Authentication Error Codes

partner web services getorderstatus version 1 service manual

Documents