AutoCAD 订购服务版本1服务手册说明书

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)
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)
Revision History
1Introduction
1.1Overview
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.2Supporting 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.
2Subscription 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.
2.1R ecurring (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.2R enewable
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.
3Service 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
Figure 1: PlaceOrder v1 process flow
3.1Order 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.2Order 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)
If subscribed to receive order fulfillment notifications, a Partner can choose one of the following three methods of delivery:
•Email
•SMS Message
•Endpoint
3.4G etOrderStatus 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.
4Service Endpoints
5Request/Response Schema
5.1R equest
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
A UTODESK PlaceOrder v1 Service Reference Manual 11
5.2R esponse
5.2.1High-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:
A UTODESK PlaceOrder v1 Service Reference Manual 24
6Sample Requests/Responses
Sample requests are provided below as a reference. Please note that many other combinations are possible.
6.1P lace an Initial Order
Below is a sample request for an initial recurring order with one product subscription.
Request
A UTODESK PlaceOrder v1 Service Reference Manual 27
Response with no errors
6.2A dd Seats
Below is a sample addition request for adding more seats to one product of an existing, recurring contract. Request
Response with no errors
A UTODESK PlaceOrder v1 Service Reference Manual 28
6.3A dd Products
Below is a sample addition request for adding one product to an existing, recurring contract.
Request
Response with no errors
6.4R emove Seats
Below is a sample revoke request for removing seats from one product of an existing, recurring contract. Request
A UTODESK PlaceOrder v1 Service Reference Manual 29
Response with no errors
6.5R emove Products
Below is a sample revoke request for removing one product from an existing, recurring contract. Request
Response with no errors
A UTODESK PlaceOrder v1 Service Reference Manual 30
6.6C ancel Order
Below is a sample revoke request to cancel an existing, recurring contract.
Request
Response with no errors
6.7G eneric Error applicable for all request types
7Formatting standards
UUID Version 4– Unique, randomly generated string
https:///wiki/Universally_unique_identifier#Version_4_.28random.29 ISO 8601– YYYY-MM-DD date format
/iso/home/standards/iso8601.htm
ISO 639-1 - Two letter language code
/iso/home/store/catalogue_tc/catalogue_detail.htm?csnumber=22109 ISO 3166-1 alpha-2 format– two letter country code form
/iso/country_codes
8Error 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.1S ystem 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.
8.2Service Error Code
The table below lists the possible error codes returned by the PlaceOrder v1 Service due to Business Logic or Data related errors.。