Partner Web Services

PlaceOrder Version 1 Service Manual

Contents 1 Introduction ...... 8 1.1 Overview ...... 8 1.2 Supporting Resources ...... 8 2 Subscription to Autodesk...... 8 2.1 Recurring (auto-renew) ...... 9 2.2 Renewable ...... 9 3 Service Overview ...... 9 3.1 Order Fulfillment ...... 10 3.2 Order Revoke ...... 10 3.3 SNS Messaging ...... 10 3.4 GetOrderStatus Service ...... 11 4 Service Endpoints...... 11 5 Request/Response Schema ...... 11 5.1 Request ...... 11 5.1.1 Detailed Request JSON Structure ...... 12 5.2 Response ...... 24 5.2.1 High-Level Entity Relationship model ...... 24 5.2.2 Detailed Response JSON Structure ...... 25 6 Sample Requests/Responses ...... 27 6.1 Place an Initial Order ...... 27 6.2 Add Seats ...... 28 6.3 Add Products...... 29 6.4 Remove Seats...... 29 6.5 Remove Products ...... 30 6.6 Cancel Order ...... 31 6.7 Generic Error applicable for all request types ...... 31 7 Formatting standards ...... 31 8 Error Messages ...... 32

AUTODESK PlaceOrder v1 Service Reference Manual 2

8.1 System Error codes ...... 32 8.2 Service Error Code ...... 32

Tables

Table 1: Service endpoints ...... 11 Table 2: Detailed JSON Request Structure for Initial Orders ...... 17 Table 3: Detailed JSON Request Structure for Add Seats ...... 18 Table 4: Detailed JSON Request Structure for Add Product ...... 21 Table 5: Detailed JSON Request Structure for Removing Seats ...... 21 Table 6: Detailed JSON Request Structure for Removing Products ...... 22 Table 7: Detailed JSON Request Structure for Contract Cancellation ...... 22 Table 9: Detailed JSON Request Structure for Get Order Status ...... 23 Table 10: Detailed JSON Response Structure ...... 25 Table 11: Authentication Error Codes ...... 32 Table 12: Place Order v1 Application Error Codes...... 37

Figures

Figure 1: PlaceOrder v1 process flow ...... 10

AUTODESK PlaceOrder v1 Service Reference Manual 3

Revision History

Version Date Author Comments 2.8 AR • Added Section 4.2, 4.7, 5.2 and 5.2.1 – to include the Recurring Billing service 2.9 AR • Updated the previously named Recurring Billing service to Update Recurring Purchase Order and Request URL 3.0 AR • Modified action_name values of Order Fulfillment from “add_seat” and “add_product” to “add_seats” and “add_products” 3.1 AR • Modified Sample Request Message for Order Fulfillment, Initial Order under Section 5.1 to display a sample payload for Recurring subscription models. • Modified Sample Request Message for Order Fulfillment, Initial Order under Section 5.2 to display a sample payload for Renewable subscription models. • Modified Create Initial Order Request Schema under Section 4.1

3.2 AR • Added add_seats Request Schema under section 4.3 • Added add_products Request Schema under section 4.4 • Added renew Request Schema under section 4.5 • Modified initial_order Request Schema under section 4.2 • Added Section 5.3, 5.4, 5.5, 5.6, 5.7 to include Sample Messages for order fulfillment actions: add_seats, add_products and renew

3.3 AR • Updated the sample data from the Sample Messages under Section 5. • Updated “Renew” Request Schema under Section 4.5 to remove “subscription_id”.

AUTODESK PlaceOrder v1 Service Reference Manual 4

• Updated “initial_order” request schema under section 4.2 to remove “external_ref_number”.

3.4 AR • Modified request schema date examples to fit the ISO 8601 format • Updated possible “action_name” values for Order Revoke to remove products, remove seats, cancel and return. Note: return is not currently available. • Updated Order Revoke Request Schema under section 4.11 • Added Descriptions for Desktop Subscription Models under section 3.1 • Added “related_account_csn” to Add Seats Request Schema under section 4.3 • Removed “pricing_date” from Add Seats Request Schema under section 4.3 • Modified Error Codes in section 7.1

3.5 AR • Modified sections 4.2-4.5 to reflect the latest request schema • Modified section 4.9 from “po_number” to “reference number”

3.6 RL • Convert all fields named “quantity” to Integer. 3.7 RL • Substitute field ref_document with fields opportunity type and opportunity_number. 3.8 RL • Remove field order_date. • Indicate rules on contract_start_date

3.9 CC • Update Documentation for Status API response schema 3.10 CC • Update SNS to indicate availability for all PlaceOrder services 3.11 PL • Section 4.2 Removed comments from first_name, last_name, email, eu_first_name, eu_last_name, eu_email • Section 4.2 Changed from O to R for first_name, last_name, email, eu_first_name, eu_last_name, eu_email

AUTODESK PlaceOrder v1 Service Reference Manual 5

• Section 4.2 edited comment section to only “Provide If Known” for contact_csn, eu_contact_csn • Section 4.2 in comments section for all fields beginning with primary_account, related_account, eu_primary_account added “*Rules apply to Recurring Only”

3.12 PL • Section 4.2, 4.3, 4.4, 4.11 updated all Quantity fields must be a Positive Integer • Section 4.2,4.3, 4.4 updated email and eu_email fields to max characters 80 • Section 4.2, 4.4, 5.1 added Address_Line2 and Address_Line3 for Primary, Eu_Primary, and Related Account fields.

3.13 PL • Removed the following fields from sections 4.2, 4.3, 4.4, 4.5 and their corresponding response messages: item_end_date, contact_csn, eu_csn, contract_end_date, currency_code, eu_contact_csn • Added field descriptions for all fields in sections 4.2, 4.3, 4.4, 4.5. • Added a possible error message to 4.15

3.14 FX • Removed all occurrences of “Desktop Subscription” as this terminology is obsolete. • The duration of subscription was referred to as a “term”. • “Multiyear” is now changed to “multi- year” as it is now s generic term.

3.15 SJ • Added comment for primary_account_csn eu_primary_account_csn in section 4.2 and 4.4. CSN will supersede the address if both provided.

AUTODESK PlaceOrder v1 Service Reference Manual 6

3.16 FX • Changed the values “remove seats” and “remove products” to “remove_seats” and “remove_products” respectively. 3.17 SJ • Removing Renewables. 3.18 OL • Removed section 4.5 that makes reference to Renewables. 3.19 Jordi Gilabert • Minor changes. • Format fixing.

1.30.20 Jordi Gilabert • Added Error codes table 1.30.21 Jordi Gilabert • API Name format fixed 1.30.22 Jordi Gilabert • Full document re-format 1.3.23 Oscar Lopez • Removed all QA references 1.3.24 Jordi Gilabert • Removed Add Seats SKUs references 1.3.25 Jordi Gilabert • Fixed incorrect “renewable” references 1.3.26 Denny Bulcao • Grammar review 1.3.27 Jordi Gilabert • Removed “PO Update” action 1.3.28 Jordi Gilabert • “email” field length changed from 50 to 80

AUTODESK PlaceOrder v1 Service Reference Manual 7

1 Introduction

1.1 Overview

Autodesk 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 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. 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 the Partner Developer Center.

Authentication API Documentation: This documentation guides partners through the process of generating credentials, signatures, and access tokens necessary to utilize 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 Subscription to Autodesk

Subscription to Autodesk is a pay-as-you-go approach, with the option of a monthly, quarterly, annual or multi-year term selected by customers. There are two main models: Recurring (auto-renew) and Renewable.

AUTODESK PlaceOrder v1 Service Reference Manual 8

2.1 Recurring (auto-renew)

Under a recurring subscription model, a customer’s subscription is updated automatically, based on the term (monthly, quarterly, or annually) that the partner selected. The subscription is ongoing and is only cancelled when the customer explicitly requests it or changes the model of the subscription in question.

2.2 Renewable

When customers subscribe to a service under the renewable model, the subscription expires after the term selected (quarterly, annual, or multi-year) has passed. This same subscription can be renewed close to the end of term. In short, a renewable subscription has an end date associated to the subscription, whereas recurring does not have an end date. PlaceOrder v1 API only supports Recurring orders.

3 Service Overview

The PlaceOrder Service exposes two API resources for managing orders: /orders/fulfillment and /orders/revoke. These resources consist of operations that handle order creation, order cancellation, order returns, adding seats and products to existing agreements, as well as removing seats and products to existing agreements.

This document includes the various scenarios of the PlaceOrder service which are eligible for order generation or agreement modifications within the Autodesk environment. The details of the services included in the order fulfillment and order revoke process are below. Please note that PlaceOrder v1 only supports Auto-Renew (Recurring) orders management.

• Submitting new recurring orders • Adding seats to existing recurring agreements • Adding products to existing recurring agreements • Removing seats from existing recurring agreements • Removing products to existing recurring agreements • Returning a recurring agreement (Not currently available) • Cancelling a recurring agreement

AUTODESK PlaceOrder v1 Service Reference Manual 9

Figure 1: PlaceOrder v1 process flow

3.1 Order Fulfillment

The Order Fulfillment API resource handles the order creation, add seat, and add product operations. The add seat and add product operations are only for existing agreements.

3.2 Order Revoke

The Order Revoke API resource handles the order return operation for recurring orders, as well as the remove seat, remove product, and cancellation operations. Returns are only valid within the agreed-upon grace period. If the return is valid, the contract will be cancelled and the amount refunded. For the cancellation operation, the auto renewal behavior is terminated. The contract is still valid for the remainder of the term. The remove seat and remove product operations are only for existing agreements.

3.3 SNS Messaging

SNS Messaging is an optional service that Autodesk Partners can opt-in to, allowing them to receive alerts regarding any PlaceOrder Services. The Partner will receive an alert after the order transaction has completed. The message in the alert indicates the status of the transaction. It will indicate if the status is “Success” or “Failed”. SNS message is available for all PlaceOrder Scenarios for both recurring and renewal models. PlaceOrder v1 only supports Recurring (not Renewable)

AUTODESK PlaceOrder v1 Service Reference Manual 10

If subscribed to receive order fulfillment notifications, a Partner can choose one of the following three methods of delivery:

• Email • SMS Message • Endpoint

3.4 GetOrderStatus Service

The GetOrderStatus API resource returns the current status of a particular order given the reference number obtained from the PlaceOrder API response. Get Order Status API is supported for all PlaceOrder scenarios. In order to retrieve the status of the desired purchase order, the transaction id of the order must be provided.

4 Service Endpoints

Environment URL Staging https://enterprise-api-stg.autodesk.com/v1/orders/ Production https://enterprise-api.autodesk.com/v1/orders/ Table 1: Service endpoints

5 Request/Response Schema 5.1 Request

Based on the action_name field provided in the request body, different operations will be invoked. The expected action_name values are:

• Fulfillment o initial_order: Creates a new order o add_seats: Adds seats to an existing contract o add_products: Adds products to an existing contract • Revoke o remove_seats: Decreases the number of seats from an existing contract o remove_products: Deletes a product from an existing contract cancel: Completely cancels an existing contract

AUTODESK PlaceOrder v1 Service Reference Manual 11

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

5.1.1.1 Initial Order

Payload Structure Cardinality Description / Condition Data Type Length Example action_name M Event name, partner is going to perform on place String 20 initial_order order

For new orders, the value must be “initial_order” reseller_account_csn M The reseller is the partner who sells Autodesk String - Free Text 10 5124015625 products directly to the end users. As an example, a VAR (Value Added Reseller) receives a request from an end user and places its order by calling/emailing… a VAD(Value Added Distributer) which then calls PlaceOrder API to submit the request.

It is also possible (based on the partner type) that the VAR receives the request from the end user and then calls PlaceOrder API directly. In that case, reseller_account_csn is the CSN of this VAR. sold_to_csn O The CSN of the VAD (Value Added Distributer) or VAR String - Free Text 10 5124015625 (Value Added Reseller) calling this API. This value should be equal to the CSN value in the HTTP header. po_number M Purchase order number of the partner (VAR or VAD) String - Free Text 35 2016-11-25- calling this API directly. 5134398484148331 customer_po_number O Purchase order number of the VAR when the API is String - Free Text 35 2016-11-25- called by a VAD. If the API is called directly by the 5602253131677329 VAR, it is advised to be provided as empty contract_start_date O Start date of the contract. The value cannot be in the String - Date ISO 8601 10 2016-11-30 past but can be in the future. If it is in the future, format invoicing date will also be adjusted accordingly, meaning that the invoice will be generated on the

AUTODESK PlaceOrder v1 Service Reference Manual 12

start date.

Please note that the value of this field cannot be larger than 30 days from the date the API service is invoked.

If not provided, current date is used. po_date O Date on which partner raises the PO in their internal String - Date ISO 8601 10 2016-11-25 system (Can be system date or date in the past) format opportunity_type O Unique sales opportunity type created for an order String 1 A opportunity_number O Unique ID that references a sales opportunity that String 15 A-2076096 has been created for an order po_date O Date on which partner raises the PO in their internal String - Date ISO 8601 10 2009-12-25 system (Can be system date or date in the past) format po_number M Purchase order number to be given by requester to String 35 ORD1234 identify each order customer_po_number O PO number of the customer. String 35 5161261435161 end_user{ M End User represents the user who buys the software. Object - -

Please note that based on the provided information in that section, Autodesk may create new users in its CRM system or can use the existing one if any.

Before creating a new contact, all the data is validated. For example postal code, city. If the information is wrong or suspicious, Autodesk systems can suspend the order until a manual intervention is performed. This is called as Export Control. In that case, the invoice generation can be delayed until the block is removed first_name M Name of the contact person for this order String - Free Text 35 Noah

last_name M Surname of the contact person for this order String - Free Text 35 Smith

email M Email address of the contact person for this order String - Free Text 80 [email protected] om

AUTODESK PlaceOrder v1 Service Reference Manual 13

language O Language code if the end user. Defaults to English if String - ISO 2 Digit 2 EN not provided Language Code primary_account_csn O Primary Account(End User Account) represents the String - Free Text 10 5124011111 majority of the time the company for which the end_user is working and buys the products for. If an end_user buys a product as a private customer, then primary_account is the same of end_user.

If the CSN Number is known, it should be provided in this field. If not, following fields related to "primary_account_*" should be provided.

When name and address information is provided instead of an existing CSN, Autodesk checks if the user already exists and use it. If it does not exist, create a new end user in its CRM system. primary_account_name O Mandatory if primary_account_csn is not provided. String - Free Text 35 The sample company1 here primary_account_address_line_1 O Mandatory if primary_account_csn is not provided String - Free Text 35 111 McInnis Parkway

primary_account_address_line_2 O Mandatory if primary_account_csn is not provided String - Free Text 35

primary_account_address_line_3 O Mandatory if primary_account_csn is not provided String - Free Text 35

primary_account_address_city O Mandatory if primary_account_csn is not provided String - Free Text 35 San Rafael

primary_account_address_state O Mandatory if primary_account_csn is not provided String - Free Text 35 CA

primary_account_address_postal_c O Mandatory if primary_account_csn is not provided String - Free Text 35 94903 ode primary_account_address_country O Mandatory if primary_account_csn is not provided String - ISO 2 Digit 35 US _code Country Code related_account_csn O Represents Subscription Contract Manager (CM). String - Free Text 10 5124022222 Subscription Contact Role that has full Subscription Contract-related privileges within the Autodesk My Account (Subscription Center with previous name).

The CM can, therefore, name Software Coordinators and Users, assign download privileges, and access

AUTODESK PlaceOrder v1 Service Reference Manual 14

coverage and Subscription Renewal Reports. The CM also receives Subscription Renewal notices.

Majority of the time, CM is equal to primary_account, so the same information is provided.

If the CSN Number is known, it should be provided in this field. If not, following fields related to "related_account_*" should be provided.

When name and address information is provided instead of an existing CSN, Autodesk checks if the user already exists and use it. If it does not exist, create a new end user in its CRM system. related_account_name O Mandatory if related_account_csn is not provided. String - Free Text 35 The sample company2 here related_account_address_line1 O Mandatory if related_account_csn is not provided. String - Free Text 35 One Market, Ste. 500

related_account_address_line2 O Mandatory if related_account_csn is not provided. String - Free Text 35 -

related_account_address_line3 O Mandatory if related_account_csn is not provided. String - Free Text 35 -

related_account_address_city O Mandatory if related_account_csn is not provided. String - Free Text 35 San Francisco

related_account_address_state O Mandatory if related_account_csn is not provided. String - Free Text 35 CA

related_account_address_postal_c O Mandatory if related_account_csn is not provided. String - Free Text 35 94105 ode related_account_address_country_ O Mandatory if related_account_csn is not provided. String - ISO 2 Digit 35 US code Country Code } - - - - - line_items [ M Line Items contains the information about the Array - Object - - products to be purchased. Please note that, - All Line Items' term (annual, yearly) should be the same. - There is no partial order provisioning, if one of the items fails, the rest also fails

AUTODESK PlaceOrder v1 Service Reference Manual 15

{ 1..N - Object - -

subscription_id M Unique ID representing the order_item (product) for String - UUID version 4 36 eac3f62a-8e7b-4f65- recurring orders. Please note that this ID is later used bb82-d14be8b9be09 to add/remove seats or to cancel the product. part_number M SKU Number, which defines the product and its term String - Free Text 35 001H1-WW6287-T317

quantity M Seat count for the product. String - Free Text 13 4

net_amount M Price of the line item according to the seat count. String - Free Text 20 605.44

eu_first_name M First name of the Software Coordinator (Contact String - Free Text 40 Emma Person) eu_last_name M Last name of the Software Coordinator (Contact String - Free Text 40 Johnson Person) eu_email M Email of the Software Coordinator (Contact Person) String - Free Text 80 emma.johnson@nore ply.com eu_language M Preferred language for software coordinator for String - ISO 2 Digit 2 EN communications Language Code eu_country M Country Code of software coordinator String - ISO 2 Digit 2 US Country Code eu_primary_account_csn O eu_primary_account represents the Software String - Free Text 10 5124033333 Coordinator associated with this line_item(product). It can be different or the same of header level primary_account.

If the CSN Number is known, it should be provided in this field. If not, following fields related to "eu_primary_account_*" should be provided.

When name and address information is provided instead of an existing CSN, Autodesk checks if the user already exists and use it. If it does not exist, create a new end user in its CRM system. eu_primary_account_name O Mandatory if eu_primary_account_csn is not String - Free Text 35 The sample company2 provided. here eu_primary_account_address_line1 O Mandatory if eu_primary_account_csn is not String - Free Text 35 100 Commercial provided. Street

AUTODESK PlaceOrder v1 Service Reference Manual 16

eu_primary_account_address_line2 O Mandatory if eu_primary_account_csn is not String - Free Text 35 provided. eu_primary_account_address_line3 O Mandatory if eu_primary_account_csn is not String - Free Text 35 provided. eu_primary_account_address_city O Mandatory if eu_primary_account_csn is not String - Free Text 35 Manchester provided. eu_primary_account_address_stat O Mandatory if eu_primary_account_csn is not String - Free Text 35 NH e provided. eu_primary_account_address_coun O Mandatory if eu_primary_account_csn is not String - ISO 2 Digit 35 03101 try_code provided. Country Code eu_primary_account_address_post O Mandatory if eu_primary_account_csn is not String - Free Text 35 US al_code provided. } - - - - -

] - - - - -

Table 2: Detailed JSON Request Structure for Initial Orders

5.1.1.2 Add Seats

Payload Structure Cardinality Description / Condition Data Type Length Example action_name M Event name, partner is going to perform on place String 20 add_seats order

For new orders, the value must be “add_seats” po_number M Purchase order number of the partner (VAR or VAD) String - Free Text 35 2016-11-25- calling this API directly. 5134398484148331 po_date O Date on which partner raises the PO in their internal String - Date ISO 8601 10 2016-11-25 system (Can be system date or date in the past) format customer_po_number O Purchase order number of the VAR when the API is String - Free Text 35 2016-11-25- called by a VAD. If the API is called directly by the 5602253131677329 VAR, it is advised to be provided as empty net_amount M Sum of all the net_amount fields under the line items String - Free Text 20 212.5 below. That represents the total value of the order

AUTODESK PlaceOrder v1 Service Reference Manual 17

contract_number M The contract number of the product(s) where String - Free Text 12 712100114242 addSeat operation is being performed. opportunity_type O Unique sales opportunity type created for an order String 1 A

opportunity_number O Unique ID that references a sales opportunity that String 15 A-2076096 has been created for an order line_items [ M Line Items contains the information about the Array - Object - - products to be purchased. Please note that, - All Line Items' term (annual, yearly) should be the same. - There is no partial order provisioning, if one of the items fails, the rest also fails { 1..N - Object - -

subscription_id M Unique ID representing the order_item (product) for String - UUID version 4 36 eac3f62a-8e7b-4f65- which add seat operation will be performed. Please bb82-d14be8b9be09 note that this ID is initially created by the VAD or VAR with PlaceOrder-Initial Order request. part_number M SKU Number, which defines the product and its term String - Free Text 35 128H1-008694-T270

quantity M Seat number to add to the product. String - Free Text 13 4

net_amount M Price of the line item according to the seat count. String - Free Text 20 212.5

} - - - - -

] - - - - -

Table 3: Detailed JSON Request Structure for Add Seats

5.1.1.3 Add Product

Payload Structure Cardinality Description / Condition Data Type Length Example action_name M Event name, partner is going to perform on place String 20 add_products order

AUTODESK PlaceOrder v1 Service Reference Manual 18

For new orders, the value must be “add_products” po_number M Purchase order number of the partner (VAR or VAD) String - Free Text 35 2016-11-25- calling this API directly. 5134398484148331 po_date O Date on which partner raises the PO in their internal String - Date ISO 8601 10 2016-11-25 system (Can be system date or date in the past) format customer_po_number O Purchase order number of the VAR when the API is String - Free Text 35 2016-11-25- called by a VAD. If the API is called directly by the 5602253131677329 VAR, it is advised to be provided as empty net_amount M Sum of all the net_amount fields under the line items String - Free Text 20 212.5 below. That represents the total value of the order contract_number M The contract number of the product(s) where String - Free Text 12 712100114242 addSeat operation is being performed. opportunity_type O Unique sales opportunity type created for an order String 1 A opportunity_number O Unique ID that references a sales opportunity that String 15 A-2076096 has been created for an order line_items [ M Line Items contains the information about the Array - Object - - products to be purchased. Please note that, - All Line Items' term (annual, yearly) should be the same. - There is no partial order provisioning, if one of the items fails, the rest also fails { 1..N - Object - -

subscription_id M Unique ID representing the order_item (product) for String - UUID version 4 36 eac3f62a-8e7b-4f65- which add seat operation will be performed. Please bb82-d14be8b9be09 note that this ID is initially created by the VAD or VAR with PlaceOrder-Initial Order request. part_number M SKU Number, which defines the product and its term. String - Free Text 35 128H1-008694-T270

quantity M Seat number to add to the product. String - Free Text 13 4

net_amount M Price of the line item according to the seat count. String - Free Text 20 212.5

eu_first_name M First name of the Software Coordinator (Contact String - Free Text 40 Emma Person)

AUTODESK PlaceOrder v1 Service Reference Manual 19

eu_last_name M Last name of the Software Coordinator (Contact String - Free Text 40 Johnson Person) eu_email M Email of the Software Coordinator (Contact Person) String - Free Text 80 emma.johnson@nore ply.com eu_language M Preferred language for software coordinator for String - ISO 2 Digit 2 EN communications Language Code eu_country M Country Code of software coordinator String - ISO 2 Digit 2 US Country Code eu_primary_account_csn O eu_primary_account represents the Software String - Free Text 10 5124033333 Coordinator associated with this line_item(product). It can be different or the same of header level primary_account.

If the CSN Number is known, it should be provided in this field. If not, following fields related to "eu_primary_account_*" should be provided.

When name and address information is provided instead of an existing CSN, Autodesk checks if the user already exists and use it. If it does not exist, create a new end user in its CRM system. eu_primary_account_name O Mandatory if eu_primary_account_csn is not String - Free Text 35 The sample company2 provided. here eu_primary_account_address_line1 O Mandatory if eu_primary_account_csn is not String - Free Text 35 100 Commercial provided. Street eu_primary_account_address_line2 O Mandatory if eu_primary_account_csn is not String - Free Text 35 provided. eu_primary_account_address_line3 O Mandatory if eu_primary_account_csn is not String - Free Text 35 provided. eu_primary_account_address_city O Mandatory if eu_primary_account_csn is not String - Free Text 35 Manchester provided. eu_primary_account_address_stat O Mandatory if eu_primary_account_csn is not String - Free Text 35 NH e provided. eu_primary_account_address_coun O Mandatory if eu_primary_account_csn is not String - ISO 2 Digit 35 03101 try_code provided. Country Code eu_primary_account_address_post O Mandatory if eu_primary_account_csn is not String - Free Text 35 US al_code provided.

AUTODESK PlaceOrder v1 Service Reference Manual 20

} - - - - -

] - - - - -

Table 4: Detailed JSON Request Structure for Add Product

5.1.1.4 Remove Seats

Payload Structure Cardinality Description / Condition Data Type Length Example action_name M Event name, partner is going to perform on place String 20 remove_seats order

To remove seats, the value must be “remove_seats” contract_number M Contract number whose seat count of product(s) will String - Free Text 12 712100114242 be decreased line_items[ M Each product(s)' seat count under this line item will Array - Object - - be decreased { 1..N - JSON Object - -

subscription_id M Subscription ID of product whose seat count will be String - UUID version 4 36 04c9417a-24de-4db8- decreased 9a38-a941808df7e9 quantity M Number of seats that will be removed from the Number - Integer - 4 product } - - - - -

] - - - - -

Table 5: Detailed JSON Request Structure for Removing Seats

5.1.1.5 Remove Products

Payload Structure Cardinality Description / Condition Data Type Length Example

AUTODESK PlaceOrder v1 Service Reference Manual 21

action_name M Event name, partner is going to perform on place String 20 remove_seats order

To remove products, the value must be “remove_products” contract_number M Contract number whose product(s) will be removed String - Free Text 12 712100114242

line_items[ M Each product under this line item with a valid Array - Object - - subscription id will be removed from the contract { 1..N - JSON Object - -

subscription_id M Subscription ID of product that will be removed from String - UUID version 4 36 04c9417a-24de-4db8- the contract 9a38-a941808df7e9 } - - - - -

] - - - - -

Table 6: Detailed JSON Request Structure for Removing Products

5.1.1.6 Cancel Order

Payload Structure Cardinality Description / Condition Data Type Length Example action_name M Event name, partner is going to perform on place String 20 cancel order

To cancel orders, the value must be “cancel” contract_number M The contract number that will be cancelled String - Free Text 12 712100114242

csn M CSN Number of the Partner calling the API String - Free Text 10 5123888874

Table 7: Detailed JSON Request Structure for Contract Cancellation

AUTODESK PlaceOrder v1 Service Reference Manual 22

5.1.1.7 Get Order Status

Payload Structure Cardinality Description / Condition Data Type Length Example reference_number M Reference Number returned by the PlaceOrder String 40 5123454340- service when creating an initial order, adding seats, 705786004296- adding products, removing seats, removing products, 1450719941 cancelling contracts or updating the PO Number Table 8: Detailed JSON Request Structure for Get Order Status

AUTODESK PlaceOrder v1 Service Reference Manual 23

5.2 Response

5.2.1 High-Level Entity Relationship model

A note on Order Completion: When Autodesk systems receive a Partner's Order, basic validations for items like SKU, Agreement, and Price are done upfront in the Service layer of the PlaceOrder API Service. After this, a response is generated and sent to the Partner regarding the success or failure of the request with a reference number (comprising of a concatenation of CSN, Purchase Order number and timestamp). Making use of the Reference Number as input for the GetOrderStatus API will allow the Partner to view the status of the PO. Finally, Autodesk systems will update the status of the transaction from a processing status to a completed state once the Order in question is created in SAP.

The following figure represents the high-level response schema of the PlaceOrder service. For a detailed description of each item, please refer to the Detailed Response JSON Structure:

AUTODESK PlaceOrder v1 Service Reference Manual 24

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.

Payload Structure Cardinality Description / Condition Data Type Length Example status M Indicates the status of API call. String - LoV 35 OK

Possible values are: • OK • FAILED • Order Accepted message M This field contains the description of error, in case an String - Free Text 255 Add seat SKU cannot error occurs during the service call. be used for initial order request In the case of Get Order Status, contains a message describing the status of the order. reference_number O This field is the reference number unique to this String - Free Text 255 5123692463- service call. The value is later used to check the status 693452211- of order submission in order to understand if the 1480666311 order is completely processed or not.

This field is Mandatory and comes populated for the following operations: • Initial Order • Add Seats • Add Products • Remove Seats • Remove Products • Update PO Number last_updated O Time stamp of the last update on the order. String 2016-01-08 17:15:54 UTC This field is Mandatory and comes populated for the following operations: • Get Order Status Table 9: Detailed JSON Response Structure

AUTODESK PlaceOrder v1 Service Reference Manual 25

AUTODESK PlaceOrder v1 Service Reference Manual 26

6 Sample Requests/Responses

Sample requests are provided below as a reference. Please note that many other combinations are possible.

6.1 Place an Initial Order

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

Request

POST /v1/orders/fulfillment

{ "action_name": "initial_order", "reseller_account_csn": "5123560247", "po_number": "2017-03-21-3468859569612687", "customer_po_number": "2017-03-21-2146232547317246", "end_user": { "first_name": "jjokyoiybj", "last_name": "fghjjuphkm", "email": "oonhwvtett @ noreply.com", "language": "EN", "country": "TR", "primary_account_name": "yejrzegklb", "primary_account_address_line1": "vsctbzanpk ksuknupabdknykl", "primary_account_address_city": "Istanbul", "primary_account_address_state": "", "primary_account_address_postal_code": "34357", "primary_account_address_country_code": "TR", "related_account_name": "yejrzegklb", "related_account_address_line1": "vsctbzanpk ksuknupabdknykl", "related_account_address_city": "Istanbul", "related_account_address_state": "", "related_account_address_postal_code": "34357", "related_account_address_country_code": "TR" }, "line_items": [{ "subscription_id": "7c0c72db-bbdc-42b3-ad17-ffd5a1131f69", "part_number": "128H1-WW6287-T317", "quantity": 14, "net_amount": "2380.0", "eu_first_name": "jjokyoiybj", "eu_last_name": "fghjjuphkm", "eu_email": "oonhwvtett @ noreply.com", "eu_language": "EN", "eu_country": "TR",

AUTODESK PlaceOrder v1 Service Reference Manual 27

"eu_primary_account_name": "yejrzegklb", "eu_primary_account_address_line1": "vsctbzanpk ksuknupabdknykl", "eu_primary_account_address_city": "Istanbul", "eu_primary_account_address_state": "", "eu_primary_account_address_country_code": "TR", "eu_primary_account_address_postal_code": "34357" } ] }

Response with no errors

{ "status": "OK", "message": "Your order is being processed", "reference_number": "5123560247-2017-03-21-3468859569612687-1490087458" }

6.2 Add Seats

Below is a sample addition request for adding more seats to one product of an existing, recurring contract.

Request

POST /v1/orders/fulfillment

{ "action_name": "add_seats", "contract_number": "712100130773", "po_number": "2017-03-21-3131666620694248", "net_amount": "1360.0", "reseller_account_csn": "5123560247", "line_items": [{ "subscription_id": "7c0c72db-bbdc-42b3-ad17-ffd5a1131f69", "part_number": "128H1-007778-T275", "quantity": 8, "net_amount": "1360.0" } ] }

Response with no errors

{ "status": "OK", "message": "Your order is being processed", "reference_number": "5123560247-2017-03-21-3131666620694248-1490087544" }

AUTODESK PlaceOrder v1 Service Reference Manual 28

6.3 Add Products

Below is a sample addition request for adding one product to an existing, recurring contract.

Request

POST /v1/orders/fulfillment

{ "action_name": "add_products", "contract_number": "712100130773", "po_number": "2017-03-21-8950592107979473", "customer_po_number": "2017-03-21-6568667610309537", "net_amount": "1037.0", "line_items": [{ "subscription_id": "d48f28fb-68d3-4cbd-8148-8a8c1de3384d", "part_number": "225H1-WW6287-T317", "quantity": 4, "net_amount": "1037.0", "eu_first_name": "jjokyoiybj", "eu_last_name": "", "eu_email": "", "eu_primary_account_csn": "5126888993" } ] }

Response with no errors

{ "status": "OK", "message": "Your order is being processed", "reference_number": "5123560247-2017-03-21-8950592107979473-1490087598" }

6.4 Remove Seats

Below is a sample revoke request for removing seats from one product of an existing, recurring contract.

Request

POST /v1/orders/revoke?customer_number=5123560247

{ "action_name": "remove_seats", "contract_number": "712100130773", "line_items": [{

AUTODESK PlaceOrder v1 Service Reference Manual 29

"subscription_id": "d48f28fb-68d3-4cbd-8148-8a8c1de3384d", "quantity": 2 } ] }

Response with no errors

{ "status": "OK", "message": "Your order is being processed", "reference_number": "5123560247-823383156-1490087724" }

6.5 Remove Products

Below is a sample revoke request for removing one product from an existing, recurring contract.

Request

POST /v1/orders/revoke?customer_number=5123560247

{ "action_name": "remove_products", "contract_number": "712100130773", "line_items": [{ "subscription_id": "7c0c72db-bbdc-42b3-ad17-ffd5a1131f69" } ] }

Response with no errors

{ "status": "OK", "message": "Your order is being processed", "reference_number": "5123560247-8250863127-1490087667" }

AUTODESK PlaceOrder v1 Service Reference Manual 30

6.6 Cancel Order

Below is a sample revoke request to cancel an existing, recurring contract.

Request

POST /v1/orders/revoke

{ "action_name": "cancel", "contract_number": "712100130773", "csn": "5123560247" }

Response with no errors

{ "status": "OK", "message": "Your order is being processed", "reference_number": "5123560247-2664740582-1490087779" }

6.7 Generic Error applicable for all request types

{ "status": "FAILED", "message": "SKU does not exist", "reference_number": "5126091597-CON-Y000057-1505225488" }

7 Formatting standards

UUID Version 4 – Unique, randomly generated 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 PlaceOrder v1 Service Reference Manual 31

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 the Autodesk environment and the 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 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 10: Authentication Error Codes

8.2 Service Error Code

The table below lists the possible error codes returned by the PlaceOrder v1 Service due to Business Logic or Data related errors.

AUTODESK PlaceOrder v1 Service Reference Manual 32

Error Code Error Message Error Description Partner Action 0 ["System.NullPointerException: Argument Need to review Reach to cannot be null."] Autodesk Client Services Team. 12 Incorrect no: of Recurring SKU(s) The Recurring Bundle Reach to maintained for SKU [SKU Number] in used in the payload is Autodesk contract [Contract Number]. Account CSN not set up correctly in Client Services = [Account CSN] SAP. There might be a Team. SKU missing or too many SKU's in the bundle causing the issue 28 Material [SKU Number] has status: UR The Recurring Bundle Reach to used in the payload is Autodesk not set up correctly in Client Services SAP. The Bundle has Team. status UR 36 Material number(s) does not exist. Please The submitted bundle is Reach to refer to the contract number [Contract no longer active or has Autodesk Number]. been edited. Client Services Team. 42 Sales document [Sales Ordre] is currently Multiple transactions for Reach to being processed (by user TIBDDWS) the same order happen Autodesk Account [Account CSN] is currently at the same time or the Client Services blocked by user TIBACC order is being processed Team. for a batch job. TIBCO retried to submit the payload 3 times and it still failed due to being locked. 129 The transport zone 0000000008 is not The Ship To Account Partner needs defined for country JP Error Submitted is in a to change the different Country/GEO JSON request than the Sold to Party and re-send Country/GEO the order with different Ship To Address. GCSO needs to cancel the agreement created. 200 No customer master record exists for Account does not exist in Reach to customer [Customer CSN] SAP or is missing data Autodesk Client Services Team. 202 Postal code must have length X Postal Code is not set up Partner needs correctly to change the

AUTODESK PlaceOrder v1 Service Reference Manual 33

JSON request and re-send the order with different Ship To Address. GCSO needs to cancel the agreement created. 203 Postal code is longer than X characters Postal Code is not set up Partner must correctly submit a new payload with the correct Postal Code 219 Sales document was not changed Need to review Reach to Autodesk Client Services Team. 248 Error in SALES_ITEM_IN 000010 The Recurring Bundle Reach to used in the payload is Autodesk not set up correctly in Client Services SAP. There might be a Team. SKU missing or too many SKU's in the bundle causing the issue 331 Error in SALES_ITEM_IN 000020 The Recurring Bundle Reach to used in the payload is Autodesk not set up correctly in Client Services SAP. There might be a Team. SKU missing or too many SKU's in the bundle causing the issue 555 The sales document is not yet complete: The account used in the Reach to Edit data Account CSN = [Account CSN] submission is missing Autodesk some key data or is not Client Services set up correctly Team. 1001 DDWSException:[]: SKU [SKU Number] SKU (Product) not Reach to does not exist in SFDC available in SFDC. If Autodesk Service Layer sends Client Services wrong SKU (or not Team. available in SFDC) 1002 System.DmlException: Upsert failed. First A contact with different Reach to exception on row 1; first error: CSN is in JSON that is not Autodesk FIELD_CUSTOM_VALIDATION_EXCEPTION, present in SFDC (based Client Services A Contact with this email address already on CSN value) but having Team. exists.: [] same email address, so SFDC tries to create one

AUTODESK PlaceOrder v1 Service Reference Manual 34

with different CSN but same email and errors out 1003 UNABLE_TO_LOCK_ROW, unable to The record is locked for a Reach to obtain exclusive access to this record: [] DML in SFDC. It happens Autodesk when another user is Client Services trying to update the Team. record simultaneously in SFDC 1004 DDWSException:[]: Subscription Id already Subscription Id in the Partner needs exists request having to change the duplicates or JSON request Subscription Id already and re-send existing in SFDC the order with different Subscription ID numbers 1004 ["DDWSException:[]: Subscription Id Payload submitted a Partner must already exists"] Subs ID that has already submit a new been used payload with a new Subs ID 1005 Subscription Cancellation Failed *Any Generic Application Reach to error in SFDC for Autodesk RemoveSeat scenario Client Services Team. 1006 Subscription Cancellation Failed *Any Generic Application Reach to error in SFDC for Autodesk RemoveProduct scenario Client Services Team. 1007 *Any standard application exception *Any Generic Application Reach to error in SFDC for Autodesk AddSeat Scenario Client Services Team. 1008 Subscription Cancellation Failed *Any Generic Application Reach to error in SFDC for Autodesk Cancellation Scenario Client Services Team. 1009 ["DDWSException:[]: Cannot add seats for An asset has been Reach to a cancelled Product with Subscription Id cancelled and an Add Autodesk [Subscription ID]"] seat is submitted. Client Services Team. 1010 Record Currently Unavailable: The record Multiple transactions for Reach to you are attempting to edit, or one of its the same order happen Autodesk related records, is currently being at the same time or the Client Services modified by another user. Please try order is being processed Team. again. for a batch job. Service Layer retried to submit

AUTODESK PlaceOrder v1 Service Reference Manual 35

the payload 3 times and it still failed due to being locked. 1011 ["DDWSException:[]: Subscription Id Not An initial order was Partner must Found"] submitted and the Subs submit a new ID was sent to SFDC and order and do then SAP. SAP did not an add seat use the correct Subs ID against the sent from SFDC and new order created its own. It synced the incorrect Subs ID to Siebel. When Add Seat is placed, the GetAgreement Call from Siebel shows a different Subs ID than what is in SFDC. 2001 Generic error message to Service layer. Generic Application Reach to E.g., Null pointer exception, DML error in SFDC Autodesk Exception, etc. Client Services Team. 2002 ["DDWSException:[]: Account/Contact MAC call or Get Account Reach to CSN cannot be null"] Call is not returning the Autodesk Account Data correctly. Client Services There may be Account Team. data returning as null. 2003 REQUIRED_FIELD_MISSING, Required Short Name of an Reach to fields are missing: [Name]: [Name]"] Account was not created Autodesk and returned to Service Client Services Layer quick enough Team. during the MAC call. Returns Null instead 2004 tibco_order_submit failed with Service layer could not Reach to Net::ReadTimeout reach TIBCO for Order Autodesk Creation but SFDC Client Services agreements were Team. created 2005 ["DDWSException:[]: DML Error occurred Contact in Payload Reach to in Standard Asset creation :Insert failed. already exists in SFDC Autodesk First exception on row 0; first error: with no associated Client Services PRIVATE_CONTACT_ON_ASSET, Cannot Account. Tries to use Team. parent an asset to an unparented contact: contact but cannot. []"] 2006 ["DDWSException:[]: Reseller Account Reseller account does Reach to does not exist in SFDC"] not exist in SFDC Autodesk Client Services Team.

AUTODESK PlaceOrder v1 Service Reference Manual 36

2007 mac_service failed with Connection MAC failed before Reach to refused - connect(2) for "[IP Address]" agreement creation Autodesk port [Port Number] Client Services Team. 2008 mac_service failed with Net::ReadTimeout MAC failed before Reach to agreement creation Autodesk Client Services Team. BW-AE- BW-AE-100011 Connectivity issue Reach to 100011 between SAP and TIBCO Autodesk Client Services Team. BWENGINE- Input data invalid Account CSN = [Account CSN submitted in Reach to 100030 CSN] payload corresponds to Autodesk an account in Siebel Client Services longer than 40 Team. characters. Fails in SAP SAP-001 No error description or OrderNumber Order number was not Reach to returned by SAP returned from SAP to Autodesk TIBCO Client Services Team. UAN-GEN- The value in required field Error with TIBCO Reach to 00108 'RequestContext.PartnerSalesOrg' is null mapping Autodesk Account CSN = [Account CSN] Client Services Team. Table 11: Place Order v1 Application Error Codes

AUTODESK PlaceOrder v1 Service Reference Manual 37