Digital Distribution Web Services (DDWS) Manuale del servizio PlaceOrder

Transcript

1 Digital Distribution Web Services (DDWS) Manuale del servizio PlaceOrder

2 INDICE Cronologia delle revisioni Introduzione Panoramica Documentazione di supporto Operazioni preliminari Panoramica del servizio PlaceOrder Abbonamento ad Autodesk Rinnovabile Evasione dell'ordine Revoca dell'ordine SNS Messaging Recupero dello stato dell'ordine Informazioni di riferimento del servizio PlaceOrder Evasione dell'ordine Schema di risposta - Creazione ordine iniziale Schema di richiesta - Aggiunta di postazioni Schema di richiesta - Aggiunta di prodotti Schema di richiesta - Rinnovo Aggiornamento ordine di acquisto ricorrente Schema di richiesta - Aggiornamento ordine di acquisto ricorrente Recupero dello stato dell'ordine Schema di richiesta - Recupero dello stato dell'ordine [solo ordine ricorrente iniziale] Revoca dell'ordine Schema di richiesta - Rimozione postazioni, rimozione prodotti, annullamento ordine Schema di risposta - Creazione ordine iniziale Schema di risposta - Aggiornamento ordine di acquisto ricorrente Schema di risposta - Recupero dello stato dell'ordine Schema di risposta - Rimozione postazione, rimozione prodotto, annullamento ordine [solo modello ricorrente] Schema di risposta - Notifica SNS Messaggi di esempio Messaggio di richiesta - Evasione ordine, ordine iniziale, modello di abbonamento ricorrente Messaggio di risposta - Evasione ordine, ordine iniziale Messaggio di richiesta - Evasione ordine, ordine iniziale, modello di abbonamento rinnovabile Messaggio di risposta - Evasione ordine, ordine iniziale Manuale di riferimento dei servizi Web

3 5.3 Messaggio di richiesta - Evasione ordine, aggiunta di postazioni, modello di abbonamento ricorrente Messaggio di risposta - Evasione ordine, aggiunta di postazioni, modello di abbonamento ricorrente Messaggio di richiesta - Evasione ordine, aggiunta di postazioni, modello di abbonamento rinnovabile Messaggio di risposta - Evasione ordine, aggiunta di postazioni, modello di abbonamento rinnovabile Messaggio di richiesta - Evasione ordine, aggiunta di prodotti, modello di abbonamento ricorrente Messaggio di risposta - Evasione ordine, aggiunta di prodotti, modello di abbonamento ricorrente Messaggio di richiesta - Evasione ordine, aggiunta di prodotti, modello di abbonamento rinnovabile Messaggio di risposta - Evasione ordine, aggiunta di prodotti, modello di abbonamento rinnovabile Messaggio di richiesta - Evasione ordine, rinnovo, solo modello di abbonamento rinnovabile Messaggio di risposta - Evasione ordine, rinnovo, solo modello di abbonamento rinnovabile Messaggio di richiesta - Aggiornamento ordine di acquisto ricorrente Messaggio di risposta - Aggiornamento ordine di acquisto ricorrente Messaggio di richiesta - Recupero dello stato dell'ordine Messaggio di risposta - Recupero dello stato dell'ordine Messaggio di richiesta - Revoca ordine (Rimozione postazione, rimozione prodotto, annullamento ordine) Messaggio di risposta - Revoca ordine (Rimozione postazione, rimozione prodotto, annullamento ordine) Messaggio di richiesta - Revoca ordine (resi ordine) Messaggio di risposta - Revoca ordine (resi ordine) Messaggio di richiesta - Messaggi SNS Messaggio di risposta - Messaggi SNS Standard di formattazione Messaggi di errore Codici di errore Messaggio di errore Manuale di riferimento dei servizi Web

4 Cronologia delle revisioni Versione Data Autore Commenti /10/2015 AR Aggiunta delle sezioni 4.2, 4.7, 5.2 e per includere il servizio di fatturazione ricorrente /10/2015 AR Sostituzione del nome del servizio Recurring Billing con Update Recurring Purchase Order e aggiornamento dell'url della richiesta /10/2015 AR Valori del campo action_name di Order Fulfillment modificati da "add_seat" e "add_product" a "add_seats" e "add_products" /11/2015 AR Messaggio di richiesta di esempio per Evasione dell'ordine, Ordine iniziale nella sezione 5.1 modificato in modo da visualizzare un payload di esempio per i modelli di abbonamento ricorrenti. Sample Request Message modificato per Evasione dell'ordine, Ordine iniziale nella sezione 5.2 in modo da visualizzare un payload di esempio per i modelli di abbonamento rinnovabili. Schema di richiesta di creazione ordine iniziale modificato nella sezione Manuale di riferimento dei servizi Web

5 3.2 05/11/2015 AR Schema della richiesta add_seats aggiunto nella sezione 4.3 Schema della richiesta add_products aggiunto nella sezione 4.4 Schema della richiesta di rinnovo aggiunto nella sezione 4.5 Schema della richiesta initial_order modificato nella sezione 4.2 Sezioni 5.3, 5.4, 5.5, 5.6, 5.7 aggiunte per includere messaggi di esempio per le azioni di evasione degli ordini: add_seats, add_products e renew /11/2015 AR Dati di esempio aggiornati in base ai messaggi di esempio nella sezione 5. Schema della richiesta "Renew" aggiornato nella sezione 4.5 per rimuovere "subscription_id". Schema della richiesta "initial_order" aggiornato nella sezione 4.2 per rimuovere "external_ref_ number". 5 Manuale di riferimento dei servizi Web

6 3.4 09/11/2015 AR Esempi di data dello schema di richiesta modificati in base al formato ISO 8601 Valori "action_name" possibili aggiornati in Order Revoke per la rimozione di prodotti e postazioni, l'annullamento e i resi. Nota: al momento i resi non sono consentiti. Schema della richiesta di revoca dell'ordine aggiornato nella sezione 4.11 Descrizioni dei modelli di abbonamento Desktop aggiunte nella sezione 3.1 Campo "related_account_cs n" aggiunto nello schema della richiesta di aggiunta di postazioni nella sezione 4.3 Campo "pricing_date" rimosso dallo schema della richiesta di aggiunta di postazioni nella sezione 4.3 Codici di errore modificati nella sezione /12/2015 AR Sezioni modificate per riflettere lo schema di richiesta più recente 6 Manuale di riferimento dei servizi Web

7 Sezione 4.9 modificata da "po_number" a "reference number" /02/2016 RL Conversione di tutti i campi denominati "quantity" in numeri interi /02/2016 RL Sostituzione del campo ref_document con i campi opportunity_type e opportunity_number /02/2016 RL Rimozione del campo order_date. Indicazione delle regole in contract_start_date /02/2016 CC Aggiornamento della documentazione per lo schema di risposta dell'api di stato /02/2016 CC Aggiornamento del servizio SNS per indicare la disponibilità per tutti i servizi di invio degli ordini /03/2016 PL Commenti nella sezione 4.2 rimossi da first_name, last_name, , eu_first_name, eu_last_name, eu_ Sezione 4.2 modificata da F a O per first_name, last_name, , eu_first_name, eu_last_name, eu_ Colonna dei commenti della sezione Manuale di riferimento dei servizi Web

8 modificata in modo da includere solo "Specificare se noto" per contact_csn, eu_contact_csn Nella colonna dei commenti della sezione 4.2 per tutti i campi che iniziano con primary_account, related_account, eu_primary_account è stato aggiunto il commento "*Le regole sono valide ricorrente" /03/2016 PL Tutti i campi Quantity delle sezioni 4.2, 4.3, 4.4, 4.11 aggiornati per contenere solo valori interi positivi Campi ed eu_ delle sezioni 4.2, 4.3 e 4.4 aggiornati in modo da contenere al massimo 80 caratteri Elementi Address_Line2 e Address_Line3 aggiunti per i campi Primary, Eu_Primary e Related Account nelle sezioni 4.2, 4.4, /05/2016 PL Campi seguenti rimossi dalle sezioni 4.2, 4.3, 4.4, 4.5 insieme ai messaggi di risposta corrispondenti: item_end_date, contact_csn, eu_csn, contract_end_date, 8 Manuale di riferimento dei servizi Web

9 currency_code, eu_contact_csn Descrizioni aggiunte per tutti i campi nelle sezioni 4.2, 4.3, 4.4, 4.5. Aggiunta di un possibile messaggio di errore nella sezione lug 2016 FX Rimosse tutte le occorrenze di "Desktop Subscription" perché questa terminologia è obsoleta. La durata dell'abbonamento è stata definita come "durata". "Subscription pluriennale" è stato modificato in "pluriennale" poiché ora fa riferimento a una durata generica. 9 Manuale di riferimento dei servizi Web

10 1 Introduzione 1.1 Panoramica La piattaforma Digital Distribution Web Service (DDWS) è una soluzione che consente ai partner di inserire automaticamente gli ordini dei prodotti Autodesk e che prevede un'interazione minima ("low touch") da parte dei partner e nessun intervento ("zero touch") da parte di Autodesk. Questa nuova funzionalità di business rende possibili vere e proprie transazioni basate sui servizi Web B2B tra i partner e Autodesk. L'invio dell'ordine è un processo completamente automatico avviato dal partner, diretto ad Autodesk e di nuovo al cliente finale, senza alcun intervento manuale. Perché il partner possa implementare in modo efficace la piattaforma DDWS di Autodesk, le società affiliate dovranno acquisire familiarità con i servizi Web REST, oauth 2.0 e JSON. Nella guida alla programmazione è disponibile un'applicazione client di esempio scritta nel linguaggio Ruby. Tale applicazione permetterà agli sviluppatori delle società affiliate di utilizzare l'api dei servizi DDWS. 1.2 Documentazione di supporto Authentication API Documentation: questo documento illustra ai partner il processo di generazione delle credenziali, delle firme e dei token di accesso necessari per utilizzare le API dei servizi. Contiene inoltre informazioni per lo sviluppo di un'applicazione di integrazione di un partner, Fornisce informazioni di base sull'integrazione del servizio Web e illustra lo sviluppo di un'applicazione tipica. API Schema/Interface Details: questo documento contiene informazioni sul payload relative a tutti i possibili scenari del servizio PlaceOrder e può essere utilizzato dagli sviluppatori per generare richieste di esempio compilando i campi desiderati. Per ulteriori informazioni sui servizi Web Autodesk, consultare il portale dello sviluppatore, dal quale è possibile accedere a tutta la documentazione disponibile, nonché a istruzioni passo-passo sul funzionamento dei servizi Autodesk. 2 Operazioni preliminari Durante il processo di formazione, i partner vengono associati a un Customer Specific Number (CSN) univoco e le relative applicazioni vengono registrate presso Autodesk. Per ulteriori informazioni sul processo di formazione, fare riferimento all'autodesk Partner Developer Guide. 10 Manuale di riferimento dei servizi Web

11 3 Panoramica del servizio PlaceOrder Il servizio PlaceOrder include due risorse API per la gestione degli ordini: /orders/fulfillment e /orders/revoke. Queste risorse sono costituite da operazioni che gestiscono la creazione, l'annullamento e i resi degli ordini, nonché l'aggiunta e la rimozione di postazioni e prodotti ai/dai contratti esistenti. In questo documento vengono descritti i vari scenari del servizio PlaceOrder idonei per la generazione degli ordini o le modifiche dei contratti all'interno dell'ambiente Autodesk. Di seguito sono riportati i dettagli dei servizi inclusi nel processo di evasione e revoca degli ordini. Invio di nuovi ordini Aggiunta di postazioni ai contratti esistenti Aggiunta di prodotti ai contratti esistenti Rimozione di postazioni dai contratti esistenti Rimozione di prodotti dai contratti esistenti Restituzione di un contratto ricorrente (al momento non disponibile) Annullamento di un contratto ricorrente 11 Manuale di riferimento dei servizi Web

12 3.1 Abbonamento ad Autodesk L'abbonamento ad Autodesk è un approccio di pagamento a consumo che prevede piani di durata mensile, trimestrale, annuale o pluriennale selezionati dai clienti. Sono disponibili due modelli principali: ricorrente e rinnovabile In un modello di abbonamento ricorrente, l'abbonamento del cliente viene aggiornato automaticamente in base alla durata (mensile, trimestrale o annuale) selezionata dal partner. L'abbonamento non termina mai e può essere annullato solo quando il cliente lo richiede esplicitamente o quando decide di passare a un altro modello Rinnovabile Nel caso di abbonamento a un servizio con modello rinnovabile, l'abbonamento termina una volta scaduta la durata selezionata (trimestrale, annuale, pluriennale). Questo stesso abbonamento potrà essere rinnovato poco prima della scadenza del periodo scelto. In breve, l'abbonamento rinnovabile ha una data di scadenza associata all'abbonamento, mentre quello ricorrente non ha alcuna scadenza. 3.2 Evasione dell'ordine La risorsa API di evasione dell'ordine (Order Fulfillment) gestisce la creazione degli ordini, l'aggiunta di postazioni e l'aggiunta di operazioni sui prodotti. Le operazioni di aggiunta di postazioni e prodotti sono disponibili solo per i contratti esistenti. 3.3 Revoca dell'ordine La risorsa API di revoca dell'ordine (Order Revoke) gestisce l'operazione di reso per gli ordini ricorrenti, nonché le operazioni di rimozione di una postazione, rimozione di un prodotto e annullamento. I resi sono validi solo entro il periodo di tolleranza stabilito. Se il reso è valido, il contratto verrà annullato e l'importo rimborsato. Se viene eseguita un'operazione di annullamento, il comportamento di rinnovo automatico viene interrotto, ma il contratto rimane ancora valido per tutto il periodo rimanente. Le operazioni di rimozione di postazioni e prodotti sono valide solo per i contratti esistenti. 3.4 SNS Messaging SNS Messaging è un servizio opzionale al quale i partner Autodesk possono scegliere di aderire per ricevere messaggi di avviso relativi ai servizi di invio degli ordini. Al completamento della transazione, il partner riceverà un messaggio di avviso con l'indicazione dello stato della transazione. Se la transazione è riuscita lo stato sarà "Success", se non è riuscita sarà "Failed". Il messaggio SNS è disponibile per tutti gli scenari di invio degli ordini, sia per i modelli ricorrenti sia per quelli di rinnovo. Se il partner ha sottoscritto il servizio di ricezione delle notifiche di evasione degli ordini, può scegliere uno dei tre metodi di consegna seguenti: o o Messaggio SMS o Endpoint 12 Manuale di riferimento dei servizi Web

13 3.5 Recupero dello stato dell'ordine La risorsa API di recupero dello stato dell'ordine (Get Order Status) restituisce lo stato corrente di un determinato ordine in base al numero di riferimento ottenuto dalla risposta dell'api di invio dell'ordine (Place Order). L'API "Get Order Status" è supportata per tutti i servizi di invio degli ordini, sia negli scenari con modelli ricorrenti sia in quelli di rinnovo. Per recuperare lo stato dell'ordine di acquisto desiderato, è necessario specificare l'id di transazione dell'ordine. 4 Informazioni di riferimento del servizio PlaceOrder Nota: la sezione seguente include lo schema di richiesta e risposta per il servizio PlaceOrder. Per stabilire quali campi sono obbligatori o facoltativi in ciascuno degli schemi seguenti, è necessario sapere quale dei due modelli di abbonamento utilizza il partner (rinnovabile o ricorrente). Al momento, i partner non possono inviare gli ordini combinando i modelli di abbonamento ricorrente e rinnovabile. Questa combinazione genererebbe infatti una risposta di errore. 4.1 Evasione dell'ordine Le operazioni richiamate saranno diverse a seconda del campo action_name specificato nel corpo della richiesta. Se ad esempio action_name è impostato su "initial_order", viene specificata l'opzione "create order", mentre con "add_seats" viene specificata l'opzione "add seat". Di seguito è riportato lo schema di richiesta nei casi in cui il tipo di richiesta prevede la creazione dell'ordine o l'aggiunta di postazioni o prodotti. È anche incluso lo schema di risposta associato. I valori action_name previsti sono i seguenti: initial_order, add_seats, add_products. 4.2 Schema di risposta - Creazione ordine iniziale La tabella seguente, relativa alla creazione degli ordini, include i dettagli dei campi previsti nel corpo della richiesta. Sono richiesti i campi contenenti informazioni sull'utente finale, sul cliente e sul prodotto. Le righe evidenziate si riferiscono agli elementi il cui valore è un oggetto JSON o una serie contenente le informazioni nelle righe rientrate riportate di seguito. Per la corretta nidificazione dei campi, fare riferimento alla sezione relativa ai messaggi di richiesta di esempio. Se esiste un account ed è specificato il CSN corrispondente, è possibile recuperare i dettagli del cliente dai sistemi Autodesk. Se il CSN non è disponibile, i partner devono fornire informazioni quali nome, indirizzo e posizione per poter creare un nuovo account. Nota sul completamento dell'ordine: quando i sistemi Autodesk ricevono un ordine iniziale del partner, le convalide di base per elementi quali SKU, contratto e prezzo vengono eseguite preventivamente nel layer Service del servizio dell'api PlaceOrder. Dopo questa operazione, viene generata e inviata al partner una risposta relativa all'esito positivo o negativo della richiesta con un numero di riferimento (comprensiva di una concatenazione di CSN, numero di ordine di acquisto e data/ora). Utilizzando il numero di riferimento come input per l'api GetOrderStatus, il partner potrà visualizzare lo stato dell'ordine di acquisto. Infine, i sistemi Autodesk aggiorneranno lo stato della transazione da stato in elaborazione a stato completato dopo che l'ordine sarà stato creato in SAP. 13 Manuale di riferimento dei servizi Web

14 Serie di campi Definizione schema Descrizione campo Esempio Tipo di campo Numero max di caratteri Obbligatorio/ Facoltativo (O/F) Commenti Rinnovo/ Ordine Dati contratto EndUse rcontac t action_name opportunity_type opportunity_number po_date po_number customer_po_number Nome dell'evento che il partner eseguirà all'invio dell'ordine Tipo di opportunità di vendita univoca creata per un ordine ID univoco che fa riferimento a un'opportunità di vendita creata per un ordine La data in cui il partner genera l'ordine di acquisto nel proprio sistema interno (può essere una data del sistema o una data passata) Numero dell'ordine di acquisto che il richiedente deve fornire per identificare ogni ordine Numero dell'ordine di acquisto del cliente. "initial_order" Stringa 13 O initial_order "A" Stringa 1 F "A " Stringa 15 F contract_start_date Data di inizio del contratto end_user first_name Nome del Contract Manager (persona di contatto) Formato di data ISO 8601 I valori possibili sono "A" (ACE) e "R" (Rinnovo). Se si specifica uno solo dei due elementi opportunity_type e opportunity_number, è necessario specificare anche l'altro. 10 F ORD1234 Stringa 35 O " " Stringa 35 F Formato di data ISO 8601 Serie di oggetti JSON 10 F O Se l'elemento contract_start_date è specificato, la data deve essere entro 30 giorni dalla data corrente. Se non è specificato, la data è quella corrente. "John" Stringa 35 O 14 Manuale di riferimento dei servizi Web

15 last_name language primary_account_csn Cognome del Contract Manager (persona di contatto) Indirizzo del Contract Manager (persona di contatto) Preferenza di lingua della persona di contatto CSN dell'account utente finale "Smith" Stringa 35 O joh.smith@sttest.com Stringa 80 O standard "EN" Stringa 2 F " " Stringa 10 F primary_account_name Nome account "Partner Inc1" Stringa 35 F primary_account_address_li ne1 primary_account_address_li ne2 primary_account_address_li ne3 Riga 1 indirizzo account "1 Parkway Road" Stringa 35 F Riga 2 indirizzo account "Engineering Dept." Stringa 35 F Riga 3 indirizzo account "Desk 5405" Stringa 35 F Impostato sulla lingua inglese per default, se non specificato Da specificare se noto, altrimenti immettere i dettagli dell'account principale di seguito primary_account_csn non è specificato primary_account_csn non è specificato primary_account_csn non è specificato primary_account_csn non è specificato 15 Manuale di riferimento dei servizi Web

16 primary_account_address_ci ty primary_account_address_s tate primary_account_address_c ountry_code primary_account_address_p ostal_code related_account_csn related_account_name Città account "San Jose" Stringa 35 F Stato dell'account "CA" Stringa 35 F Codice paese account "US" Stringa 35 F Codice postale dell'account "94604" Stringa 35 F CSN dell'account al quale è associato il Contract Manager (può essere lo stesso o diverso) Nome dell'account a cui è associato il Contract Manager " " Stringa 10 F "Partner Inc" Stringa 35 F primary_account_csn non è specificato primary_account_csn non è specificato primary_account_csn non è specificato. Codice ISO a 2 cifre primary_account_csn non è specificato Specificarlo se è noto, altrimenti immettere i dettagli dell'account correlato di seguito related_account_csn non è specificato 16 Manuale di riferimento dei servizi Web

17 related_account_address_lin e1 related_account_address_lin e2 related_account_address_lin e3 related_account_address_cit y related_account_address_st ate related_account_address_c ountry_code Riga 1 indirizzo account correlato Riga 2 indirizzo account correlato Riga 3 indirizzo account correlato "1 Parkway Road" Stringa 35 F "Engineering Dept." Stringa 35 F "Desk 5405" Stringa 35 F Città dell'account correlato "San Jose" Stringa 35 F Stato dell'account correlato "CA" Stringa 35 F Codice paese dell'account correlato "US" Stringa 35 F related_account_csn non è specificato related_account_csn non è specificato related_account_csn non è specificato related_account_csn non è specificato related_account_csn non è specificato related_account_csn non è specificato. Codice ISO a 2 cifre 17 Manuale di riferimento dei servizi Web

18 related_account_address_p ostal_code Codice postale dell'account correlato "94604" Stringa 35 F related_account_csn non è specificato Rivendit ore Acquirent e ListOfLineItems reseller_account_csn CSN dell'account correlato " " Stringa 10 O Partner DL sold_to_account_csn other_parties account_csn partner_type line_items subscription_id CSN dell'account acquirente CSN dell'account della parte (ad es.: agente di inoltro) L'uico valore da immettere è "ForwardingAgent" In caso di ordine ricorrente, per identificare in modo univoco ogni linea di prodotti occorre generare un ID abbonamento univoco per ogni linea di prodotti. È necessario fare riferimento allo stesso ID abbonamento durante le transazioni successive, ad esempio l'aggiunta di postazioni per la stessa linea di prodotti dello stesso contratto. " " Stringa 10 F Serie di oggetti JSON O CSN acquirente partner. Se non viene specificato, assume il valore dell'intestazione di autorizzazione. Rinnovo " " Stringa 10 O Rinnovo "ForwardingAgent" Stringa 18 O Rinnovo "845cd4b7-2f20-4c1aaaa " Serie di oggetti JSON O Stringa 36 O part_number SKU 001G1-WW7929-T210 Stringa 35 O quantity Quantità 1 Numero intero positivo O Formato UUID versione 4. Numero SKU -> part_number 18 Manuale di riferimento dei servizi Web

19 net_amount Importo "39.33" Stringa 20 O delivery_method eu_first_name eu_last_name eu_ eu_language eu_country eu_primary_account_csn eu_primary_account_name eu_primary_account_addres s_line1 Valore del metodo di consegna da passare "ED" Nome del Software Coordinator (persona di contatto) Cognome del Software Coordinator (persona di contatto) del Software Coordinator (persona di contatto) Lingua preferita del Software Coordinator per le comunicazioni Codice paese del Software Coordinator CSN dell'account al quale è associato il Software Coordinator, in questo scenario in cui per una determinata linea di prodotti il Software Coordinator è diverso dal Contract Manager Nome account a cui è associato il Software Coordinator Riga 1 indirizzo account Software Coordinator "ED" Stringa - O Rinnovo "Peter" Stringa 40 O "longslide" Stringa 40 O Peter.longslide@sttest.co m Stringa 80 O Standard: "IT" Stringa 2 O Codice ISO a 2 cifre "US" Stringa 2 O Codice ISO a 2 cifre " " Stringa 10 F "Partner Inc1" Stringa 35 F "1 Parkway Road" Stringa 35 F Da specificare se noto, altrimenti immettere i dettagli dell'eu_primary_accou nt di seguito eu_primary_account_c sn non è specificato eu_primary_account_c sn non è specificato 19 Manuale di riferimento dei servizi Web

20 eu_primary_account_addres s_line2 eu_primary_account_addres s_line3 eu_primary_account_addres s_city eu_primary_account_addres s_state eu_primary_account_addres s_country_code eu_primary_account_addres s_postal_code Riga 2 indirizzo account Software Coordinator Riga 3 indirizzo account Software Coordinator Città dell'account Software Coordinator Stato dell'account Software Coordinator Codice paese dell'account Software Coordinator Codice postale dell'account Software Coordinator "Engineering Dept." Stringa 35 F "Desk 5405" Stringa 35 F "San Jose" Stringa 35 F "CA" Stringa 35 F "US" Stringa 35 F "94604" Stringa 35 F eu_primary_account_c sn non è specificato eu_primary_account_c sn non è specificato eu_primary_account_c sn non è specificato eu_primary_account_c sn non è specificato eu_primary_account_c sn non è specificato. Codice ISO a 2 cifre eu_primary_account_c sn non è specificato 20 Manuale di riferimento dei servizi Web

21 Ora il payload può essere di due tipi. Se il CSN dell'account principale, dell'account correlato o eu_primary_account_csn è noto, è possibile creare il payload come mostrato nella versione avanzata di seguito Payload ordine iniziale esistente Payload ordine iniziale avanzato 21 Manuale di riferimento dei servizi Web

22 4.3 Schema di richiesta - Aggiunta di postazioni Serie di campi Definizione schema Descrizione campo Esempio action_name Nome dell'evento che il partner eseguirà all'invio dell'ordine, ad esempio l'aggiunta di postazioni. Tipo di campo Numero max di caratteri Obbligatorio/ Facoltativo (O/F) Commenti Rinnovo/ "add_seats" Stringa 9 O "add_seats" contract_number Contratto/Numero di contratto " " Stringa 12 O po_date po_number customer_po_number La data in cui il partner genera l'ordine di acquisto nel proprio sistema interno (può essere una data del sistema o una data passata) Numero dell'ordine di acquisto che il richiedente deve fornire per identificare ogni ordine Numero dell'ordine di acquisto del cliente. contract_start_date Data di inizio del contratto net_amount Importo totale (somma dell'importo delle varie voci) " " Data 10 F " " Stringa 35 O " " Stringa 35 F Formato di data ISO F "105.32" Stringa 20 O Se l'elemento contract_start_d ate è specificato, la data deve essere entro 30 giorni dalla data corrente. Se non è specificato, la data è quella corrente. Somma di tutti gli elementi line_items Rinnovo reseller_account_csn CSN dell'account del rivenditore " " Stringa 10 O Rinnovo 22 Manuale di riferimento dei servizi Web

23 line_items sold_to_account_csn CSN dell'account acquirente " " Stringa 10 F opportunity_type opportunity_number line_items subscription_id item_start_date Tipo di opportunità di vendita univoca creata per un ordine ID univoco che fa riferimento a un'opportunità di vendita creata per un ordine In caso di ordine ricorrente, per identificare in modo univoco ogni linea di prodotti occorre generare un ID abbonamento univoco per ogni linea di prodotti. È necessario fare riferimento allo stesso ID abbonamento durante le transazioni successive, ad esempio l'aggiunta di postazioni per la stessa linea di prodotti dello stesso contratto. Data di inizio fatturazione per la postazione aggiuntiva "A" Stringa 1 F "A " Stringa 15 F "914fadc9-2b67-476e-b480- e0e232e98745" Serie di oggetti JSON O Stringa 36 O Se non viene specificato, assume il valore dell'intestazione di autorizzazione. I valori possibili sono "A" (ACE) e "R" (Rinnovo). Se si specifica uno solo dei due elementi opportunity_typ e e opportunity_nu mber, è necessario specificare anche l'altro. Stringa UUID versione 4 Rinnovo " " Data 10 F Rinnovo part_number SKU "321K T979" Stringa 35 O quantity Quantità 7 Numero intero positivo O 23 Manuale di riferimento dei servizi Web

24 eu_ eu_first_name del Software Coordinator (persona di contatto) Nome del Software Coordinator (persona di contatto) Stringa 80 O Rinnovo "John" Stringa 40 O Rinnovo eu_last_name Cognome del Software Coordinator (persona di contatto) "Smith" Stringa 40 O Rinnovo net_amount Importo "105.32" Stringa 20 O serial_numbers Numero di serie [" "] Serie di stringhe O Importo netto per ogni line_item Rinnovo 4.4 Schema di richiesta - Aggiunta di prodotti Serie di campi Definizione schema Descrizione campo Esempio Tipo di campo Numero max di caratteri Obbligatorio/ Facoltativo (F) Commenti Rinnovo/ action_name Nome dell'evento che il partner eseguirà, ad esempio "add_products" Stringa 12 O "add_products" l'aggiunta di prodotti contract_number Contratto/Numero di contratto " " Stringa 12 O po_number Numero dell'ordine di acquisto che il richiedente deve fornire per identificare ogni ordine " " Stringa 35 O net_amount po_date Importo totale (somma dell'importo delle varie voci) La data in cui il partner genera l'ordine di acquisto nel proprio sistema interno (può essere una data del sistema o una data passata) "105.32" Stringa 20 O " " Data 10 F Somma di tutti gli elementi line_items Impostato per default sulla data di sistema 24 Manuale di riferimento dei servizi Web customer_po_number Numero di PO del cliente " " Stringa 35 F

25 line_items contract_start_date Data di inizio del contratto " " reseller_account_csn CSN dell'account del rivenditore Formato di data ISO F Se l'elemento contract_start_date è specificato, la data deve essere entro 30 giorni dalla data corrente. Se non è specificato, la data è quella corrente. 25 Manuale di riferimento dei servizi Web Rinnovo " " Stringa 10 O Rinnovo sold_to_account_csn CSN dell'account acquirente " " Stringa 10 F opportunity_type opportunity_number line_items subscription_id Tipo di opportunità di vendita univoca creata per un ordine ID univoco che fa riferimento a un'opportunità di vendita creata per un ordine In caso di ordine ricorrente, per identificare in modo univoco ogni linea di prodotti occorre generare un ID abbonamento univoco per ogni linea di prodotti. È necessario fare riferimento allo stesso ID abbonamento durante le transazioni successive, ad esempio l'aggiunta di postazioni per la stessa linea di prodotti dello stesso contratto. "A" Stringa 1 F "A " Stringa 15 F "914fadc9-2b67-476e-b480- e0e232e98745" Serie di oggetti JSON O Stringa 36 O Se non viene specificato, assume il valore dell'intestazione di autorizzazione. I valori possibili sono "A" (ACE) e "R" (Rinnovo). Se si specifica uno solo dei due elementi opportunity_type e opportunity_numbe r, è necessario specificare anche l'altro. Stringa UUID versione 4 Rinnovo

26 part_number SKU "321K T868" Stringa 35 O quantity Quantità 7 item_start_date eu_ eu_first_name eu_last_name end_user first_name last_name language Data di inizio fatturazione per la postazione aggiuntiva del Software Coordinator (persona di contatto) Nome del Software Coordinator (persona di contatto) Cognome del Software Coordinator (persona di contatto) Nome del Contract Manager (persona di contatto) Cognome del Contract Manager (persona di contatto) Indirizzo del Contract Manager (persona di contatto) Preferenza di lingua della persona di contatto Numero intero positivo O " " Data 10 F Rinnovo "admin@autodesk.com" Stringa 80 O Rinnovo "John" Stringa 40 O Rinnovo "Smith" Stringa 40 O Rinnovo Oggetto JSON F "John" Stringa 35 O "Smith" Stringa 35 O john@autodesk.com Stringa 80 O "EN" Stringa 2 F primary_account_csn CSN dell'account utente finale " " Stringa 10 F primary_account_name Nome account "Arthur Doe" Stringa 35 F Impostato sulla lingua inglese per default, se non specificato Da specificare se noto, altrimenti immettere i dettagli dell'account principale di seguito primary_account_c sn non è specificato 26 Manuale di riferimento dei servizi Web

27 primary_account_address_line1 Riga 1 indirizzo account "1 Parkway Road" Stringa 35 F primary_account_address_line2 Riga 2 indirizzo account "Engineering Dept." Stringa 35 F primary_account_address_line3 Riga 3 indirizzo account "Desk 5405" Stringa 35 F primary_account_address_city Città account "San Jose" Stringa 35 F primary_account_address_state Stato dell'account "CA" Stringa 3 F primary_account_address_countr y_code primary_account_address_postal _code Codice paese account "US" Stringa 3 F Codice postale dell'account "94604" Stringa 9 F net amount Importo "105.32" Stringa 20 O primary_account_c sn non è specificato primary_account_c sn non è specificato primary_account_c sn non è specificato primary_account_c sn non è specificato primary_account_c sn non è specificato primary_account_c sn non è specificato. Codice ISO a 2 cifre primary_account_c sn non è specificato Importo netto per ogni line_item 27 Manuale di riferimento dei servizi Web

28 4.5 Schema di richiesta - Rinnovo Serie di campi Definizione schema Descrizione campo Esempio Tipo di campo Numero max di caratteri Obbligatorio/ Facoltativo (F) Commenti Rinnovo/ action_name Nome dell'evento che il partner eseguirà all'invio dell'ordine, ad esempio il rinnovo "renew" Stringa 5 O "renew" Rinnovo order_date Data in cui l'ordine è stato inviato " " Data 10 F Rinnovo po_date po_number customer_po_number La data in cui il partner genera l'ordine di acquisto nel proprio sistema interno (può essere una data del sistema o una data passata) Numero dell'ordine di acquisto che il richiedente deve fornire per identificare ogni ordine Numero dell'ordine di acquisto del cliente. " " Data 10 F Rinnovo " " Stringa 35 O Rinnovo " " Stringa 35 F Rinnovo contract_number Contratto/Numero di contratto " " Stringa 12 O Rinnovo reseller_account_csn CSN dell'account del rivenditore " " Stringa 10 O Rinnovo Se non viene specificato, sold_to_account_csn CSN dell'account acquirente " " Stringa 10 F assume il valore dell'intestazione di autorizzazione. opportunity_type I valori possibili Tipo di opportunità di vendita "A" Stringa 1 F sono "A" (ACE) univoca creata per un ordine e "R" (Rinnovo). Se si specifica uno solo dei due opportunity_number elementi ID univoco che fa riferimento a opportunity_type un'opportunità di vendita creata per "A " Stringa 15 F e un ordine opportunity_num ber, è necessario 28 Manuale di riferimento dei servizi Web Rinnovo Rinnovo Rinnovo

29 line_items Serie di oggetti JSON O specificare anche l'altro. Rinnovo line_items part_number SKU "123K T979" Stringa 35 O Rinnovo quantity Quantità 7 Numero intero positivo net_amount Importo "105.32" Stringa 20 O serial_numbers Numero di serie [" "] Serie di stringhe O O Importo netto per ogni line_item Rinnovo Rinnovo Rinnovo 29 Manuale di riferimento dei servizi Web

30 4.6 Aggiornamento ordine di acquisto ricorrente La risorsa API di aggiornamento dell'ordine di acquisto ricorrente (Update Recurring Purchase Order) gestisce l'aggiornamento di un numero di ordini di acquisto per la fatturazione È possibile usare l'api di aggiornamento dell'ordine di acquisto ricorrente solo per i partner che si sono abbonati a un modello Tale abbonamento si rinnoverà automaticamente in base all'intervallo selezionato (con frequenza trimestrale, annuale, pluriennale). L'ordine aperto esistente verrà aggiornato con un nuovo numero di PO e, di conseguenza, con la fatturazione Per poter applicare gli aggiornamenti, è necessario che la richiesta venga inviata almeno 48 ora prima della fatturazione ricorrente pianificata. 4.7 Schema di richiesta - Aggiornamento ordine di acquisto ricorrente Nota: il seguente schema si applica solo ai partner che utilizzano un modello di abbonamento Descrizione campo Definizione schema Esempio Tipo di campo Lunghezza Commenti action_name "po_update" Stringa 9 Deve essere sempre "po_update" contract_number Stringa 30 Obbligatorio po_number Stringa 35 Obbligatorio 4.8 Recupero dello stato dell'ordine Il micro-servizio di recupero dello stato dell'ordine (Get Order Status) è una semplice richiesta get con il formato seguente: che prevede un solo campo nello schema di richiesta descritto di seguito. È anche incluso lo schema di risposta associato, ovvero uno stato di esito positivo o negativo. 4.9 Schema di richiesta - Recupero dello stato dell'ordine [solo ordine ricorrente iniziale] Descrizione campo Percorso URL Definizione schema reference number Esempio /order/status/ Tipo di campo Stringa Lunghezza Min. 20 Max. 40 caratteri Commenti Obbligatorio. Parte del percorso URL 4.10 Revoca dell'ordine Di seguito è riportato lo schema per le richieste di rimozione di una postazione o di un prodotto, di annullamento di un ordine o di reso di un ordine. È anche incluso lo schema di risposta associato. Le richieste di revoca di un ordine sono disponibili solo per i partner che utilizzano un modello di abbonamento Attualmente, i resi degli ordini non sono disponibili ma saranno inclusi in una versione futura. 30 Manuale di riferimento dei servizi Web

31 I valori action_name possibili sono: remove seats, remove products, cancel Schema di richiesta - Rimozione postazioni, rimozione prodotti, annullamento ordine Nella tabella che segue sono riportati i dettagli dei campi previsti nel corpo della richiesta per le modifiche da apportare a un ordine esistente, ad esempio la riduzione della quantità di postazioni o la rimozione dei un altro prodotto. Nota: il seguente schema si applica solo ai partner che utilizzano un modello di abbonamento Al momento non è disponibile alcuno schema per il modello di abbonamento rinnovabile. Descrizione campo Intestazione contratto Livello voce Definizione schema Esempio Tipo di campo Obbligatorio/ Facoltativo Lunghezza Commenti action_name "remove seats" Stringa O 15 Rimozione postazioni, rimozione prodotti, annullamento contract_number Stringa O 30 Obbligatorio line_items subscription_id "bac19ced- 7aa a c8e98d" quantity 3 Serie di oggetti JSON O Stringa O 36 Numero intero positivo O 13 Non richiesto per l'annullamento Non richiesto per l'annullamento Richiesto solo per la rimozione di postazioni. Numero di postazioni da rimuovere 4.12 Schema di risposta - Creazione ordine iniziale Una semplice risposta dall'api che verifica se una chiamata è stata sottoposta ai processi di autenticazione, autorizzazione e convalida ed è ora in esecuzione nei sistemi backend Autodesk. Definizione schema Esempio Tipo di campo status "OK" Stringa message "Your order is being processed." Stringa reference number Stringa 4.13 Schema di risposta - Aggiornamento ordine di acquisto ricorrente Una semplice risposta dall'api che verifica se una chiamata è stata sottoposta ai processi di autenticazione, autorizzazione e convalida ed è ora in esecuzione nei sistemi backend Autodesk. 31 Manuale di riferimento dei servizi Web

32 Definizione schema Esempio Tipo di campo status "FAILED" Stringa message "Contract number does not exist" "Cannot add seats for a cancelled Product with Stringa Subscription ID <Subs ID>" reference number Stringa Definizione schema 4.14 Schema di risposta - Recupero dello stato dell'ordine La risposta dall'api di stato restituisce lo stato dell'ordine in base all'id di transazione specificato. Lo stato indicherà se l'ordine è in corso di elaborazione, completato o non riuscito con un numero di richiesta di supporto per il codice di stato. Esempio Tipo di campo status "OK", "FAILED", "Order Accepted" Stringa message "Order Processing" "Order was created successfully." "Order processing error. Please contact Autodesk (error code 71)" "Order processing error. Please contact Autodesk CASE# " Stringa last updated " :15:54 UTC" Stringa 4.15 Schema di risposta - Rimozione postazione, rimozione prodotto, annullamento ordine [solo modello ricorrente] Una semplice risposta dall'api che verifica se una chiamata è stata sottoposta ai processi di autenticazione, autorizzazione e convalida ed è ora in esecuzione nei sistemi backend Autodesk. Definizione schema Esempio Tipo di campo status "FAILED" Stringa message "SKU is not active." Stringa reference number Stringa 4.16 Schema di risposta - Notifica SNS Di seguito sono riportati i dati inclusi in una risposta di notifica SNS. La risposta fornisce i dettagli sullo stato dell'ordine inviato. In caso di esito positivo, il numero di entità viene completato con il numero dell'ordine di vendita fornito dai sistemi di back office. Se si verifica un errore durante l'elaborazione dell'ordine, nel campo del messaggio è indicato un codice di errore. 32 Manuale di riferimento dei servizi Web

33 Definizione schema Esempio Tipo di campo csn " " Stringa transaction_id " " Stringa status "Success", "Failed" Stringa message "Order was created successfully." "Add seat order was updated successfully." "Order processing error. Please contact Autodesk (error code 71)" Stringa entity_number " " Stringa 33 Manuale di riferimento dei servizi Web

34 5 Messaggi di esempio 5.1 Messaggio di richiesta - Evasione ordine, ordine iniziale, modello di abbonamento ricorrente Message Headers Authorization: Bearer <<Access Token>> Content-Type: application/json CSN: <<CSN>> Body "action_name": "initial_order", "po_number": " ", "customer_po_number": " ", "opportunity_type": 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", 34 Manuale di riferimento dei servizi Web

35 "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" ] Messaggio di risposta - Evasione ordine, ordine iniziale "status": "OK", "message": "Your order is being processed", "reference number": " INITIAL ORDER 9-27 arc " 35 Manuale di riferimento dei servizi Web

36 5.2 Messaggio di richiesta - Evasione ordine, ordine iniziale, modello di abbonamento rinnovabile 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": " ": "rawr.stein@ .com", "first_name": "Rawr", "last_name": "Stein", "primary_account_name": "Rawrstein 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": "Rawrstein 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", 36 Manuale di riferimento dei servizi Web

37 "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_type": "ForwardingAgent" ], "line_items": [ "part_number": "978G1-WW2859-T981", "quantity": 1, "net_amount": "1570.8", "delivery_method": "ED", "part_number": "978G1-WW6919-T229", "quantity": 1, "net_amount": "1293.6", "delivery_method": "ED" ] Messaggio di risposta - Evasione ordine, ordine iniziale "status": "OK", "message": "Your order is being processed", "reference number": " INITIAL ORDER 9-27 arc " 37 Manuale di riferimento dei servizi Web

38 5.3 Messaggio di richiesta - Evasione ordine, aggiunta di postazioni, modello di abbonamento ricorrente 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" ] Messaggio di risposta - Evasione ordine, aggiunta di postazioni, modello di abbonamento ricorrente "status": "OK", "message": "Your order is being processed", "reference number": " INITIAL ORDER 9-27 arc " 38 Manuale di riferimento dei servizi Web

39 5.4 Messaggio di richiesta - Evasione ordine, aggiunta di postazioni, modello di abbonamento rinnovabile 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": [ " " ] ] 39 Manuale di riferimento dei servizi Web

40 5.4.1 Messaggio di risposta - Evasione ordine, aggiunta di postazioni, modello di abbonamento rinnovabile "status": "OK", "message": "Your order is being processed", "reference number": " INITIAL ORDER 9-27 arc " 5.5 Messaggio di richiesta - Evasione ordine, aggiunta di prodotti, modello di abbonamento ricorrente 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" ] 40 Manuale di riferimento dei servizi Web

41 5.5.1 Messaggio di risposta - Evasione ordine, aggiunta di prodotti, modello di abbonamento ricorrente "status": "OK", "message": "Your order is being processed", "reference number": " INITIAL ORDER 9-27 arc " 5.6 Messaggio di richiesta - Evasione ordine, aggiunta di prodotti, modello di abbonamento rinnovabile 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" ] 41 Manuale di riferimento dei servizi Web