---
title: Configurazione API + Gestione automatizzata degli ordini (AOM) + Reporting automatizzato dell'utilizzo
slug: it/configurazione-api-gestione-automatizzata-degli-ordini-aom-reporting-automatizzato-dellutilizzo
icon: {"faIcon":"fa-brands fa-wordpress"}
createdAt: 2026-03-10T18:19:01.825Z
---

# Parte 0: Configurazione

WeTransact invia eventi all'**Endpoint dell'argomento di Event Grid** configurato in **Impostazioni** nel WeTransact Portal.

### 3.1 Accesso API

:::BlockQuote
📖 Riferimento API: https\://apidocs.wetransact.io/openapi/subscriptions
:::

Se desidera controllare l'attivazione in modo programmatico, ha bisogno di una chiave API.

**Per generare una chiave:**

1. Vada al suo portale WeTransact: yourcompany.wetransact.io
2. Vada a **Impostazioni** → **Integrazioni&#x20;**→ scorra fino alla sezione **Accesso API**
3. Faccia clic su **Genera**
4. Copi immediatamente la chiave e la memorizzi in un gestore di segreti

![](https://api.archbee.com/api/optimize/wlBoYP3-_D88k8I6lqBSW/2N4POKUZ-0O8BJSNQvqtP_fig4-api-key-created.png)

:::BlockQuote
⚠️ **La chiave è visibile una sola volta.** Dopo aver lasciato la pagina non verrà più mostrata. Se compromessa, ne generi una nuova per invalidare la vecchia chiave
:::

# <font color="#4338CA">Parte 1\: Gestione automatizzata degli ordini (AOM)</font>

## 1. Introduzione

📖 Riferimento API: https\://apidocs.wetransact.io/openapi/subscriptions

Quando i publisher di Marketplace dispongono di un processo di provisioning automatizzato, la maggior parte di loro desidera collegare il canale di acquisto Marketplace a tale processo. Tramite la piattaforma WeTransact ciò può essere ottenuto seguendo questa guida.

## 2. Processo dell'ordine

Quando si vende tramite Microsoft Marketplace, Microsoft determina il flusso degli ordini. Quando AOM è abilitato, WeTransact agisce come middleware tra Microsoft Marketplace e il suo sistema di gestione degli ordini.

**Come funziona:**

1. Il cliente effettua un acquisto → viene reindirizzato alla WeTransact Landing Page
2. L'acquirente fa clic su **Conferma acquisto** → l'ordine viene inviato al WeTransact Portal
3. WeTransact invia un evento CreateSubscription al suo endpoint Event Grid
4. Il suo sistema esegue il provisioning e attiva la sottoscrizione
5. WeTransact notifica a Microsoft Marketplace la conferma dell'attivazione

![](https://api.archbee.com/api/optimize/wlBoYP3-_D88k8I6lqBSW/fBzcvZrJQXXciFY4G1O9u_fig1-order-flow.png)

**Eventi successivi del ciclo di vita** — dopo l'attivazione, WeTransact inoltra anche questi:

| Evento                            | Descrizione                                                                               |
| --------------------------------- | ----------------------------------------------------------------------------------------- |
| Annullamento                      | Il cliente annulla; il servizio termina alla fine del periodo di impegno                  |
| Sospensione                       | Microsoft non è riuscita a riscuotere il pagamento; consideri la sospensione del servizio |
| Ripristino                        | Pagamento riscosso dopo la sospensione; ripristini il servizio                            |
| Rinnovo                           | Sottoscrizione rinnovata manualmente o tramite rinnovo automatico                         |
| Modifica del piano                | Il cliente ha modificato il livello del piano (ad es. Basic → Standard)                   |
| Modifica del numero di postazioni | Il cliente ha modificato il numero di utenti (solo piani Per-User)                        |

##

### 3 Attivazione della sottoscrizione

Gli editori devono attivare un abbonamento **entro 30 giorni** oppure Microsoft lo annullerà automaticamente.

:::BlockQuote
🚨 **Finestra di 30 giorni.** Configuri il monitoraggio e gli avvisi sulla sua coda ordini per evitare di perdere questa scadenza.
:::

Esistono tre modi per attivare:

**Opzione 1 — Manuale (portale)** Vada a **Ordini** → faccia clic su **Agisci** → approvi o rifiuti.

![](https://api.archbee.com/api/optimize/wlBoYP3-_D88k8I6lqBSW/DJKA9SwNjidNaZTqNGKNu_fig5-manual-activation.png)

**Opzione 2 — Approvazione automatica** Vada a **Elenco prodotti → Piano tariffario** → abiliti **Approva automaticamente i nuovi ordini** (disponibile per tutti i piani o per un piano specifico).

Per tutti i piani

![](https://api.archbee.com/api/optimize/wlBoYP3-_D88k8I6lqBSW/j6bnG7ZRhf8FZrsaVWxso_image.png)

Per un piano specifico

![](https://api.archbee.com/api/optimize/wlBoYP3-_D88k8I6lqBSW/GZAvJSjulWzSK7JD4mrgP_image.png)

**Opzione 3 — Tramite API** *(consigliato per AOM)* Riceva l'evento CreateSubscription, completi il provisioning, quindi chiami l'API per attivare.

### 3.2 Attivazione tramite API

| &#x20;           |                                                                                                     |
| ---------------- | --------------------------------------------------------------------------------------------------- |
| **Metodo**       | POST                                                                                                |
| **URL**          | https\://\[YOUR-SUBDOMAIN].wetransact.io/api/v1.0/subscriptions/\[SUBSCRIPTION-ID]/actions/activate |
| **Intestazione** | x-api-key: \[YOUR API KEY]                                                                          |

**Risposte:**

- 200 OK — elaborato correttamente
- 500 — operazione non riuscita, contatti il supporto WeTransact

:::BlockQuote
ℹ️ Un 200 non garantisce l'attivazione. Se fallisce downstream, WeTransact invierà un evento ActivateSubscriptionFailed in modo asincrono. Contatti il supporto se ciò accade.
:::

## 4. Eventi e messaggi

### 4.1 CreateSubscription

Inviato quando viene creato un abbonamento. Contiene tutto il necessario per il provisioning e l'attivazione.

| Campo                     | Tipo                   | Descrizione                                                                     |
| ------------------------- | ---------------------- | ------------------------------------------------------------------------------- |
| MarketplaceSubscriptionId | GUID                   | ID assegnato da Microsoft. Da utilizzare come identificatore univoco.           |
| Created                   | DATETIME               | Timestamp della creazione della sottoscrizione                                  |
| CompanyName               | STRING                 | Nome dell'azienda acquirente                                                    |
| MarketplaceOfferId        | STRING                 | ID prodotto in Partner Center                                                   |
| MarketplacePlanId         | STRING                 | ID del piano (SKU) in Partner Center                                            |
| SeatQuantity              | STRING *(facoltativo)* | Numero di postazioni — solo piani Per-User                                      |
| TermUnit                  | STRING                 | P1M / P1Y / P2Y / P3Y                                                           |
| InitialUserEmail          | STRING                 | Email dell'acquirente                                                           |
| AdditionalDetails         | STRING *(facoltativo)* | Campi aggiuntivi della Landing Page, come JSON                                  |
| Channel                   | STRING                 | Diretto o Indiretto (CSP)                                                       |
| BeneficiaryEmail          | STRING *(facoltativo)* | Email dell'utente finale — diversa da quella dell'acquirente quando tramite CSP |

json

:::BlockQuote
\{  "MarketplaceSubscriptionId": "a1fabe21-7904-4c2f-932d-5253a35e97d0",  "Created": "2025-03-07T12:34:56.7892",  "CompanyName": "EndCustomer",  "MarketplaceOfferId": "offer-123",  "MarketplacePlanId": "plan-premium",  "SeatQuantity": "10",  "TermUnit": "P1Y",  "InitialUserEmail": "purchasing\@contoso.com",  "AdditionalDetails": "\{}",  "Channel": "Indirect",  "BeneficiaryEmail": "user\@endcustomer.io",  "ResellerName": "Contoso"}
:::

### 4.2 AnnullaSottoscrizione

Inviato quando un cliente annulla. Il servizio rimane attivo fino al termine del periodo impegnato.

| Campo                     | Tipo | Descrizione                       |
| ------------------------- | ---- | --------------------------------- |
| MarketplaceSubscriptionId | GUID | ID della sottoscrizione annullata |

json

:::BlockQuote
\{ "MarketplaceSubscriptionId": "a1fabe21-7904-4c2f-932d-5253a35e97d0" }
:::

### 4.3 SuspendSubscription

Inviato quando Microsoft non riesce a riscuotere il pagamento. Valuti la sospensione del servizio o il contatto con il cliente.

| Campo                     | Tipo | Descrizione                     |
| ------------------------- | ---- | ------------------------------- |
| MarketplaceSubscriptionId | GUID | ID della sottoscrizione sospesa |

json

:::BlockQuote
\{ "MarketplaceSubscriptionId": "a1fabe21-7904-4c2f-932d-5253a35e97d0" }
:::

### 4.4 ReinstateSubscription

Inviato quando Microsoft riscuote il pagamento dopo una sospensione. Ripristini il servizio se era stato sospeso.

| Campo                     | Tipo | Descrizione                             |
| ------------------------- | ---- | --------------------------------------- |
| MarketplaceSubscriptionId | GUID | ID della sottoscrizione da ripristinare |

json

:::BlockQuote
\{ "MarketplaceSubscriptionId": "a1fabe21-7904-4c2f-932d-5253a35e97d0" }
:::

### 4.5 RenewSubscription

Inviato quando una sottoscrizione viene rinnovata manualmente o tramite rinnovo automatico.

| Campo                     | Tipo | Descrizione                       |
| ------------------------- | ---- | --------------------------------- |
| MarketplaceSubscriptionId | GUID | ID della sottoscrizione rinnovata |

json

:::BlockQuote
\{ "MarketplaceSubscriptionId": "a1fabe21-7904-4c2f-932d-5253a35e97d0" }
:::

### 4.6 ChangePlan

Inviato quando un cliente cambia livello del piano. Aggiorni i feature flag, i diritti o le allocazioni delle risorse.

| Campo                     | Tipo   | Descrizione                         |
| ------------------------- | ------ | ----------------------------------- |
| MarketplaceSubscriptionId | GUID   | ID della sottoscrizione interessata |
| MarketplacePlanId         | STRING | ID del nuovo piano (SKU)            |

json

:::BlockQuote
\{  "MarketplaceSubscriptionId": "a1fabe21-7904-4c2f-932d-5253a35e97d0",  "MarketplacePlanId": "plan-premium"}
:::

### 4.7 ModificaSeatQuantity

Inviato quando un cliente modifica il numero di postazioni. Solo per i piani Per-User. Aggiorni di conseguenza le allocazioni di calcolo/risorse.

| Campo                     | Tipo   | Descrizione                         |
| ------------------------- | ------ | ----------------------------------- |
| MarketplaceSubscriptionId | GUID   | ID della sottoscrizione interessata |
| SeatQuantity              | STRING | Nuovo numero totale di postazioni   |

json

:::BlockQuote
\{  "MarketplaceSubscriptionId": "a1fabe21-7904-4c2f-932d-5253a35e97d0",  "SeatQuantity": "150"}
:::

### 4.8 AttivazioneSubscriptionFailed

Inviato quando l'attivazione fallisce downstream dopo che una chiamata API ha restituito 200 OK. Contatti immediatamente il supporto WeTransact.

| Campo                     | Tipo | Descrizione                                             |
| ------------------------- | ---- | ------------------------------------------------------- |
| MarketplaceSubscriptionId | GUID | ID della sottoscrizione che non è riuscita ad attivarsi |

json

:::BlockQuote
\{ "MarketplaceSubscriptionId": "a1fabe21-7904-4c2f-932d-5253a35e97d0" }
:::

## 5. Instradamento dei messaggi

Tutti i messaggi includono un campo Subject per il filtraggio nella sua sottoscrizione Event Grid:

| Subject                    | Trigger                             |
| -------------------------- | ----------------------------------- |
| CreateSubscription         | Nuovo ordine effettuato             |
| CancelSubscription         | Cancellazione da parte del cliente  |
| SuspendSubscription        | Errore di pagamento                 |
| ReinstateSubscription      | Pagamento risolto                   |
| RenewSubscription          | Sottoscrizione rinnovata            |
| ChangePlan                 | Livello del piano modificato        |
| ChangeSeatQuantity         | Numero di postazioni modificato     |
| ActivateSubscriptionFailed | Attivazione downstream non riuscita |

# <font color="#1300fffb">Parte 2\: Reporting automatico dell'utilizzo</font>

## Introduzione

📖 Riferimento API: https\://apidocs.wetransact.io/openapi/subscriptions

Alcuni publisher del Marketplace hanno la necessità di riportare l'utilizzo tramite un API. Questo è necessario quando la frequenza di reporting è elevata (più di una volta al mese). Questa sezione spiega come viene utilizzata la WeTransact API per riportare l'utilizzo.

Il reporting dell'utilizzo deve sempre avvenire rispetto a una sottoscrizione attiva, identificabile in modo univoco tramite un GUID. Quando tale GUID viene ottenuto, il publisher può riportare l'utilizzo definendo gli importi per meter. Tutta la documentazione API è disponibile all'indirizzo:&#x20;

https\://apidocs.wetransact.io/openapi

Questa specifica API descrive tutti gli altri dettagli API correlati, inclusi esempi di messaggi di richiesta e risposta. La sezione 7.1 spiega come ottenere l'accesso alla WeTransact API.

![](https://api.archbee.com/api/optimize/wlBoYP3-_D88k8I6lqBSW/5SLXHR6Fv0okpak6-Blh4_.blob)

Nel **passaggio 1** il sistema di reporting del publisher recupera l'ID della sottoscrizione corretto (nome esatto del campo: marketplaceSubscriptionId) ottenendo prima tutte le sottoscrizioni tramite l'endpoint GET /subscriptions. Per includere informazioni sui meter validi per la sottoscrizione, deve essere aggiunto il parametro di query includeMeters=true. Se l'ID della sottoscrizione e i dettagli del meter sono già archiviati, questo passaggio può essere saltato.

Nel **passaggio 2**, il sistema lato publisher deve effettuare un addebito sulla sottoscrizione identificata dall'ID della sottoscrizione. Questo viene fatto chiamando l'endpoint POST /subscriptions/&#x7B;id}/charge. Qui il sistema definisce l'ID della sottoscrizione da addebitare, nonché l'ID del meter e l'importo. La piattaforma WeTransact si occupa dello scambio di messaggi con Microsoft Marketplace (**passaggio 3**).

### 7.1 Accesso API

Quando i publisher desiderano automatizzare il reporting dell'utilizzo, è necessario l'accesso API. Se non è stata creata alcuna chiave API, la sezione Settings mostrerà un pulsante Generate.
