Digital Distribution Web Services (DDWS) PlaceOrder - Service Manual

Transcription

1 Digital Distribution Web Services (DDWS) PlaceOrder - Service Manual

2 CONTENTS Revision History Introduction Overview Supporting Documentation Getting Started PlaceOrder Service Overview Subscription to Autodesk Renewable Order Fulfillment Order Revoke SNS Messaging Get Order Status PlaceOrder Service Reference Information Order Fulfillment Request Schema Create Initial Order Request Schema Add Seats Request Schema Add Products Request Schema Renew Update Purchase Order Request Schema Update Purchase Order Get Order Status Request Schema Get Order Status [ Initial Order Only] Order Revoke Request Schema Remove Seats, Remove Products, Order Cancellation Response Schema Create Initial Order Response Schema Update Purchase Order Response Schema Get Order Status Response Schema Remove Seat, Remove Product, Order Cancellation [ Only] Response Schema SNS notification Sample Messages Request Message Order Fulfillment, Initial Order, Subscription Model Response Message Order Fulfillment, Initial Order Request Message Order Fulfillment, Initial Order, Renewable Subscription Model Response Message Order Fulfillment, Initial Order Web Service Reference Manual

3 5.3 Request Message Order Fulfillment, Add Seats, Subscription Model Response Message Order Fulfillment, Add Seats, Subscription Model Request Message Order Fulfillment, Add Seats, Renewable Subscription Model Response Message Order Fulfillment, Add Seats, Renewable Subscription Model Request Message Order Fulfillment, Add Products, Subscription Model Response Message Order Fulfillment, Add Products, Subscription Model Request Message Order Fulfillment, Add Products, Renewable Subscription Model Response Message Order Fulfillment, Add Products, Renewable Subscription Model Request Message Order Fulfillment, Renew, Renewable Subscription Model Only Response Message Order Fulfillment, Renew, Renewable Subscription Model Only Request Message Update Purchase Order Response Message Update Purchase Order Request Message Get Order Status Response Message Get Order Status Request Message Order Revoke (Remove Seat, Remove Product, Order Cancellation) Response Message Order Revoke (Remove Seat, Remove Product, Order Cancellation) Request Message Order Revoke (Order Returns) Response Message Order Revoke (Order Returns) Request Message SNS Messaging Response Message SNS messaging Formatting standards Error Messages Error codes Error Message Web Service Reference Manual

4 Revision History Version Date Author Comments /21/2015 AR Added Section 4.2, 4.7, 5.2 and to include the Billing service /22/2015 AR Updated the previously named Billing service to Update Purchase Order and Request URL /28/2015 AR Modified action_name values of Order Fulfillment from add_seat and add_product to add_seats and add_products /03/2015 AR Modified Sample Request Message for Order Fulfillment, Initial Order under Section 5.1 to display a sample payload for 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 /05/2015 AR Added add_seats Request Schema under section 4.3 Added add_products Request Schema under section Web Service Reference Manual

5 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 /05/2015 AR Updated the sample data from the Sample Messages under Section 5. Updated Renew Request Schema under Section 4.5 to remove subscription_id. Updated initial_order request schema under section 4.2 to remove external_ref_number /09/2015 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 Web Service Reference Manual

6 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 /21/2015 AR Modified sections to reflect the latest request schema Modified section 4.9 from po_number to reference number /22/2016 RL Convert all fields named quantity to Integer /22/2016 RL Substitute field ref_document with fields opportunity type and opportunity_number /23/2016 RL Remove field order_date. Indicate rules on contract_start_date /26/2016 CC Update Documentation for Status API response schema 6 Web Service Reference Manual

7 3.10 2/26/2016 CC Update SNS to indicate availability for all place order services /4/16 PL Section 4.2 Removed comments from first_name, last_name, , eu_first_name, eu_last_name, eu_ Section 4.2 Changed from O to R for first_name, last_name, , eu_first_name, eu_last_name, eu_ 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 Only /31/16 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 and eu_ fields to max characters 80 Section 4.2, 4.4, 5.1 added Address_Line2 and Address_Line3 for Primary, Eu_Primary, 7 Web Service Reference Manual

8 and Related Account fields /4/16 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 Jul 2016 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 multiyear as it is now s generic term August 2016 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. 8 Web Service Reference Manual

9 1 Introduction 1.1 Overview The Digital Distribution Web Services (DDWS) comprise an automation solution for order placement directly from Partners to Autodesk, all with low touch from Partners and zero touch from Autodesk. The new business capability is the ability for true B2B web service transactions between our Partners and Autodesk. The submission of the order would be fully automated from the Partner to Autodesk and back to the end customer with no manual touch. For the Partner to have effective implementation of the Autodesk s DDWS, affiliates will need familiarity of REST web services, OAuth 2.0 and JSON. A sample client application in the Ruby language is provided within the Programming Guide document. This will help the developers of the affiliates to consume the DDWS API. 1.2 Supporting Documentation Authentication API Documentation: This document guides Partners through the process of generating credentials, signatures, and access tokens necessary for utilizing Service APIs. It also contains information for the development of a Partner s integrating application. It provides basic understanding of web service integration and demonstrates the development of a typical application. API Schema/Interface Details: This document contains payload information regarding all possible scenarios for Place Order, it can be used by Developers in order to generate sample requests by filling in the desired fields. For further information on Autodesk Web Services please refer to the Developer Portal, where all available documentation, and step-by-step guidance on how our services work can be found. 2 Getting Started As part of the onboarding process, Partners will be associated with a unique Customer Specific Number (CSN). The Partner will have their respective application registered with Autodesk. For more detail on the onboarding process please refer to the Autodesk Partner Developer Guide. 9 Web Service Reference Manual

10 3 PlaceOrder Service Overview The PlaceOrder Service exposes two API resources for managing orders: /orders/fulfillment, /orders/revoke. These resources consist of operations, which 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 will include 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 can be found below. Submitting new orders Adding seats to existing agreements Adding products to existing agreements Removing seats from existing agreements Removing products to existing agreements Returning a recurring agreement (Not currently available) Cancelling a recurring agreement 10 Web Service Reference Manual

11 3.1 Subscription to Autodesk Subscription to Autodesk is a pay-as-you-go approach, with the option of monthly, quarterly, annually or multi-year term selected by customers. There are two main models: and Renewables Under a recurring subscription model, customers given subscription is updated automatically, based on the term (monthly, quarterly or annually) which partner has selected. The subscription is never ending and it will only be cancelled when the customer explicitly requests it, or changes the model of the subscription in question Renewable When customers subscribe to a service under the renewable model, the subscription will expire after the term selected (quarterly, annual, multi-year) has passed. This same subscription can be renewed close to the end of term. In short, renewable subscription has an end date associated to the subscription whereas recurring does not have any end date. 3.2 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.3 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.4 SNS Messaging SNS Messaging is an optional service that Autodesk Partners can opt-in to, allowing them to receive alerts regarding any Place Order Services. The Partner will receive an alert after the order transaction has completed. The message in the alert will indicate the status of the transaction. It will display transaction will indicate if the status is Success or Failed. SNS message is available for all Place Order Scenarios for both recurring and renewal models. If subscribed to receive order fulfillment notifications, a Partner can choose one of the following three methods of delivery: o o SMS Message o Endpoint 11 Web Service Reference Manual

12 3.5 Get Order Status The Get Order Status API resource returns the current status of a particular order given the reference number obtained from the Place Order API response. Get Order Status API is supported for all Place Order services for both and Renewal scenarios. In order to retrieve the status of the desired purchase order, transaction id of the order will need to be provided. 4 PlaceOrder Service Reference Information Note: The following section contains Request & Response Schema for the PlaceOrder Service. The question of which fields are required or optional in each of the following schema is determined by a Partner s use of one of the two subscription models, Renewable or. At this point, Partners may not submit orders under a combination of and Renewable subscription models. Doing so will return an error response. 12 Web Service Reference Manual

13 4.1 Order Fulfillment Based on the action_name field provided in the request body, different operations will be invoked. For example, an action_name of initial_order will specify the create order option and add_seats will specify the add seat option. Below is the request schema for the cases where the request type is for order creation or for adding seats or products. The associated response schema is also included. The expected action_name values are as follows: initial_order, add_seats, add_products. 4.2 Request Schema Create Initial Order The details of the expected fields in the request body are located in the following table for Order Creation. We will require fields regarding end user, client, and product information. The highlighted rows are elements whose value is a JSON object or Array that contains the information in the rows indented below. Refer to the section of sample request messages for proper nesting of fields. If an account exists and the corresponding CSN is provided, then the customer details can be retrieved from Autodesk systems. If CSN is not provided, then partners must provide the information such as name, address, and location in order to create a new account. A note on Order Completion: When Autodesk systems receive a Partner's Initial 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. 13 Web Service Reference Manual

14 EndUserC ontact Contract Data Order Field Array Schema Definition Field Description Example Field Type Max Char Required/ Optional (R/O) Comments Renewal / action_name Event name, partner is going to perform on place order "initial_order" String 13 R initial_order opportunity_type Unique sales opportunity type created for an order A String 1 O Possible values are A (ACE) and R (Renewal). opportunity_number po_date po_number customer_po_number Unique ID that references a sales opportunity that has been created for an order Date on which partner raises the PO in their internal system (Can be system date or date in the past) Purchase order number to be given by requester to identify each order PO number of the customer. A String 15 O contract_start_date Contract start date Date ISO 8601 format When you provide one of opportunity_type and opportunity_number, you have to provide the other. 10 O ORD1234 String 35 R String 35 O Date ISO 8601 format 10 O When contract_start_date is given, the date must be within 30 days from the current date. When contract_start_date is not given, the date is the current date. end_user Array of JSON Object R first_name First name of the contract manager (Contact Person) "John" String 35 R 14 Web Service Reference Manual

15 last_name Last name of the contract manager (Contact Person) "Smith" String 35 R of the contract manager (Contact Person) joh.smith@sttest.com String 80 R Standard language Language preference of Contact Person EN String 2 O Defaults to English if not provided primary_account_csn End User Account CSN String 10 O Provide if known, otherwise fill in primary account details below. This will supersede if both are provided primary_account_name Account Name Partner Inc1 String 35 O primary_account_csn is not provided primary_account_address_li ne1 Account Address Line 1 1 Parkway Road String 35 O primary_account_csn is not provided primary_account_address_li ne2 primary_account_address_li ne3 primary_account_address_c ity primary_account_address_s tate Account Address Line 2 Engineering Dept. String 35 O Account Address Line 3 Desk 5405 String 35 O Account City San Jose String 35 O Account State "CA" String 35 O primary_account_csn is not provided primary_account_csn is not provided primary_account_csn is not provided primary_account_csn is not provided 15 Web Service Reference Manual

16 primary_account_address_c ountry_code primary_account_address_p ostal_code related_account_csn related_account_name related_account_address_li ne1 related_account_address_li ne2 related_account_address_li ne3 related_account_address_ci ty Account Country Code "US" String 35 O Account Postal Code String 35 O Account CSN to which contract manager is associated (could be same or different) Name of account to which contract manager is associated Related Account Address Line 1 Related Account Address Line 2 Related Account Address Line String 10 O Partner Inc String 35 O 1 Parkway Road String 35 O Engineering Dept. String 35 O Desk 5405 String 35 O Related Account City San Jose String 35 O primary_account_csn is not provided. 2 Digit ISO Code primary_account_csn is not provided Provide if known, otherwise fill in Related Account details below related_account_csn is not provided related_account_csn is not provided related_account_csn is not provided related_account_csn is not provided related_account_csn is not provided 16 Web Service Reference Manual

17 ListOfLineItems SoldToP arty Reseller Party related_account_address_st ate related_account_address_c ountry_code related_account_address_p ostal_code Related Account State "CA" String 35 O Related Account Country Code Related Account Postal Code "US" String 35 O String 35 O related_account_csn is not provided related_account_csn is not provided. 2 Digit ISO Code related_account_csn is not provided reseller_account_csn Related Account CSN String 10 R DL Partner sold_to_account_csn Sold To Account CSN String 10 O other_parties account_csn partner_type line_items subscription_id Account CSN of the party (e.g.: forwarding agent) Values to be entered is only 'ForwardingAgent" In case of recurring order, to uniquely identify each product line, a unique SUBS ID is to be generated per product line. The same subs. ID needs to be referenced whilst doing subsequent transactions like add seats for the same Array of JSON Object R Partner sold to CSN. If not provided it will take the authorization header value. Renewal String 10 R Renewal ForwardingAgent String 18 R Renewal "845cd4b7-2f20-4c1aaaa " Array of JSON Object R String 36 R UUID Version 4 format. 17 Web Service Reference Manual

18 product line for the same contract part_number SKU 001G1-WW7929-T210 String 35 R SKUNumber -> part_number quantity Quantity 1 Positive Integer net_amount Amount "39.33" String 20 R delivery_method eu_first_name Delivery method Value to be passed ED First name of the Software Coordinator (Contact Person) R ED String - R Renewal "Peter" String 40 R eu_last_name eu_ eu_language eu_country eu_primary_account_csn Last name of the Software Coordinator (Contact Person) of the Software Coordinator (Contact Person) Preferred language for software coordinator for communications Country Code of software coordinator Account CSN to which Software Coordinator is associated, in this scenario where for a given product line Software Coordinator is different to contract manager "longslide" String 40 R Peter.longslide@sttest.com String 80 R Standard: "EN" String 2 R 2 Digit ISO Code "US" String 2 R 2 Digit ISO Code String 10 O Provide if known, otherwise fill in eu_primary_account details below. This will supersede if both are provided 18 Web Service Reference Manual

19 eu_primary_account_name eu_primary_account_addre ss_line1 eu_primary_account_addre ss_line2 eu_primary_account_addre ss_line3 eu_primary_account_addre ss_city eu_primary_account_addre ss_state eu_primary_account_addre ss_country_code eu_primary_account_addre ss_postal_code Account name to which Software Coordinator is associated Software Coordinator Account Address Line 1 Software Coordinator Account Address Line 2 Software Coordinator Account Address Line 3 Software Coordinator Account City Software Coordinator Account State Software Coordinator Account Country Code Software Coordinator Account Postal Code Partner Inc1 String 35 O 1 Parkway Road String 35 O Engineering Dept. String 35 O Desk 5405 String 35 O San Jose String 35 O "CA" String 35 O "US" String 35 O String 35 O eu_primary_account_csn is not provided eu_primary_account_csn is not provided eu_primary_account_csn is not provided eu_primary_account_csn is not provided eu_primary_account_csn is not provided eu_primary_account_csn is not provided eu_primary_account_csn is not provided. 2 Digit ISO COde eu_primary_account_csn is not provided 19 Web Service Reference Manual

20 Now the payload can be of two types. If the primary account CSN, related account CSN or eu_primary_account_csn is known then you can create the payload as shown the enhanced version below Exisiting Initial Order Payload Enhanced Initial Order Payload 20 Web Service Reference Manual

21 4.3 Request Schema Add Seats Field Array Schema Definition Field Description Example action_name Event name, partner is going to perform on place order, like add seat. Field Type Max Char Required/ Optional (R/O) Comments Renewal / Recurrin g "add_seats" String 9 R "add_seats" contract_number Contract/Agreement number " " String 12 R po_date po_number Date on which partner raises the PO in their internal system (Can be system date or date in the past) Purchase order number to be given by requester to identify each order " " Date 10 O " " String 35 R customer_po_number PO number of the customer String 35 O contract_start_date Contract start date net_amount Total Amount (sum of amount in line items) Date ISO 8601 format 10 O "105.32" String 20 R When contract_start_dat e is given, the date must be within 30 days from the current date. When contract_start_dat e is not given, the date is the current date. Sum of all line_items Renewal reseller_account_csn Reseller Account CSN " " String 10 R Renewal 21 Web Service Reference Manual

22 line_items sold_to_account_csn Sold to Account CSN String 10 O opportunity_type opportunity_number Unique sales opportunity type created for an order Unique ID that references a sales opportunity that has been created for an order A String 1 O A String 15 O If not provided it will take the authorization header value. Possible values are A (ACE) and R (Renewal). When you provide one of opportunity_type and opportunity_numb er, you have to provide the other. Renewal line_items Array of JSON objects R subscription_id item_start_date In case of recurring order, to uniquely identify each product line, a unique SUBS ID is to be generated per product line. The same subs. ID needs to be referenced whilst doing subsequent transactions like add seats for the same product line for the same contract Date which billing start for this addition seat "914fadc9-2b67-476e-b480- e0e232e98745" String 36 R UUID version 4 formatted String " " Date 10 O Renewal part_number SKU "321K T979" String 35 R quantity Quantity 7 eu_ of Software Coordinator (contact person) Positive Integer "admin@autodesk.com" String 80 R Renewal R 22 Web Service Reference Manual

23 eu_first_name First name of the Software Coordinator (Contact Person) "John" String 40 R Renewal eu_last_name Last name of the Software Coordinator (Contact Person) "Smith" String 40 R Renewal net_amount Amount "105.32" String 20 R serial_numbers Serial Number [" "] Array of Strings R Net amount of per line_item Renewal 4.4 Request Schema Add Products Field Array Schema Definition Field Description Example Field Type Max Char Required/ Optional (O) Comments Renewal/Rec urring action_name Event name, partner is going to perform like add products "add_products" String 12 R "add_products" contract_number Contract/Agreement number " " String 12 R po_number net_amount po_date Purchase order number to be given by requester to identify each order Total Amount (sum of amount in line items) Date on which partner raises the PO in their internal system (Can be system date or date in the past) " " String 35 R "105.32" String 20 R " " Date 10 O Sum of all line_items Defaults to system Date 23 Web Service Reference Manual

24 line_items customer_po_number PO number of the customer String 35 O contract_start_date Contract start date Date ISO 8601 format 10 O When contract_start_date is given, the date must be within 30 days from the current date. When contract_start_date is not given, the date is the current date. Renewal reseller_account_csn Reseller Account CSN String 10 R Renewal sold_to_account_csn Sold To Account CSN String 10 O If not provided it will take the authorization header value. Renewal opportunity_type Unique sales opportunity type created for an order A String 1 O Possible values are A (ACE) and R (Renewal). opportunity_number Unique ID that references a sales opportunity that has been created for an order A String 15 O When you provide one of opportunity_type and opportunity_numbe r, you have to provide the other. line_items Array of JSON objects R 24 Web Service Reference Manual

25 subscription_id In case of recurring order, to uniquely identify each product line, a unique SUBS ID is to be generated per product line. The same subs. ID needs to be referenced whilst doing subsequent transactions like add seats for the same product line for the same contract "914fadc9-2b67-476e-b480- e0e232e98745" String 36 R UUID version 4 formatted String part_number SKU "321K T868" String 35 R quantity Quantity 7 item_start_date Date which billing start for this addition seat Positive Integer R " " Date 10 O Renewal eu_ of Software Coordinator (contact person) "admin@autodesk.com" String 80 R Renewal eu_first_name First name of the Software Coordinator (Contact Person) "John" String 40 R Renewal eu_last_name Last name of the Software Coordinator (Contact Person) "Smith" String 40 R Renewal end_user JSON object O first_name First name of the contract manager (Contact Person) "John" String 35 R last_name Last name of the contract manager (Contact Person) "Smith" String 35 R 25 Web Service Reference Manual

26 of the contract manager (Contact Person) String 80 R language Language preference of Contact Person EN String 2 O Defaults to English if not provided primary_account_csn End User Account CSN " " String 10 O primary_account_name Account Name "Arthur Doe" String 35 O Provide if known, otherwise fill in primary account details below. This will supersede if both are provided primary_account_c sn is not provided primary_account_address_line1 Account Address Line 1 1 Parkway Road String 35 O primary_account_c sn is not provided primary_account_address_line2 Account Address Line 2 Engineering Dept. String 35 O primary_account_c sn is not provided primary_account_address_line3 Account Address Line 3 Desk 5405 String 35 O primary_account_c sn is not provided primary_account_address_city Account City San Jose String 35 O primary_account_c sn is not provided 26 Web Service Reference Manual

27 primary_account_address_state Account State "CA" String 3 O primary_account_c sn is not provided primary_account_address_count ry_code Account Country Code "US" String 3 O primary_account_c sn is not provided. 2 digit ISO Code primary_account_address_postal _code Account Postal Code String 9 O primary_account_c sn is not provided net amount Amount "105.32" String 20 R Net amount of per line_item 27 Web Service Reference Manual

28 line_items 4.5 Request Schema Renew Field Array Schema Definition Field Description Example action_name Event name, partner is going to perform on place order, like renew Field Type Max Char Required/ Optional (O) Comments 28 Web Service Reference Manual Renewa l / Recurri ng "renew" String 5 R "renew" Renewal order_date Date on which order is placed " " Date 10 O Renewal po_date po_number Date on which partner raises the PO in their internal system (Can be system date or date in the past) Purchase order number to be given by requester to identify each order " " Date 10 O Renewal " " String 35 R Renewal customer_po_number PO number of the customer String 35 O Renewal contract_number Contract/Agreement number " " String 12 R Renewal reseller_account_csn Reseller Account CSN String 10 R Renewal sold_to_account_csn Sold To Account CSN String 10 O opportunity_type opportunity_number line_items Unique sales opportunity type created for an order Unique ID that references a sales opportunity that has been created for an order A String 1 O A String 15 O Array of JSON objects R If not provided it will take the authorization header value. Possible values are A (ACE) and R (Renewal). When you provide one of opportunity_type and opportunity_numbe r, you have to provide the other. Renewal Renewal Renewal Renewal part_number SKU "123K T979" String 35 R Renewal

29 quantity Quantity 7 Positive Integer net_amount Amount "105.32" String 20 R serial_numbers Serial Number [" "] Array of Strings R R Net amount of per line_item Renewal Renewal Renewal 29 Web Service Reference Manual

30 4.6 Update Purchase Order The Update Purchase Order API resource handles the updating of a PO number for recurring billing. The Update Purchase Order API can only be used for Partners that have subscribed under a model. Said subscription will renew itself automatically over whatever interval was selected (quarterly, annual, multi-year), and the existing open order will be updated with a new PO number and consequently the recurring billing. In order for the updates to be applied, the request must be submitted at least 48 hours in advance to the scheduled recurring billing. 4.7 Request Schema Update Purchase Order Note: The following schema only applies to partners utilizing a subscription Model. Field description Schema Definition Example Field Type Length 9 Comments Must always be po_update action_name "po_update" String contract_number String 30 Mandatory po_number String 35 Mandatory 4.8 Get Order Status The Get Order Status micro service is a simple get request of the following format: which only has a single field in the request schema, described below. The associated response schema, a status of success or failed, is also included. 4.9 Request Schema Get Order Status [ Initial Order Only] Field descriptio n URL Path Schema Definition reference number Example Field Type /order/status/ String Lengt h Min. 20 Max. 40 charact ers Comment s Mandatory. Part of URL path 4.10 Order Revoke Below is the request schema for the cases where the request type is for seat removal, product removal, order cancellation, or order returns. The associated response schema is also included. The order revoke requests are only available for those Partners utilizing a subscription model. Currently, order returns are not available and will be released as part of a future enhancement. The expected action_name values are as follows: remove seats, remove products, cancel. 30 Web Service Reference Manual

31 4.11 Request Schema Remove Seats, Remove Products, Order Cancellation The details of the expected fields in the request body for modifications to an existing order, such as decreasing the amount of seats to removing another product are located in the following table. Note: The following schema only applies to Partners utilizing a subscription model. A schema for the Renewable subscription model is not available at the moment. Field Description Contract header Line item level Schema Definition Example Field Type Required/ Optional Length Comments R 15 remove seats, remove products, action_name "remove seats" String cancel contract_number String R 30 Mandatory line_items subscription_id "bac19ced- 7aa a c8e98d" quantity 3 Array of JSON Objects String Positive Integer R R 36 R 13 Not needed for Cancellation Not Needed for Cancellation Only required for remove seats. Number of seats to be removed 4.12 Response Schema Create Initial Order A simple response from the API that verifies that a call has went through authentication, authorization, and validations and is being processed in our backend systems. Schema Definition Example Field Type status "OK" String message "Your order is being processed." String reference number String 4.13 Response Schema Update Purchase Order A simple response from the API that verifies that a call has went through authentication, authorization, and validations and is being processed in our backend systems. Schema Definition Example Field Type status "FAILED" String message "Contract number does not exist" Cannot add seats for a cancelled Product with Subscription ID <Subs ID> String reference number String 31 Web Service Reference Manual

32 4.14 Response Schema Get Order Status The response from the Status API returns the status of the order based on the provided transaction id. The status will indicate if the order is processing, completed, or failed with either a case number for status code. Schema Definition Example Field Type status "OK", FAILED,"Order Accepted String Order Processing Order was created successfully. Order processing error. Please contact Autodesk (error code 71) Order processing error. Please contact Autodesk CASE# message String last updated " :15:54 UTC" String 4.15 Response Schema Remove Seat, Remove Product, Order Cancellation [ Only] A simple response from the API that verifies that a call has went through authentication, authorization, and validations and is being processed in our backend systems. Schema Definition Example Field Type status "FAILED" String message "SKU is not active." String reference number String 4.16 Response Schema SNS notification Below are the present in the response from an SNS notification. The response provides details on the status of the placed order. If successful, the entity number is populated with the sales order number from our back office systems. If an error occurred when processing the order, the message field will provide an error code. Schema Definition Example Field Type csn " " String transaction_id " String status Success, Failed String message Order was created successfully. Add seat order was updated successfully. Order processing error. Please contact Autodesk (error code 71) String entity_number String 32 Web Service Reference Manual

33 5 Sample Messages 5.1 Request Message Order Fulfillment, Initial Order, Subscription Model Message Headers Authorization: Bearer <<Access Token>> Content-Type: application/json CSN: <<CSN>> Body "action_name": "initial_order", "po_number": " ", "customer_po_number": " ", "opportunity _ty pe": A, opportunity _number : A , "end_user": "first_name": "Gitman ", "last_name": "Gitman ", " ": "GitmanSan @ssttest.net", "language": "EN", "country ": "US", "primary _account_name": "Corp Account1", "primary _account_address_line1": "500 Las Gallinas Ave", primary_account_address_line2 : Engineering Dept., primary_account_address_line3 : Office 5342, "primary _account_address_city": "San Rafael", "primary _account_address_state": "CA", "primary _account_address_country_code": "US", "primary _account_address_postal_code": "94903", "related_account_name": "Corp Account1", "related_account_address_line1": "400 Las Gallinas Ave", related _account_address_line2 : Engineering Dept., related _account_address_line3 : Office 5342, "related_account_address_city": "San Rafael", "related_account_address_state": "CA", "related_account_address_country_code": "US", "related_account_address_postal_code": "94903", 33 Web Service Reference Manual

34 "reseller_account_csn": " ", "line_items": [ "subscription_id": "845cd4b7-2f20-4c1a-aaa ", "part_number": "767F T279", "quantity ": 1, "net_amount": "264.00", "eu_first_name": "Gitman ", "eu_last_name": "Gitman ", "eu_ ": "Gitman @ssttest.net", "eu_language": "EN", "eu_country ": "US", "eu_primary_account_name": "Gitman Corp Accoun1", "eu_primary_account_address_line1": "600 Las Gallinas Ave", "eu_primary_account_address_city": "San Rafael", "eu_primary_account_address_state": "CA", "eu_primary_account_address_country_code": "US", "eu_primary_account_address_postal_code": "94903" ] Response Message Order Fulfillment, Initial Order "status": "OK", "message": "Your order is being processed", "reference number": " INITIAL ORDER 9-27 arc " 34 Web Service Reference Manual

35 5.2 Request Message Order Fulfillment, Initial Order, Renewable Subscription Model Message Headers Authorization: Bearer <<Access Token>> Content-Type: application/json CSN: <<CSN>> Body "action_name": "initial_order", "po_date": " ", "po_number": "SSDD-002", "customer_po_number": "initial custpo", "end_user": " ": "raw "first_name": "Raw r", "last_name": "Stein", "primary_account_name": "Raw rstein World", "primary_account_address_line1": "666 Mars Way", "primary_account_address_city": "San Rafael", "primary_account_address_county": "United States", "primary_account_address_country_code": "US", "primary_account_address_geo": "NAMER", "primary_account_address_postal_code": "94903", "primary_account_address_state": "CA", "related_account_name": "Raw rstein World", "related_account_address_line1": "666 Mars Way", "related_account_address_city": "San Rafael", "related_account_address_county": "United States", "related_account_address_country_code": "US", "related_account_address_geo": "NAMER", "related_account_address_postal_code": "94903", "related_account_address_state": "CA", 35 Web Service Reference Manual

36 "reseller_account_csn": " ", "ship_to_party _account_name": "Rawrstein World", "ship_to_party _address_line1": "666 Mars Way", "ship_to_party _address_city": "San Rafael", "ship_to_party _address_county": "United States", "ship_to_party _address_country_code": "US", "ship_to_party _address_geo": "NAMER", "ship_to_party _address_postal_code": "94903", "ship_to_party _address_state_code": "CA", "sold_to_account_csn": " ", "other_parties": [ "account_csn": " ", "partner_ty pe": "ForwardingAgent" ], "line_items": [ "part_number": "978G1-WW2859-T981", "quantity ": 1, "net_amount": "1570.8", "deliv ery_method": "ED", "part_number": "978G1-WW6919-T229", "quantity ": 1, "net_amount": "1293.6", "deliv ery_method": "ED" ] Response Message Order Fulfillment, Initial Order "status": "OK", "message": "Your order is being processed", "reference number": " INITIAL ORDER 9-27 arc " 36 Web Service Reference Manual

37 5.3 Request Message Order Fulfillment, Add Seats, Subscription Model Message Headers Authorization: Bearer <<Access Token>> Content-Type: application/json CSN: <<CSN>> Body "action_name": "add_seats", "contract_number": " ", "po_number": " ", "net_amount": "105.32", "line_items": [ "subscription_id": "173789c1-d4b1-4bda-aaa1-8b3ea18ee53e", "part_number": "123F T979", "quantity": 3, "net_amount": "105.32", "subscription_id": "173789c1-d4b1-4bda-aaa1-8b3ea18ee53e", "part_number": "123F T970", "quantity": 2, "net_amount": "105.32" ] Response Message Order Fulfillment, Add Seats, Subscription Model "status": "OK", "message": "Your order is being processed", "reference number": " INITIAL ORDER 9-27 arc " 5.4 Request Message Order Fulfillment, Add Seats, Renewable Subscription Model 37 Web Service Reference Manual

38 Message Headers Authorization: Bearer <<Access Token>> Content-Type: application/json CSN: <<CSN>> Body "action_name": "add_seats", "po_date": " ", "po_number": "adds-mp-001", "customer_po_number": "adds s.s.d.d.", "contract_number": " ", "net_amount": "2864.4", "pricing_date": " ", "reseller_account_csn": " ", "ship_to_party_account_csn": " ", "sold_to_account_csn": " ", "line_items": [ "item_start_date": " ", "part_number": "978G T761", "quantity": 1, "related_account_csn" : " ", "net_amount": "1570.8", "serial_numbers": [ " " ], "item_start_date": " ", "part_number": "978G T204", "quantity": 1, "related_account_csn" : " ", "net_amount": "1293.6", "serial_numbers": [ " " ] ] 38 Web Service Reference Manual

39 5.4.1 Response Message Order Fulfillment, Add Seats, Renewable Subscription Model "status": "OK", "message": "Your order is being processed", "reference number": " INITIAL ORDER 9-27 arc " 5.5 Request Message Order Fulfillment, Add Products, Subscription Model Message Headers Authorization: Bearer <<Access Token>> Content-Type: application/json CSN: <<CSN>> Body "action_name": "add_products", "contract_number": " ", "po_number": "ae9be-3205ec9a9f3b", "net_amount": "264.0", "line_items": [ "subscription_id": "fa724c53-a376-4ab4-9a ec9a9f3b", "part_number": "767F T826", "quantity": 2, "net_amount": "264.0", "end_user": "first_name": "ddwsman ", "last_name": "ddwsman ", " ": "ddwsman @ssttest.net", "language": "EN", "country": "US", "primary_account_name": "ddwsman Corp Account1", "primary_account_address_line1": "810 Civic Center Dr", "primary_account_address_city": "San Rafael", "primary_account_address_state": "CA", "primary_account_address_country_code": "US", "primary_account_address_postal_code": "94903" ] 39 Web Service Reference Manual

40 5.5.1 Response Message Order Fulfillment, Add Products, Subscription Model "status": "OK", "message": "Your order is being processed", "reference number": " INITIAL ORDER 9-27 arc " 5.6 Request Message Order Fulfillment, Add Products, Renewable Subscription Model Message Headers Authorization: Bearer <<Access Token>> Content-Type: application/json CSN: <<CSN>> Body "action_name": "add_products", "po_date": " ", "po_number": "de2398-addp-002", "contract_number": " ", "customer_po_number": "addp s.s.d.d.", "net_amount": "1570.8", "pricing_date": " ", "reseller_account_csn": " ", "ship_to_party_account_csn": " ", "sold_to_account_csn": " ", "line_items": [ "item_start_date": " ", "part_number": "978G1-WW2859-T981", "quantity": 1, "eu_ ": "rawr.stein@ .com", "eu_first_name": "Rawr", "eu_last_name": "Stein", "related_account_csn": " ", "net_amount": "1570.8" ] 40 Web Service Reference Manual

41 5.6.1 Response Message Order Fulfillment, Add Products, Renewable Subscription Model "status": "OK", "message": "Your order is being processed", "reference number": " INITIAL ORDER 9-27 arc " 41 Web Service Reference Manual

42 5.7 Request Message Order Fulfillment, Renew, Renewable Subscription Model Only Message Headers Authorization: Bearer <<Access Token>> Content-Type: application/json CSN: <<CSN>> Body "action_name": "renew", "po_date": " ", "po_number": "SSDD-RENEW-02", "contract_number": " ", "net_amount": "1293.6", "pricing_date": " ", "reseller_account_csn": " ", "ship_to_party_account_csn": " ", "sold_to_account_csn": " ", "opportunity_type": A, opportunity_number : A ", "line_items": [ "part_number": "978G T374", "quantity": 1, "eu_ ": "rawr.stein@ .com", "eu_first_name": "Rawr", "eu_last_name": "Stein", "related_account_csn": " ", "net_amount": "1293.6", "serial_numbers": [ " " ] ] 42 Web Service Reference Manual

43 5.7.1 Response Message Order Fulfillment, Renew, Renewable Subscription Model Only "status": "OK", "message": "Your order is being processed", "reference number": " INITIAL ORDER 9-27 arc " 5.8 Request Message Update Purchase Order Message Headers Content-Type: application/json Authorization: Bearer <<Access Token>> "action_name":"po_update", "contract_number":" ", "po_number":" " Response Message Update Purchase Order "status": "OK", "message": "Your order is being processed", "reference number": " " 5.9 Request Message Get Order Status Response Message Get Order Status "status": "Order Accepted", "message": "Order was created successfully.", "last_updated": " :21:54 UTC" 43 Web Service Reference Manual

44 5.10 Request Message Order Revoke (Remove Seat, Remove Product, Order Cancellation) Message Headers Content-Type: application/json Authorization: Bearer <<Access Token>> "action_name": "cancel", "contract_number": " Response Message Order Revoke (Remove Seat, Remove Product, Order Cancellation) "status": "OK", "message": "Your order is being processed", "reference number": " " 5.11 Request Message Order Revoke (Order Returns) [Not Currently Available] Response Message Order Revoke (Order Returns) [Not Currently Available] 5.12 Request Message SNS Messaging SNS is an opt-in service that actively sends updated to the provide endpoint. A request to an endpoint is not required Response Message SNS messaging "csn": " ", "transaction_id": " juxtapoze ", "entity_number": " ", "message": 44 Web Service Reference Manual

45 "message": "Add seat order was updated successfully.", "status": "Success" 6 Formatting standards UUID Version 4 Unique randomly generate string ISO 8601 YYYY-MM-DD date format ISO Two letter language code ISO alpha-2 format two letter country code form 7 Error Messages 7.1 Error codes The following table shows the error codes and their respective error messages present in response messages should they occur. HTTP Status Code Autodesk Error Code Internal Message 200 OK 201 Created 304 Not Modified 400 Bad Request Error: 4000 Incorrect or malformed request Unauthorized Error: 4100 No CSN was passed in the request Unauthorized Error: 4101 No HMAC Signature passed in the request 401 Unauthorized Error: 4102 No HMAC Client ID passed in the request 401 Unauthorized Error: 4103 No HMAC Timestamp passed in the request 401 Unauthorized Error: 4104 No Authorization passed in the request 401 Unauthorized Error: 4105 Invalid token 401 Unauthorized Error: 4106 Something went wrong generating the token 403 Forbidden Error: 4301 HMAC signature was passed, but not a correct one 403 Forbidden Error: 4302 HMAC timestamp was passed, but not a correct one 403 Forbidden Error: 4300 CSN was passed, but not a correct one 45 Web Service Reference Manual

46 7.2 Error Message Below is a sample Error Message as it will be presented to the Partner: "status": "Error", "reference number": " ", "message": [ "error_code": "UAN-GEN-00108", "error_message": "Please enter Account Number" ] 46 Web Service Reference Manual