Partner Web Services PlaceOrder Version 2 Service Manual · AUTODESK PlaceOrder v2 Service...

Partner Web Services

PlaceOrder Version 2

Service Manual

AUTODESK PlaceOrder v2 Service Reference Manual 2

Contents

1 Introduction .......................................................................................................................................... 6

1.1 Overview ....................................................................................................................................... 6

1.2 Supporting Resources ................................................................................................................... 6

2 Service Overview ................................................................................................................................... 7

2.1 Subscription to Autodesk .............................................................................................................. 7

2.1.1 Renewable Order Model ....................................................................................................... 7

2.1.2 Maintenance to Subscription (M2S) ..................................................................................... 8

3 Service Endpoints .................................................................................................................................. 8

4 Pilot Run and Go Live ............................................................................................................................ 8

5 Request/Response Schema ................................................................................................................. 10

5.1 Request ....................................................................................................................................... 10

5.1.1 High-Level Entity Relationship model ................................................................................. 10

5.1.2 Low-Level Entity Relationship model .................................................................................. 11

5.1.3 Detailed Request JSON Structure ........................................................................................ 12

5.2 Response ..................................................................................................................................... 20

5.2.1 High-Level Entity Relationship model ................................................................................. 20

5.2.2 Detailed Response JSON Structure ..................................................................................... 21

6 Sample Requests/Responses .............................................................................................................. 22

6.1 Initial Order ................................................................................................................................. 22

6.2 Additions – Add seats.................................................................................................................. 24

6.3 Additions – Add products............................................................................................................ 26

6.4 Renewals ..................................................................................................................................... 28

6.5 Maintenance-to-Subscription switch .......................................................................................... 30

7 Formatting standards .......................................................................................................................... 32

8 Error Messages.................................................................................................................................... 32

8.1 System Error codes ..................................................................................................................... 32

8.2 Service Error Codes ..................................................................................................................... 33


8.3 Asynchronous Error Codes .......................................................................................................... 36

Tables

Table 1: Service endpoints ..................................................................................................................................... 8

Table 2:Detailed JSON Request Structure for Initial Orders (Renewal) ....................................................13

Table 3:Detailed JSON Request Structure for Additions to existing Orders (Renewal) ........................ 15

Table 4:Detailed JSON Request Structure for Renew Orders ....................................................................... 16

Table 5:Detailed JSON Request Structure for M2S Orders .......................................................................... 18

Table 6: Account JSON Model .............................................................................................................................. 19

Table 7: Contact JSON Model................................................................................................................................ 19

Table 8: Detailed JSON Response Structure .................................................................................................... 21

Table 9: Authentication Error Codes .................................................................................................................. 33

Table 10: Application Error Codes ...................................................................................................................... 36

Figures

Figure 1: Request High-Level JSON Schema Model ....................................................................................... 10

Figure 2: Request Low-Level Entity Model ........................................................................................................ 11

Figure 3: Response High-Level JSON Schema Model ................................................................................... 20


Revision History

Version Date Author Comments

2.0.0 Jan 17, 2017 Abdullah Sahin • Initial version of PlaceOrder API v2

2.0.1 Mar 16, 2017 Jordi Gilabert • Updated the Low-Level entity

relationship Model in 5.1.2

• Changed transaction_id description

in 5.2.2

2.0.2 Mar 17, 2017 Jordi Gilabert • Removed Multi-Event examples

• Full document re-formatting

• Fixed all cross-references

2.0.4 Jun 30, 2017 Oscar Lopez • Removed Software coordinator

section from payload

2.0.5 Jul 20, 2017 Jordi Gilabert • Error codes updated in Section 8

2.0.6 Jul 25, 2017 Jordi Gilabert • Request Payloads updated

2.0.7 Aug 02, 2017 Shantnu Jain • Changed ‘serialNumber’ to ‘subscriptionReferenceNumber’

• Changed ‘subscriptionId’ to ‘partnerSubscriptionId’

2.0.8 Aug 03, 2017 Jordi Gilabert • Minor format changes

2.0.9 Aug 18, 2017 Jordi Gilabert • Updated links to DEVPortal documentation and API Authentication Guide, from QA to STG environment

• Updated low level entity relationship diagram

2.0.10 Aug 22, 2017 Jordi Gilabert • Fixed structure for ShipTo from Contact to Account

2.0.11 Aug 31, 2017 Jordi Gilabert • API Name format fixed

2.0.12 Oct 03, 2017 Oscar Lopez • Removed all QA references

2.0.13 Oct 24, 2017 Jordi Gilabert • Emphasize that Contract Manager

information is only needed for

existing contracts if has to be

updated


2.0.14 Nov 29, 2017 Jordi Gilabert • Country code max length set 2

characters to align with ISO code

max length.

2.0.15 Apr 3, 2018 Jordi Gilabert • Added M2S support

• Fixed cosmetic errors

2.0.16 May 22,2018 Shantnu Jain & Jordi Gilabert

• Removed field

switchToContractNumber from

section 5.1.3.4

• Added section 8.3 to refer to

GetOrderStatus Reference manual

2.0.17 July 30, 2018 Jordi Gilabert • Added support for multiple

additions in the same request in

Section 4

2.0.18 August 14, 2018 Jordi Gilabert • Updated M2S request fields’ order

for a better readability on section

5.1.3.4

• Updated valid contract term options

for M2S on section 5.1.3.4


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.

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

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


2 Service Overview

PlaceOrder Service exposes API resources for managing orders: /orders/fulfillment. While version 1 of this

service is intended to be used to manage Recurring (Auto-Renew) contracts and version 2 handles order

creation and management of Renewable orders. With this API, partners can create and also specify events

to add seats and products to existing active agreements or renew those that are going to expire.

This document will include various scenarios of the PlaceOrder v2 service which are eligible for order

generation or agreement modification within the Autodesk environment. The details of the services

included in the order fulfillment process can be found below:

• Submitting new renewable orders

• Adding seats to existing renewable agreements

• Adding products to existing renewable agreements

• Renewing an existing contract

• Switching from a Maintenance contract to a Subscription contract

When an Order Fulfillment request has been made, the API service performs basic validations for schema,

SKUs, contracts, and pricing details to ensure the data is valid fulfilling the order request. If the validations

are successful, the order will be queued for further processing and a response will be returned indicating

that the order is being processed. The response will contain a unique transaction ID as a reference to the

order and partners can query the status of their order by using Get Order Status service or, alternatively,

by SNS service which they can subscribe for order process event notifications.

2.1 Subscription to Autodesk

Subscription to Autodesk is a pay-as-you-go approach, with the option of quarterly, annually or multi-year

term selected by customers. PlaceOrder Version 2 provides API access to the Renewable Model only.

2.1.1 Renewable Order Model

When customers subscribe to a service under the renewable order model, the subscription will be active

for the term selected in their subscription (quarterly, annual, multi-year). The subscription can be

renewed 90 days prior to the end of the term through the renew event in the Order Fulfillment API.

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


2.1.2 Maintenance to Subscription (M2S)

Maintenance to Subscription (M2S) is a special offer designed to help customers on a maintenance plan

move to subscription.

• Maintenance plan: Autodesk Offering that is attached to a Perpetual License and offers updates,

upgrades and other select benefits

• Subscription plan: Autodesk Offering that allows a customer access to product(s), service(s),

upgrades and/or support for a specified term.

3 Service Endpoints

Environment URL

Staging https://enterprise-api-stg.autodesk.com/v2/orders/fulfillment

Production https://enterprise-api.autodesk.com/v2/orders/fulfillment Table 1: Service endpoints

4 Pilot Run and Go Live

Please note that the following features will not be available during the pilot run (Partners can still use

these fields in their requests, but their values will be ignored by Autodesk APIs.):

• Media Kit

• Fee SKUs/ETR

• Cloud Credits

• Cross Country Orders

• VPA/CQS

• User Packs

• Volume Purchase Order

• Promo Code

• Partner Line Item ID

Additionally, the service is only able to manage one-single event per request for a given contract (i.e. one

Initial Order OR one/various Additions for the same contract OR one contract Renewal OR one M2S

switch):

• Initial Order


o Create a new order with one/multiple products with one/multiple seats.

• Additions

o Add seats to one existing line of a contract

o Create a new line in an existing contract

o Add seats to different lines within the same contract

o Add seats to an existing line and create a new line within the same contract

o Any combination of the above (i.e. Add seats to 3 different lines and create 2 new lines)

• Renewal

o Renew one single contract

• Maintenance to Subscription

o Switch one Maintenance contract to a Subscription contract


5 Request/Response Schema

5.1 Request

5.1.1 High-Level Entity Relationship model

The following figure represents the high-level request schema of the PlaceOrder service. For a detailed

description of each item, please refer to Detailed Request JSON Structure:

Figure 1: Request High-Level JSON Schema Model


5.1.2 Low-Level Entity Relationship model

Figure 2: Request Low-Level Entity Model


5.1.3 Detailed Request JSON Structure

The following tables explain the schema for the Request of the API service.

For a better reading, the payloads are split based on the operation to be done:

• Initial Renewable Order

• Additions to an existing Renewable Order

• Renew a Renewable Order

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

5.1.3.1 Initial Order

Payload Structure Cardinality Description / Condition Data Type Length Example

action M Action to be performed by the service. For Initial orders its value has to be “Initial”

String - Free Text 35 “Initial” Other possible values for action are – “Initial”, “Add-On” and “Renewal”

endCustomer { M Default End Customer information for the order placed.

JSON Object - -

account {} M Default End Customer Account information for the order placed.

JSON Object Please refer to 5.1.3.4(a) (Account) for entity details.

- -

contractManager {} M Default Contract Manager for the order placed. JSON Object Please refer to 5.1.3.4(b) (Contact) for entity details.

- -

} - - - - -

shipTo {} M Default Ship to Account for the order placed. JSON Object

- -


Please refer to 5.1.3.4(a) (Account) for entity details.

reseller { M Default Reseller Account for the order placed. JSON Object - -

csn M Reseller CSN. String - Free Text 35 5930928324

} - - - - -

soldTo { M Default Sold To Account for the order placed. JSON Object - -

csn M The value should always be equal to the renewable CSN of the partner calling the API.

String - Free Text 35 5986958493

} - - - - -

poNumber M Partner Purchase Order number. String - Free Text 35 PO_20160239483343

customerPoNumber O Customer Purchase Order number. String - Free Text 35 PO_20160239424197

contractStartDate O Requested contract start date. This value can only be in the future and not longer than 1 month from the date order is placed.

String - Date ISO 8601 format

10 2016-01-22

opportunityNumber O Valid opportunities that can be applied to orders. String - Free Text 15 A-2845134

lineItems [ M List of product to be ordered. Array - JSON Object - -

{ 1..N One occurrence per product. JSON Object - -

partNumber M Initial Order SKU for renewable subscription. String - Free Text 18 128I1-WW3492-T000

partnerSubscriptionId M Should be a fresh value generated by the service caller. Formerly known as subscription Id.

String - UUID version 4 40 42e0e7d0-e7d7-408a-8471-bb2acc62fbc2

quantity M Number of seats. Number - Integer - 3

netPrice M Price for the line item. Please note that quantity is a factor for the pricing. Ex – If a customer has ordered 3 seats of a product and each seat is $110.14 then netPrice = 3*$110.14 = $330.42

String - Free Text 20 330.42

} - - - -

] - - - -

Table 2:Detailed JSON Request Structure for Initial Orders (Renewal)

https://en.wikipedia.org/wiki/ISO_8601

https://en.wikipedia.org/wiki/ISO_8601


5.1.3.2 Additions


action M Action to be performed by the service. For additions its value has to be “Add-On”

String - Free Text 35 “Add-On”

endCustomer { O Default End Customer information for the order placed.

JSON Object - -

contractManager {} O Default Contract Manager for the order placed. JSON Object Please refer to 5.1.3.4(b) (Contact) for entity details.

- -

} - - - - -

shipTo {} M Default Ship to Account for the order placed. JSON Object Please refer to 5.1.3.4(a) (Account) for entity details.

- -



} - - - - -




} - - - - -

poNumber M Partner Order number. String - Free Text 35 PO_20160239483644

customerPoNumber O Customer Order number. String - Free Text 35 PO_20160239428990

contractNumber M Contract number to which the product will be added and/or Contract number containing the product to which the additional seats will be added.



lineItems [ M List of products to be added or modified. Array - JSON Object - -


partNumber M Based on the operation:

String - Free Text 18 128I1-WW4421-T056


Add Product: Initial Order SKU Add Seat: Add Seat SKU

partnerSubscriptionId

O Required for Add Products. Should be a fresh value generated by the service caller. Formerly known as subscription ID

String - UUID version 4 40 89095390-7398-45ef-8f2f-41727552d55e

subscriptionReferenceNumber

O Required for Add Seats. Formerly known as serial number Serial number of the product to modify.

String - Free Text 40 563-04891896

Quantity M Number of seats. Number - Integer - 8

netPrice M Price for the line item. Please note that quantity is a factor for the pricing.


} - - - - -

] - - - - -

Table 3:Detailed JSON Request Structure for Additions to existing Orders (Renewal)

5.1.3.3 Renewal


action M Action to be performed by the service. For renewals its value has to be “Renewal”

String - Free Text 35 “Renewal”


JSON Object - -

contractManager {} O Contract Manager details should only be sent if there is a new Contract Manager for the particular contract. If the Contract Manager is unchanged, then there is no need for the partner to send the contract manager.

JSON Object Please refer to 5.1.3.4(b) (Contact) for entity details.

- -

} - - - - -

shipTo {} M Default Ship to Account for the order placed. JSON Object Please refer to 5.1.3.4(a) (Account) for entity details.

- -




} - - - - -




} - - - - -



contractNumber M String - Free Text 15 778734753442




partNumber M Renew SKU. String - Free Text 18 128I1-WW3497-T122

partnerSubscriptionId O Subscription ID of the product to renew. Formerly known as subscriptionID

String - UUID version 4 40 d3a274b0-3bb4-4f52-a39b-11163bb09b0f


M Subscription Reference Number of the product to renew. Formerly known as the serial number.



netPrice M Price for the line item. Please note that quantity is a factor for the pricing.


} - - - - -

] - - - - -

Table 4:Detailed JSON Request Structure for Renew Orders


5.1.3.4 Maintenance-to-Subscription Switch


action M Action to be performed by the service. For M2S its value has to be “Switch from Maintenance”

String - Free Text 35 “Switch from Maintenance”


JSON Object - -

contractManager {} O Contract Manager details should only be sent if there is a new Contract Manager for the particular contract. If the Contract Manager is unchanged, then there is no need for the partner to send the contract manager.

JSON Object Please refer to (b) (Contact) for entity details.

- -

} - - - - -

shipTo {} M Default Ship to Account for the order placed. JSON Object Please refer to (a) (Account) for entity details.

- -



} - - - - -




} - - - - -



switchFromContractNumber M Represents the existing maintenance agreement. String - Free Text 15 110123456789

contractTerm O String value of the unit of measurement the partner is ordering. Term is annual (1 year), 2 year, or 3 year

String - Free Text 15 Annual

opportunityNumber M Represents the maintenance renewal opportunity. This is a required field for M2S switches.

String - Free Text 15 A-2845443




partNumber M Renew SKU. String - Free Text 18 128I1-WW3497-T122


netPrice M Either the full price of the sku or the prorated price if it is add to existing contract.


partnerSubscriptionId O Subscription ID of the product to renew. Formerly known as subscriptionID

String - UUID version 4 40 d3a274b0-3bb4-4f52-a39b-11163bb09b0f

previousSubscriptions [ M Array of serial numbers to be switched. Array - JSON Object - -


M Subscription Reference Number of the product to renew. Formerly known as the serial number.


quantity O For future extension of this schema to support partial quantity but will not be validated for existing Switch Flow. As it is always assumed that all the quantity is switched with switch action.

Number - Integer - 7

]

} - - - - -

] - - - - -

Table 5:Detailed JSON Request Structure for M2S Orders


(a) Account


csn O - String - Free Text 10 5256678474

name O Mandatory if csn is not provided, ignored otherwise. String - Free Text 35 Partner Inc.

altName O Mandatory if csn is not provided, ignored otherwise. String - Free Text 35 -

addressLine1 O Mandatory if csn is not provided, ignored otherwise. String - Free Text 35 1 Parkway Road

addressLine2 O Optional if csn is not provided, ignored otherwise. String - Free Text 35 -

addressLine3 O Optional if csn is not provided, ignored otherwise. String - Free Text 35 -

city O Mandatory if csn is not provided, ignored otherwise. String - Free Text 35 San Jose

postalCode O Mandatory if csn is not provided, ignored otherwise. String - Free Text 35 94604

stateProvinceCode O Optional if csn is not provided, ignored otherwise. String - Free Text 35 CA

countryCode O Mandatory if csn is not provided, ignored otherwise. String - ISO 2 Digit Country Code

2 US

Table 6: Account JSON Model

(b) Contact


firstName M First name of the contact. String - Free Text 35 James

lastName M Last name of the contact. String - Free Text 35 Peterson

email M Email address of the contact. String - Free Text 35 [email protected]

countryCode O Country of the contact. String - ISO 2 Digit Country Code

2 US

language O Preferred language of the contact. String - ISO 2 Digit Language Code

35 EN

Table 7: Contact JSON Model


5.2 Response

5.2.1 High-Level Entity Relationship model

The following figure represents the high-level response schema of the PlaceOrder service. For a detailed

description of each item, please refer to Detailed Response JSON Structure:

Figure 3: Response High-Level JSON Schema Model


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


transactionId M The unique integer used in the request to identify the transaction.

String - UUID version 4 36 aed587eb-4ad3-4ec2-8083-822062d55a0b

status M The status confirming if request event has started processing or encountered an error. Possible values are:

• processing

• error

String - Free Text 10 processing

error O Error when processing the event, if any. JSON Object - -

{ - - - - -

code O Error code associated with error message. Please check section 8 for error codes and descriptions.


message O Human readable message explaining error Please check section 8 for error codes and descriptions.

String - Free Text 50 Enter a valid action

} - - - - -

Table 8: 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 Initial Order

Below sample request is for an initial renewable order with one product subscription.

Request

POST /v2/orders/fulfillment HTTP/1.1 Host: enterprise-api-stg.autodesk.com Authorization: Bearer EJHZpIWBkdQPecjwVhLylKGDOtMF Content-Type: application/json signature: eDHyiqdugOMZTJwcvXFlrb/YycqvIMfgBSKhWEptVoR= timestamp: 1481139061 CSN: 0013284960

{

"action": "Initial",

"endCustomer": {

"account": {

"name": "Padberg-Boyle",

"addressLine1": "9451 Lee Hwy",

"addressLine2": "Apt:617",

"city": "Fairfax",

"stateProvinceCode": "VA",

"postalCode": "22031",

"countryCode": "US"

},

"contractManager": {

"firstName": "Pearlie",

"lastName": "Christiansen",

"email": "[email protected]",

"language": "EN",

"countryCode": "US"

}

},

"shipTo": {

"name": "ABC End User",

"addressLine1": "123 Main Street",

"addressLine2": "Building A",

"city": "San Francisco",


"stateProvinceCode": "CA",


"countryCode": "US"

},

"reseller": {

"csn": "0070176510"

},

"soldTo": {

"csn": "0070176510"

},

"poNumber": "2017-08-01-9678071455770702",

"customerPoNumber": "2017-08-01-5521607100752069",

"lineItems": [{

"partNumber": "001I1-WW1518-T316",

"partnerSubscriptionId": "f2072540-4713-42c4-89bb-52bc6862db7a",

"quantity": 1,

"netPrice": "497.25"

}

]

}

Response with no errors

{

"transactionId": "b982c66e-0a02-4c7a-a920-f6d94a37888c",

"status": "processing"

}

Response with errors

{

"transactionId": "f23d640e-ed49-4f8b-83fb-d549c15aaef2",

"status": "error",

"error": {

"code": 43033,

"message": "Enter a valid price for Part Number 001I1-WW1518-T316"

}

}


6.2 Additions – Add seats

Below sample request is an addition request for adding more seats to one product of an existing

renewable contract.

Request


{

"action": "Add-On",

"endCustomer":{

"contractManager":{

"firstName":"John",

"lastName":"Smith",

"email":"[email protected]",

"language":"EN",

"countryCode":"US"

}

},

"shipTo":{

"name":"AB Devillers",

"addressLine1":"1482 spicetree circle",

"addressLine2":"Apt:203",

"city":"Fairborn",

"stateProvinceCode":"OH",

"postalCode":"45324",

"countryCode":"US"

},

"reseller":{

"csn":"0070176510"

},

"soldTo":{

"csn":"0070176510"

},

"customerPoNumber":"2017-08-01-9678071455779977",

"poNumber":"2017-08-01-9678071455776653",

"contractNumber":"712100035873",

"lineItems":[

{

"partNumber":"001I1-009113-T722",


"subscriptionReferenceNumber":"712-10050071",

"quantity":1,

"netPrice":"497.25"

}

]

}


{

"transactionId": "7ec0f98e-116f-4fea-81a4-25257c28dd39",


}


{

"transactionId": "9f387ef1-fd89-4e03-a70d-1f6394ecae45",

"status": "error",

"error": {

"code": "status_failed",

"message": "No asset on agreement for corresponding

subscriptionReferenceNumber 123-434343 in line items"

}

}


6.3 Additions – Add products

Below sample request is an addition request for adding one product to an existing renewable contract.

Request


{

"action": "Add-On",

"endCustomer":{

"contractManager":{

"firstName":"John",

"lastName":"Smith",

"email":"[email protected]",

"language":"EN",

"countryCode":"US"

}

},

"shipTo":{

"name":"AB Devillers",

"addressLine1":"1482 spicetree circle",

"addressLine2":"Apt:203",

"city":"Fairborn",

"stateProvinceCode":"OH",

"postalCode":"45324",

"countryCode":"US"

},

"reseller":{

"csn":"0070176510"

},

"soldTo":{

"csn":"0070176510"

},

"customerPoNumber":"2017-08-01-9678071455779977",

"poNumber":"2017-08-01-9678071455776653",

"contractNumber":"712100035873",

"lineItems":[

{

"partNumber":"834I1-WW1518-T316",

"partnerSubscriptionId":"36b91fc0-06ba-4ee2-a1f4-093268e7d8c6",


"quantity":1,

"netPrice":"211.75"

}

]

}


{

"transactionId": "466f482a-49cd-4e61-9d8f-88a3fa217a0f",


}


{

"transactionId": "112e5a87-6983-4512-b847-e13b2e9092e4",

"status": "error",

"error": {

"code": 43015,

"message": "Part Number 827I1-WW1060-T725 does not exist"

}

}


6.4 Renewals

Below sample request is a request for the renewal of a contract. The proper renew SKU should be used

by the caller.

Request


{

"action": "Renewal",

"endCustomer": {


"firstName": "John",

"lastName": "Smith",


"language": "EN",

"countryCode": "US"

}

},

"shipTo": {

"name": "rqrmnDdwsRenew Auto",

"addressLine1": "500 California st",

"addressLine2": "Omni building",

"city": "San Francisco",

"stateProvinceCode": "CA",


"countryCode": "US"

},

"reseller": {

"csn": "0070176510"

},

"soldTo": {

"csn": "0070176510"

},

"poNumber": "2017-08-01-9678071455771112",

"customerPoNumber": "2017-08-01-9678071455774556",

"contractNumber": "712100035873",

"opportunityNumber": "A-2010676",

"lineItems": [{

"partNumber": "001I1-006414-T772",


"subscriptionReferenceNumber": "712-10050071",

"quantity": 1,

"netPrice": "485.55"

}

]

}


{

"transactionId": "f30b6c7a-9585-41d1-9411-834d170acd95",


}


{

"transactionId": "7e937dbf-ab52-4a28-b7cf-74c4908d333a",

"status": "error",

"error": {

"code": 43001,

"message": "Unable to retrieve opportunity details"

}

}


6.5 Maintenance-to-Subscription switch

Below sample request is an M2S request for switching from a Maintenance to a Subscription contract.

Request


{

"action": "Switch from Maintenance",

"endCustomer": {


"firstName": "John",

"lastName": "Doe",


"language": "EN",

"countryCode": "US"

}

},

"shipTo": {

"name": "ABC Tech Ltd.",

"addressLine1": "500 California St",

"addressLine2": "Suite 1234 ",

" city ": " San Francisco ",

" stateProvinceCode ": " CA ",

" postalCode ": " 94104 ",

" countryCode ": " US "

},

" reseller ": {

" csn ": " 0000001234 "

},

" soldTo ": {

" csn ": " 0070123456 "

},

" poNumber ": " PO - 1234 ",

" customerPoNumber ": " CUST - PO - 1234 ",

" switchFromContractNumber ": " 110123456789 ",

" opportunityNumber ": " A - 1234567 ",

" lineItems ": [{

" partNumber ": " 001I1 - WW1518 - T316 ",

" partnerSubscriptionId ": " bf862027 - 257a - 4c7a - 9c5d - 69f3516de5d0 ",


" previousSubscriptions ": [{

" subscriptionReferenceNumber ": " 561 - 10123456 ",

" quantity ": " 7 "

}, {

" subscriptionReferenceNumber ": " 561 - 10345678 ",

" quantity ": " 9 "

}

],

" quantity ": " 16 ",

" netPrice ": " 777 "

}

]

}


{

"transactionId": "f30b6c7a-9585-41d1-9411-834d170acd95",


}


{

"transactionId": "7e937dbf-ab52-4a28-b7cf-74c4908d333a",

"status": "error",

"error": {

"code":,43007

"message": "Enter a valid contract number"

}

}


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

8.2 Service Error Codes

Table below lists the possible error codes returned by the PlaceOrder v2 Service due to Business Logic or

Data related errors:

Error Code Error Message Error Description

UAN-GEN-00108 Please enter Customer Number Customer Number with blank value

43001 Enter a valid <request body element> • Partner did not send a required entity/element for specified action (e.g. no Sold-To CSN provided by partner)

• Partner exceeded character length of the entity/element in the message

• Partner sent data in an incorrect format (e.g. sending a string when they were expected to send an integer, or sending dates in a format other than YYYY-MM-DD)

• Partner did not group certain elements together (e.g. partner opted to send end customer account details in lieu of an end customer CSN and are missing the account name)

43002 Request Body Missing Request message body is empty or blank

43003 Enter a valid action Action is not sent by partners or Action is not a valid name/scenario

43005 Invalid Part Number {{0}} for action • Part Number submitted by partner is not applicable to initial orders

• Part Number submitted by partner is not applicable to Add-On orders

• Part Number submitted by partner is not applicable to


Subscription Renewal or Maintenance Renewal orders

43006 Invalid line item offering combination Part Numbers submitted by partner are not the same subscription type (e.g. subscription renewal vs. maintenance renewal)

43007 Enter a valid contract number Contract Number submitted by partner does not exist in back office (e.g. Siebel, SFDC)

43008 SubscriptionReferenceNumber {{0}} is not active

Subscription Reference Number submitted by partner is not an active subscription

43009 SubscriptionReferenceNumber {{0}} does not exist on contract

Subscription Reference Number submitted by partner is not a subscription under the Contract Number submitted by partner

43010 Subscription Id {{0}} does not exist on contract

Subscription ID submitted by partner is not a subscription under the Contract Number submitted by partner

43011 Enter a valid Sold-To CSN Invalid Sold To CSN provided

43012 Enter a valid Sold-To CSN Partner CSN not provided by partner in HTTP request header (unlikely scenario, as CSN is used in upfront apigee validation)

43013 Contract Start Date cannot exceed 30 days from today's date

Contact Start Date submitted by partner can be at most be 30 days in the future from today's date

43015 Part Number {{0}} does not exist Part Number submitted by partner does not exist or is not present in cache

43016 Part Number {{0}} billing behavior is not supported

Part Number submitted by partner has a billing behavior that is not blank, renewal, or recurring

43017 Part Number {{0}} is not active Part Number submitted by partner is not released (a.k.a. incorrect Dchain Status) for that partner's Sales Org

43018 Subscription term must match for all line items

Part Numbers submitted by partner do not have the same term (e.g. Quarterly, Annual, Multi-Year)

43019 Subscription term must match between all line items and contract

Part Numbers submitted by partner do not have the same term (e.g. Quarterly, Annual, Multi-Year) & do not match with the Service Contract Number provided

43020 License model must match for all line items

Part Numbers submitted by partner do not have the same License Model (e.g. Term)


43021 License model must match for all line items and contract

Part Numbers submitted by partner do not have the same License Model & do not match with the Service Contract Number provided

43022 License usage type must match for all line items

Part Numbers submitted by partner do not have the same License Usage Type (e.g. COM)

43023 License usage type must match for all line items and contract

Part Numbers submitted by partner do not have the same License Usage Type & do not match with the Service Contract Number provided

43024 Billing behavior must match for all line items

Part Numbers submitted by partner do not have the same Billing Behavior (e.g. renewable, auto-renew)

43025 Billing behavior must match for all line items and contract

Part Numbers submitted by partner do not have the same billing behavior & do not match with the Service Contract's billing behavior

43026 Part Number {{0}} product line must match with subscription product line

Part Number submitted by partner to add seats is not the same product line as the subscription the seats are being added to

43027 Part Number {{0}} support level must match with subscription support level

Part Number submitted by partner to add seats is not the same subscription level as the subscription the seats are being added to

43028 Please submit another order for promotional items.

free month propries do not match

43029 Part Number {{0}} has a free month When modifying existing agreement. New skus can not have free months

43030 Reseller is not specialized for Part Number(s) {{0}}, {{0}}, …, {{0}}

Sku has Special Sales Program

43031 Unable to verify renewal opportunity line items

• No product list returned for opportunity

• Product list is empty

43032 Part Number {{0}} does not meet seat requirement

Seat count provided by partner for a given part number does not match the LPI opportunity seat threshold required for purchase

43033 Enter a valid price for Part Number {{0}} Price for line item submitted by partner does not match price records in cache

43035 Enter a valid Opportunity Number Opportunity Number submitted by partner either does not exist or the opportunity is in an invalid status (e.g. not Open, Ready for Order)

43036 Contract cannot be renewed Partner can no longer renew the service contract as it is past the grace


period (30 days after contract end date)

43037 Line items do not match opportunity line items to be renewed

Partner request line items are not in one-to-one with renewable line items in the renewal opportunity specified (where oppty line item renew flag is set to 'TRUE')

43038 SubscriptionReferenceNumber {{0}} quantity does not match opportunity line item quantity to be renewed

Partner has submitted a Subscription Reference Number to be renewed and the quantity they specified in their request message is not the quantity that is expected to be renewed

43039 Order has already been submitted Partner has submitted the same request/order to us and that previous order was created successfully

43040 Pricing not found for Part Number {{0}} Part Number provided by partner does not have pricing details for that partner's price list and price group

43041 Invalid Part Number {{0}} for subscription product line

Part Number submitted by partner does not match the product line of the subscription it is attempting to modify

43042 SubscriptionReferenceNumber {{0}} does not exist on subscription

Subscription ID generated and submitted by partner is not the Subscription ID that already exists on the Subscription Reference Number

43043 Subscription term must match for opportunity and contract

Opportunity submitted by partner does not have the same term (e.g. Quarterly, Annual, Multi-Year) as the Service Contract Number provided

43044 Product Line {{0}} on opportunity is missing in request

Partner did not send a part number for a corresponding LPI opportunity product to be purchased

50100 Internal Server Error • All unhandled exceptions

• Unable to connect to downstream service

Table 10: Application Error Codes

8.3 Asynchronous Error Codes

Once the Order has been placed, asynchronous validations are executed in the Autodesk backend.

Possible validations errors will be returned by the GetOrderStatus service. Please check the

PWS_GetOrderStatus_Service Reference Manual to find all possible error codes.

Date post:	20-Nov-2018
Category:	Documents
Upload:	dinhque
View:	217 times
Download:	0 times

Partner Web Services PlaceOrder Version 2 Service Manual · AUTODESK PlaceOrder v2 Service...

Documents