Digital Distribution Web Services (DDWS) GetOrderDetails - Service Manual

Transcription

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

2 CONTENTS Revision History Introduction Overview Supporting documents Getting Started GetOrderDetails Service Overview GetOrderList GetOrderDetails Benefits of GetOrderDetails Service GetOrderDetails Service Reference Information Request Schema Response Schema GetOrderList GetOrderDetails Error Schema Request Messages Request Message - GetOrderDetails Response Message Response Message GetOrderList Response Message GetOrderDetails Error Messages Sample Error Response Revision History Version Date Author Comments /22/2015 AR Added Revision History section /04/2015 AR Updated Section to reflect changes in the Response Schema 2 Web Service Reference Manual

3 3.4 12/21/2015 AR Added serial_number under section 3.2 Modified response message under section Modified response message under section /23/2016 RL Add fields item_po_number, billing_start_date, billing_end_date, billing_status,item_cancellation_transaction_date, and cancellation_reason to order_items_array /23/2016 RL Add field recurring_po to order_header_array /23/2016 ER Add field sales_licence_type to order_items description /31/2016 PL Added Street_2 and Street_3 to section /2/2016 PL Added fields activity, type, transactiondate, previousqty, newqty to section and updated example response in June 2016 FX Added field type and output lenght/format in section and July 2016 JC Added field unit_discount at item level in section and updated example response in Web Service Reference Manual

4 1 Introduction 1.1 Overview The Digital Distribution Web Service (DDWS) platform is an automation solution for order placement made directly from our Partners to Autodesk, all with low touch from Partners and zero touch from Autodesk. This new business capability will allow for true B2B web service transactions between Partners and Autodesk. For Partners to have effective implementation of Autodesk s Digital Services Platform, affiliates will need familiarity with REST web services, oauth and JSON. A sample client application is provided (written in the Ruby language) in a Programming Guide document, which will help said affiliates developers to consume the Digital Service API. 1.2 Supporting documents Autodesk Partner Developer Guide: This guide helps Partners with their onboarding process and accessing DDWS services. The guide also serves to introduce Partners to Autodesk s Digital Services Platform, using step-by-step instructions that guide them through the initial activities required for integration. 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. 2 Getting Started As part of the onboarding process, Partners will be associated with a unique Customer Specific Number (CSN) and will have their application registered with Autodesk. For more details on the onboarding process, please refer to the Autodesk Partner Developer Guide. 4 Web Service Reference Manual

5 3 GetOrderDetails Service Overview The GetOrderDetails service will provide Partners with detailed order information, including contract numbers, serial numbers, and product information, among other fields. This data will be in a raw format and it will be available to be consumed by a Partner s system of choice. This document will include all scenarios of the GetOrderDetails service which are eligible for retrieving order information within the Autodesk environment. There are two operations defined in this service for fetching orders, activated depending on the input provided to the GetOrderDetails service: 5 Web Service Reference Manual

6 GetOrderList GetOrderDetails 3.1 GetOrderList The purpose of this operation is to get the order list from a back end system if the input only includes a date range. The response will include data that will allow a Partner to re-query the service in order to get order details. Once the requester receives the response and retrieves the information he or she needs from it, he or she will call GetOrderDetails using Customer Number/Purchase Order Number/Sales Order Number as inputs. The following inputs are required to invoke the operation: 1. customer_number 2. order_date_from 3. order_date_to 3.2 GetOrderDetails The purpose of this operation is to get the order details for a given input. This operation can be called using the following sets of inputs: 1. customer_number 2. Only one of the following: a. serial_number b. contract_number c. partner_po d. customer_po e. order_number Note: Only a valid order will be populated as part of the GetOrderDetails API response. 3.3 Benefits of GetOrderDetails Service 1. A lightweight REST web service that can be consumed easily from any application via HTTP(s) connection. 2. Real time order status and tracking information. 3. The ability to have information about the order as soon as it is available. 4 GetOrderDetails Service Reference Information 4.1 Request Schema The details of the Request Message Parameters are in the following table for GetOrderDetails. Element Field Type Input Length/Format Utilization 6 Web Service Reference Manual

7 GetOrderDetails() Elements GetOrderList() Elements customer_number String Length: Max 10 Mandatory order_date_from Date Format: ISO 8601 YYYY-MM-DD Mandatory order_date_to Date Format: ISO 8601 YYYY-MM-DD (Date Range Limited to 90 Days) Mandatory customer_number String Length: Max 10 Mandatory contract_number String Length: Max 12 partner_po String Length: Max 35 customer_po order_number String String Length: Max 35 Length: 10 characters Only one can be passed along with customer_number serial_number String Length: Max 12 characters 4.2 Response Schema GetOrderList For date range submission, the following columns will be displayed. Field Field Type Output Length/Format sales_order_number String Length: Max 10 purchase_order_number String Length: Max 35 Description SAP Order Number Generated by Autodesk systems. Purchase Order Number Generated by the Partner and sent within PlaceOrder request. order_date Date Format: ISO 8601 Order processed date 7 Web Service Reference Manual

8 YYYY-MM-DD Thh:mm:ss+00:00 (e.g T17:51: ) customer_po_number String Length: Max 35 document_type String Length: Max 10 customer_number String Length: Max 10 customer_name String Length: Max 35 status String Confirmation response: Completed, Open tracking_number String Length: Max 35 Customer Purchase Order Number Belongs to the reseller who places the order via another reseller/distributor. Document Type Customer Number Name of Customer Order Status Tracking Number GetOrderDetails Field Field Output Description Type Length/Format status String Confirmation response: OK, FAILED, ERROR Request Status order_header_array [Array of JSON Objects] Field order_date String Format: ISO 8601 YYYY-MM-DD Thh:mm:ss+00:00 (e.g T17:51: ) sales_order_number String Length: Max 10 purchase_order_number String Length: Max 35 customer_po_number String Length: Max 35 document_type String Length: Max 10 Description Order Processed Date SAP Order Number Generated by Autodesk systems. Purchase Order Number Generated by the Partner and sent within PlaceOrder request. Customer Purchase Order Number Belongs to the reseller who places the order via another reseller/distributor. Document Type 8 Web Service Reference Manual

9 customer_number String Length: Max 10 customer_name String Length: Max 35 order_status String Length: Max 20 tracking_number String Length: Max 35 order_amount String Length: Max 15 tax_amount String Length: Max 13 contract_number String Length: Max 12 shipment_method String Length: Max 20 freight_charge String Length: Max 15 purchase_order_date String Format: ISO 8601 YYYY-MM-DD Thh:mm:ss+00:00 (e.g T17:51: ) contract_start_date String Format: ISO 8601 YYYY-MM-DD Thh:mm:ss+00:00 (e.g T17:51: ) contract_end_date String Format: ISO 8601 YYYY-MM-DD Thh:mm:ss+00:00 (e.g T17:51: ) Customer Number Customer Name Order Status Tracking Number Order Amount Is the total price of the order, which equals the price of the products in the initial order plus the price of those products for the next term. The latter will be invoiced next billing period. Tax Amount Contract Number Is a unique number associated with the master order. Shipment Method Freight Charge Purchase Order Date Contract Start Date Is the date when the billing will start. This is equal to order date unless the order is placed with a future start date. Contract End Date Is the date when the subscription will be terminated. For recurring orders, this field will be equal to XXXXX. contract_usage_type String Length: Max 3 Contract Usage Type recurring_po String Length: Max 40 Recurring PO Number order_items_array [Array of JSON Objects] sales_order_number String Length: Max 10 Sales Order Number line_number String Length: Max 6 Line Number 9 Web Service Reference Manual

10 Item_po_number String Length: Max 40 sku String Length: Max 18 sku_description String Length: Max 60 quantity Integer Length: Max 15 unit_price String Length: Max 11 unit_discount String Length: Max 11 order_currency String Length: Max 5 net_value String Length: Max 15 product_key String Length: Max 30 group_name String Length: Max 35 serial_number String Length: Max 1300 current_serial_number String Length: Max 130 seats String Length: Max 10 Item PO Number Is the order number generated by the Partner and sent within the PlaceOrder request. If the line item is generated during the initial order, the value will be equal to that of purchase_order_number at the header level. Otherwise, if a product is added to the same contract later on, it will contain the purchase order number of this request. Material Number Is the number to identify the product being ordered. The format of this field is like the one below "001H T275" Material Description Is the description of the product that is being ordered. Quantity Price per unit Represents the price of one seat. Discount per unit Represents the discount of one seat Currency Is the currency of the monetary value in the order, and is defined based on the locale of the Partner placing the order. Net Value Product Key Group Name Empty if the order is a Renewal or Add Seats Generated by Autodesk to uniquely identify the product. Empty if the order is an Initial Order or Add Products Number of seats For Subscription Orders, this field is always equal to 1. For perpetual licenses, it represents the seat number under the license. 10 Web Service Reference Manual

11 deployment String Length: Max 1 Deployment license_type String Length: Max 30 License Type usage_type String Length: Max 3 Usage Type license_description String Length: Max 155 License Description subs_id String Length: Max 48 Subscription ID, Recurring Only billing_start_date String Format: ISO 8601 Billing Start Date YYYY-MM-DD Thh:mm:ss+00:00 billing_end_date String Format: ISO 8601 Billing End Date YYYY-MM-DD Thh:mm:ss+00:00 (e.g T17:51: ) billing_status String Billing Status item_cancellation_transact ion_date String Format: ISO 8601 YYYY-MM-DD Thh:mm:ss+00:00 (e.g T17:51: ) Item Cancellation Transaction Date cancellation_reason String Length: Max 40 Cancellation Reason sales_licence_type String Length: Max 30 New or Renewal order_partners_array [Array of JSON Objects] sales_order_number String Length: Max 10 Sales Order Number line_number String Length: Max 6 Line Number partner_type String Length: Max 15 For each partner type, all the corresponding information will be displayed. Partner types are: Contact Person, Dealer, End User, Bill to, Ship to, Contract Mgr. partner_number String Length: Max 10 Partner Number contact_number String Length: Max 10 Contact Number partner_name String Length: Max 80 Partner Name street String Length: Max 30 Street street_2 String Length: Max 40 Address Line 2 street_3 String Length: Max 40 Address Line 3 po_box String Length: Max 10 PO Box 11 Web Service Reference Manual

12 city String Length: Max 25 City postal_code String Length: Max 10 Postal Code pobox_postal_code String Length: Max 10 Postal Code Corresponding to PO Box country String Length: Max 15 Country district String Length: Max 25 District region String Length: Max 3 Region end_user_ String Length: Max 241 assetdetailslist [Array of JSON Objects] serialnumber String Length: Max 18 All serial numbers associated to the order registereddate String Format: ISO 8601 Registered date for each serial number YYYY-MM-DD Thh:mm:ss+00:00 activity [Array of JSON Element of assetdetailslist, audit trail list Objects] type String Length: Max 15 Remove seat. This section will be populated for remove seat scenarios. transactiondate String Format: ISO 8601 Date and time of seat removal YYYY-MM-DD Thh:mm:ss+00:00 previousqty Integer Length: Max 15 Previous seat quantity newqty Integer Length: Max 15 New seat quantity welcomekitstatus String Length: Max 100 Sent, Not Sent Note: As the GetOrderDetails Service exists now, the Welcome Kit Status field (welcomekitstatus) will return the default response "Not Sent. This flag will be updated in the future when full development of the GetOrderDetails Service is completed. 4.3 Error Schema Field Name status message transactionid Description Confirmation response: OK, FAILED, ERROR Message for failure or errors Unique transaction id (combination of order number and time stamp). Only returned in case of success. 4.4 Request Messages Below are sample requests for GetOrderDetails 12 Web Service Reference Manual

13 4.4.1 Request Message - GetOrderDetails [Getting GetOrderList using Customer Number and Date Range] 01&order_date_to= Message Headers Content-Type: application/json Authorization: Bearer <<Access Token>> CSN: <<CSN>> signature: <<Signed Access Token>> timestamp: <<Timestamp for the signed Access Token>> [Getting GetOrderDetails using Customer Number and Serial Number] stg.autodesk.com/v1/orders?customer_number= &order_date_from= stg.autodesk.com/v1/orders?customer_number= &serial_number=d Message Headers Content-Type: application/json Authorization: Bearer <<Access Token>> CSN: <<CSN>> signature: <<Signed Access Token>> timestamp: <<Timestamp for the signed Access Token>> 4.5 Response Message Note: Autodesk will send a response with the following structure. Partners can reformat this to different structures based on their need Response Message GetOrderList "status": "OK", "message": "elements": [ "order_list_array": [ "sales_order_number": " ", "purchase_order_number": "PONFRtes", 13 Web Service Reference Manual

14 "customer_po_number": "", "customer_number": " ", "customer_name": "newstgsasp endcomp", "status": "Completed", "sales_order_number": " ", "purchase_order_number": "RCG-annual-renew No order date", "customer_po_number": "Cust po renew no orderdate", "customer_number": " ", "customer_name": "Sample Name", "status": "Being processed", "sales_order_number": " ", "purchase_order_number": "InitialOrderQTR1130", "customer_po_number": "", "customer_number": " ", "customer_name": "Initialorderqtr 1130", "status": "Completed", "sales_order_number": " ", "purchase_order_number": "InitialOrderQTR1130A", "customer_po_number": "", "customer_number": " ", "customer_name": "Initialorderqtr 1130", "status": "Completed", "sales_order_number": " ", "purchase_order_number": "AddSeat1130PT", "customer_po_number": " ", "customer_number": " ", "customer_name": "SAMPLE NAME", "status": "Completed", "sales_order_number": " ", 14 Web Service Reference Manual

15 "purchase_order_number": "testpo ", "customer_po_number": "", "customer_number": " ", "customer_name": "Sample Name", "status": "Being processed", "sales_order_number": " ", "purchase_order_number": "testpo ", "customer_po_number": "", "customer_number": " ", "customer_name": "Sample Name", "status": "Completed", "sales_order_number": " ", "purchase_order_number": "testpo ", "customer_po_number": "", "customer_number": " ", "customer_name": "Sample Name", "status": "Completed", "sales_order_number": " ", "purchase_order_number": "testpo ", "customer_po_number": "", "customer_number": " ", "customer_name": "Sample Name", "status": "Completed", "sales_order_number": " ", "purchase_order_number": "RCG Initial Dec 01", "customer_po_number": " ", "customer_number": " ", "customer_name": "Sample Name", "status": "Being processed", 15 Web Service Reference Manual

16 "sales_order_number": " ", "purchase_order_number": "NewOrder1201PT", "customer_po_number": "", "customer_number": " ", "customer_name": "Neworder 1201Pt", "status": "Completed", "sales_order_number": " ", "purchase_order_number": "RenewalOrder1201PT", "customer_po_number": "", "customer_number": " ", "customer_name": "Renewalorder 1201Pt", "status": "Completed", "sales_order_number": " ", "purchase_order_number": "ddwsmultiseattest2", "customer_po_number": "", "document_type": "Online Transaction", "customer_number": " ", "customer_name": "SEnterprises", "status": "Being processed", "sales_order_number": " ", "purchase_order_number": "functest_ ", "customer_po_number": "", "document_type": "Online Transaction", "customer_number": " ", "customer_name": "SEnterprises", "status": "Being processed", } ] } ] } } 16 Web Service Reference Manual

17 4.5.2 Response Message GetOrderDetails "status": "OK", "message": "elements": [ "order_header_array": [ "order_date": " T00:00: ", "sales_order_number": " ", "purchase_order_number": "JEM-REN-Jul18 PRUEBA_0001", "customer_po_number": "custpo JEM-REN-Jul18 PRUEBA_0001", "customer_number": " ", "customer_name": "KCCGJCGDPJHMHJBKPBEDPEOHDAKIEHAD", "order_status": "Open",, "order_amount": "2,402.40", "tax_amount": "0.00", "contract_number": " ", "shipment_method": "FDIDLNBAPOIFMJGOGPLD", "freight_charge": "0.00", "purchase_order_date": " T00:00: ", "contract_start_date": " T00:00: ", "contract_end_date": " T00:00: ", "contract_usage_type": "COM", "recurring_po": "" }], "order_items_array": [ "sales_order_number": " ", "line_number": "000010", "item_po_number": "JEM-REN-Jul18 PRUEBA_0001", "sku": "765H1-WW4127-T897", "sku_description": "BDSP 2016 TBP:PA SUB WW ELD", "quantity": 1, "order_currency": "USD", "unit_price": "2,730.00", "unit_discount": " ", "net_value": "2,402.40", "product_key": "765H1", "group_name": "", "serial_number": " ", "current_serial_number": "", "seats": "1", "deployment": "S", "license_type": "NOT APPLICABLE", "usage_type": "COM", "license_description": "Autodesk Building Design Suite Premium 2016", "subs_id": "", "billing_start_date": null, "billing_end_date": null, "billing_status": "N/A", "item_cancellation_transaction_date": null, "cancellation_reason": "", 17 Web Service Reference Manual

18 "sales_license_type": "New" }], "order_partners_array": [ "sales_order_number": " ", "line_number": "000000", "partner_type": "Contact Person", "partner_number": "", "contact_number": " ", "partner_name": "Eddie The Eagle", "street": "JJOPDAEJMHAFNPBGKCPCOENGLNFMGC", "street_2": "", "street_3": "", "po_box": "JJOPDAEJMH", "city": "San Rafael", "postal_code": "94903", "pobox_postal_code": "94903", "country": "US", "district": "", "region": "CA", "end_user_ ": "" "sales_order_number": " ", "line_number": "000000", "partner_type": "Dealer", "partner_number": " ", "contact_number": " ", "partner_name": "NOFCMIEAEFKLMLPHIEGGOMOOMHMMIBNH JJOPDAEJMHAFNPBGKCPCOENGLNFMGCCM", "street": "OEECHGIHNFOJALFENFDBMIPKBIEPCJ", "street_2": "", "street_3": "", "po_box": "JJOPDAEJMH", "city": "Mississauga", "postal_code": "L5N 8G1", "pobox_postal_code": "L5N 8G1", "country": "CA", "district": "", "region": "ON", "end_user_ ": "" "sales_order_number": " ", "line_number": "000000", "partner_type": "End User", "partner_number": " ", "contact_number": " ", "partner_name": "KCCGJCGDPJHMHJBKPBEDPEOHDAKIEHAD JJOPDAEJMHAFNPBGKCPCOENGLNFMGCCM", "street": "JJOPDAEJMHAFNPBGKCPCOENGLNFMGC", "street_2": "", "street_3": "", 18 Web Service Reference Manual

19 "po_box": "JJOPDAEJMH", "city": "San Rafael", "postal_code": "94903", "pobox_postal_code": "94903", "country": "US", "district": "", "region": "CA", "end_user_ ": "" "sales_order_number": " ", "line_number": "000000", "partner_type": "Bill to", "partner_number": " ", "contact_number": " ", "partner_name": "Test-Tech Data Prod MGT Commercial", "street": "5350 Tech Data Dr", "street_2": "", "street_3": "", "po_box": "", "city": "Clearwater", "postal_code": " ", "pobox_postal_code": "", "country": "US", "district": "PINELLAS", "region": "FL", "end_user_ ": "" "sales_order_number": " ", "line_number": "000000", "partner_type": "Ship to", "partner_number": " ", "contact_number": " ", "partner_name": "KCCGJCGDPJHMHJBKPBEDPEOHDAKIEHAD JJOPDAEJMHAFNPBGKCPCOENGLNFMGCCM", "street": "JJOPDAEJMHAFNPBGKCPCOENGLNFMGC", "street_2": "", "street_3": "", "po_box": "JJOPDAEJMH", "city": "San Rafael", "postal_code": "94903", "pobox_postal_code": "94903", "country": "US", "district": "", "region": "CA", "end_user_ ": "" "sales_order_number": " ", "line_number": "000000", "partner_type": "Contract Mgr", "partner_number": " ", 19 Web Service Reference Manual

20 "contact_number": " ", "partner_name": "KCCGJCGDPJHMHJBKPBEDPEOHDAKIEHAD JJOPDAEJMHAFNPBGKCPCOENGLNFMGCCM", "street": "JJOPDAEJMHAFNPBGKCPCOENGLNFMGC", "street_2": "", "street_3": "", "po_box": "JJOPDAEJMH", "city": "San Rafael", "postal_code": "94903", "pobox_postal_code": "94903", "country": "US", "district": "", "region": "CA", "end_user_ ": "" "sales_order_number": " ", "line_number": "000010", "partner_type": "Contract Mgr", "partner_number": "EU3000", "contact_number": " ", "partner_name": "KCCGJCGDPJHMHJBKPBEDPEOHDAKIEHAD JJOPDAEJMHAFNPBGKCPCOENGLNFMGCCM", "street": "JJOPDAEJMHAFNPBGKCPCOENGLNFMGC", "street_2": "", "street_3": "", "po_box": "JJOPDAEJMH", "city": "San Rafael", "postal_code": "94903", "pobox_postal_code": "94903", "country": "US", "district": "", "region": "CA", "end_user_ ": "" } ], "assetdetailslist": [ "serialnumber": " ", "registereddate": " T00:00:00.000Z", "activity": [ "type": "Remove Seat", "transactiondate": " T23:03:52.000Z", "previousqty": "3", "newqty": 2 "type": "Remove Seat", "transactiondate": " T22:17:51.000Z", "previousqty": "2", "newqty": 1 } ] 20 Web Service Reference Manual

21 } }], "welcomekitstatus": "Not Sent" }]} 4.6 Error Messages The following table shows error codes and their respective error messages present in response messages should an error be found: Message Number Error Message 003 & is not found. 013 The input parameter is incomplete. 015 Order Number Not Found 016 Order Number Not Found 017 The Serial Number Provided is not valid 018 Duration should be less than ninety (90) days UAN-GEN The Serial Number provided is not in the correct format UAN-GEN Please provide Customer number UAN-GEN Please enter "From Date" in YYYY-MM-DD format UAN-GEN Please enter "From Date" in YYYY-MM-DD format UAN-GEN Please enter "To Date" in YYYY-MM-DD format UAN-GEN Please enter "To Date" in YYYY-MM-DD format UAN-INV "From Date" should be prior than "To Date" UAN-GEN Date range must not be more than 90 days. Please check your entry and try again UAN-GEN Invalid Customer number. Please check your entry and try again UAN-GEN Customer number may not exceed 10 characters. Please check your entry and try again UAN-GEN Please provide a valid parameters combination UAN-GEN Please provide the right parameters names UAN-GEN Please provide Order number or another valid document number. UAN-GEN Order number should be exact 10 characters. Please check your entry and try again UAN-GEN Purchase Order number may not exceed 35 characters. Please check your entry and try again Please Provide at least one of the following parameters SerialNumber,ContractNumber,OrderNumber or PONumber The Serial Number Provided is not valid APG-DWS-INV-002 Provided customer number is invalid. UAN-GEN Partner PO may not exceed 35 characters. Please check your entry and try again UAN-GEN Contract Number may not exceed 12 characters. Please check your entry and try again 21 Web Service Reference Manual

22 4.6.1 Sample Error Response } "status": "Error", "transactionid": "INV ", "message": [ "error_code": " APG-DWS-INV-002", "error_message": "Provided customer number is invalid." } ] Note: This Service Reference Manual is for the sole use of the intended recipients and may contain proprietary and/or confidential information which may be privileged or otherwise protected from disclosure. Any unauthorized review, use, disclosure or distribution is prohibited. 22 Web Service Reference Manual