API di sottoscrizione per l'evasione SaaS v2 nel marketplace commerciale Microsoft

Articolo
11/10/2023

Questo articolo descrive la versione 2 delle API di sottoscrizione di evasione SaaS.

Risolvere una sottoscrizione acquistata

L'endpoint di risoluzione consente all'editore di scambiare il token di identificazione dell'acquisto dal marketplace commerciale (detto token in Acquistato ma non ancora attivato) a un ID sottoscrizione SaaS acquistato permanente e ai relativi dettagli.

Quando un cliente viene reindirizzato all'URL della pagina di destinazione del partner, il token di identificazione del cliente viene passato come parametro del token in questa chiamata URL. Si prevede che il partner usi questo token e faccia una richiesta per risolverlo. La risposta dell'API Resolve contiene l'ID sottoscrizione SaaS e altri dettagli per identificare in modo univoco l'acquisto. Il token fornito con la chiamata URL della pagina di destinazione è valido per 24 ore. Se il token ricevuto è scaduto, è consigliabile fornire le indicazioni seguenti all'utente finale:

"Non siamo riusciti a identificare questo acquisto. Riaprire questa sottoscrizione SaaS nel portale di Azure o nel Centro Amministrazione Microsoft 365 e selezionare di nuovo "Configura account" o "Gestisci account".

La chiamata all'API Resolve restituisce i dettagli della sottoscrizione e lo stato delle sottoscrizioni SaaS in tutti gli stati supportati.

Inserisci `https://marketplaceapi.microsoft.com/api/saas/subscriptions/resolve?api-version=<ApiVersion>`

Parametri di query:

Parametro	Valore
`ApiVersion`	Usare 2018-08-31.

Intestazioni della richiesta:

Parametro	Valore
`content-type`	`application/json`
`x-ms-requestid`	Valore stringa univoco per tenere traccia della richiesta dal client, preferibilmente un GUID. Se questo valore non viene specificato, ne viene generato uno e fornito nelle intestazioni della risposta.
`x-ms-correlationid`	Valore stringa univoco per l'operazione sul client. Questo parametro mette in correlazione tutti gli eventi dell'operazione del client con gli eventi sul lato server. Se questo valore non viene specificato, ne viene generato uno e fornito nelle intestazioni della risposta
`authorization`	Token di accesso univoco che identifica l'autore che effettua questa chiamata API. Il formato è `"Bearer <access_token>"` quando il valore del token viene recuperato dall'editore, come illustrato in Ottenere un token basato sull'app Microsoft Entra.
`x-ms-marketplace-token`	Parametro del token di identificazione dell'acquisto da risolvere. Il token viene passato nella chiamata URL della pagina di destinazione quando il cliente viene reindirizzato al sito Web del partner SaaS (ad esempio: `https://contoso.com/signup?token=<token><authorization_token>`). Il valore del token codificato fa parte dell'URL della pagina di destinazione, quindi deve essere decodificato prima che venga usato come parametro in questa chiamata API. Di seguito è riportato un esempio di stringa codificata nell'URL: `contoso.com/signup?token=ab%2Bcd%2Fef`, dove il token è `ab%2Bcd%2Fef`. Lo stesso token decodificato è: `Ab+cd/ef`

Codici di risposta:

Codice: 200 Restituisce identificatori univoci di sottoscrizione SaaS in base all'oggetto x-ms-marketplace-token specificato.

Esempio di corpo della risposta:

{
  "id": "<guid>", // purchased SaaS subscription ID
  "subscriptionName": "Contoso Cloud Solution", // SaaS subscription name
  "offerId": "offer1", // purchased offer ID
  "planId": "silver", // purchased offer's plan ID
  "quantity": 20, // number of purchased seats, might be empty if the plan is not per seat
  "subscription": { // full SaaS subscription details, see Get Subscription APIs response body for full description
    "id": "<guid>",
    "publisherId": "contoso",
    "offerId": "offer1",
    "name": "Contoso Cloud Solution",
    "saasSubscriptionStatus": " PendingFulfillmentStart ",
    "beneficiary": {
      "emailId": "test@test.com",
      "objectId": "<guid>",
      "tenantId": "<guid>",
      "puid": "<ID of the user>"
    },
    "purchaser": {
      "emailId": "test@test.com",
      "objectId": "<guid>",
      "tenantId": "<guid>",
      "puid": "<ID of the user>"
    },
    "planId": "silver",
    "term": {
      "termUnit": "P1M",
      "startDate": "2022-03-07T00:00:00Z", //This field is only available after the saas subscription is active.
      "endDate": "2022-04-06T00:00:00Z" //This field is only available after the saas subscription is active.
    },
      "autoRenew": true/false,
    "isTest": true/false,
    "isFreeTrial": false,
    "allowedCustomerOperations": <CSP purchases>["Read"] <All Others> ["Delete", "Update", "Read"],
      "sandboxType": "None",
      "lastModified": "0001-01-01T00:00:00", //[Deprecated] Do not use.
      "quantity": 5,
    "sessionMode": "None"
  }
}

Codice: 400 Richiesta non valida. x-ms-marketplace-token mancante, in formato non valido, non valido o scaduto.

Codice: 403 Accesso negato. Il token di autorizzazione non è valido, è scaduto o non è stato specificato. La richiesta sta tentando di accedere a una sottoscrizione SaaS per un'offerta pubblicata con un ID app Microsoft Entra diverso da quello usato per creare il token di autorizzazione.

Questo errore è spesso un sintomo di non eseguire correttamente la registrazione SaaS.

Codice: errore interno del server 500. Ripetere la chiamata API. Se l'errore persiste, contattare il supporto tecnico Microsoft.

Attivare una sottoscrizione

Dopo aver configurato l'account SaaS per un utente finale, l'editore deve chiamare l'API Attiva sottoscrizione sul lato Microsoft. Il cliente non viene fatturato a meno che questa chiamata API non riesca.

Inserisci `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/activate?api-version=<ApiVersion>`

Parametri di query:

Parametro	Valore
`ApiVersion`	Usare 2018-08-31.
`subscriptionId`	Identificatore univoco della sottoscrizione SaaS acquistata. Questo ID viene ottenuto dopo aver risolto il token di autorizzazione del marketplace commerciale usando l'API Resolve.

Intestazioni della richiesta:

Parametro	Valore
`content-type`	`application/json`
`x-ms-requestid`	Valore stringa univoco per tenere traccia della richiesta dal client, preferibilmente un GUID. Se questo valore non viene specificato, ne viene generato uno e fornito nelle intestazioni della risposta.
`x-ms-correlationid`	Valore stringa univoco per l'operazione sul client. Questa stringa correla tutti gli eventi dell'operazione client con gli eventi sul lato server. Se questo valore non viene specificato, ne viene generato uno e fornito nelle intestazioni della risposta.
`authorization`	Token di accesso univoco che identifica l'autore che effettua questa chiamata API. Il formato è `"Bearer <access_token>"` quando il valore del token viene recuperato dall'editore, come illustrato in Ottenere un token basato sull'app Microsoft Entra.

Codici di risposta:

Codice: 200 Richiesta di aggiornamento della sottoscrizione e contrassegno come "Sottoscritto". I fornitori di software indipendenti (ISV) possono verificare lo stato della sottoscrizione dopo alcuni minuti (leggere per verificare lo stato della sottoscrizione). In questo modo si ottiene la risposta definitiva se la sottoscrizione è stata aggiornata correttamente. Se non si esegue la sottoscrizione, viene inviato automaticamente un webhook "Annulla sottoscrizione".

Non esiste alcun corpo della risposta per questa chiamata.

Codice: 400 Richiesta non valida: convalida non riuscita.

La sottoscrizione SaaS è in stato Sospeso .

Questo errore è spesso un sintomo di non eseguire correttamente la registrazione SaaS.

Codice: 404 Non trovato. La sottoscrizione SaaS è in stato Annulla sottoscrizione .

Codice: errore interno del server 500. Ripetere la chiamata API. Se l'errore persiste, contattare il supporto tecnico Microsoft.

Ottenere l'elenco di tutte le sottoscrizioni

Questa API recupera un elenco di tutte le sottoscrizioni SaaS acquistate per tutte le offerte pubblicate dall'editore nel marketplace commerciale. Vengono restituite sottoscrizioni SaaS in tutti gli stati possibili. Le sottoscrizioni SaaS annullate vengono restituite anche perché queste informazioni non vengono eliminate sul lato Microsoft.

L'API restituisce i risultati impaginati di 100 per pagina.

Ottieni `https://marketplaceapi.microsoft.com/api/saas/subscriptions?api-version=<ApiVersion>`

Parametri di query:

Parametro	Valore
`ApiVersion`	Usare 2018-08-31.
`continuationToken`	Parametro facoltativo. Per recuperare la prima pagina dei risultati, lasciare vuoto. Usare il valore restituito nel `@nextLink` parametro per recuperare la pagina successiva.

Intestazioni della richiesta:

Parametro	Valore
`content-type`	`application/json`
`x-ms-requestid`	Valore stringa univoco per tenere traccia della richiesta dal client, preferibilmente un GUID. Se questo valore non viene specificato, ne viene generato uno e fornito nelle intestazioni della risposta.
`x-ms-correlationid`	Valore stringa univoco per l'operazione sul client. Questo parametro mette in correlazione tutti gli eventi dell'operazione del client con gli eventi sul lato server. Se questo valore non viene specificato, ne viene generato uno e fornito nelle intestazioni della risposta.
`authorization`	Token di accesso univoco che identifica l'autore che effettua questa chiamata API. Il formato è `"Bearer <access_token>"` quando il valore del token viene recuperato dall'editore, come illustrato in Ottenere un token basato sull'app Microsoft Entra.

Codici di risposta:

Codice: 200 Restituisce l'elenco di tutte le sottoscrizioni esistenti per tutte le offerte effettuate dal server di pubblicazione, in base al token di autorizzazione dell'editore.

Esempio di corpo della risposta:

{
  "subscriptions": [
    {
      "id": "<guid>", // purchased SaaS subscription ID
      "name": "Contoso Cloud Solution", // SaaS subscription name
      "publisherId": "contoso", // publisher ID
      "offerId": "offer1", // purchased offer ID
      "planId": "silver", // purchased plan ID
      "quantity": 10, // purchased amount of seats, is empty if plan is not per seat
      "beneficiary": { // email address, user ID and tenant ID for which SaaS subscription was purchased.
        "emailId": " test@contoso.com",
        "objectId": "<guid>",
        "tenantId": "<guid>",
        "puid": "<ID of the user>"
      },
      "purchaser": { // email address, user ID and tenant ID that purchased the SaaS subscription. These could be different from beneficiary information for reseller (CSP) purchase
        "emailId": " test@contoso.com",
        "objectId": "<guid>",
        "tenantId": "<guid>",
        "puid": "<ID of the user>"
      },
      "term": { // The period for which the subscription was purchased.
        "startDate": "2022-03-04T00:00:00Z", //format: YYYY-MM-DD. This is the date when the subscription was activated by the ISV and the billing started. This field is only available after the saas subscription is active.
        "endDate": "2022-04-03T00:00:00Z", // This is the last day the subscription is valid. Unless stated otherwise, the automatic renew happens the next day. This field is only available after the saas subscription is active.
        "termUnit": "P1M" // where P1M is monthly and P1Y is yearly. Also reflected in the startDate and endDate values
      },
      "autoRenew": true,
      "allowedCustomerOperations": ["Read", "Update", "Delete"], // Indicates operations allowed on the SaaS subscription for beneficiary. For CSP-initiated purchases, this is always "Read" because the customer cannot update or delete subscription in this flow. Purchaser can perform all operations on the subscription.
      "sessionMode": "None", // not relevant
      "isFreeTrial": true, // true - the customer subscription is currently in free trial, false - the customer subscription is not currently in free trial. (Optional field -– if not returned, the value is false.)
      "isTest": false, // not relevant
      "sandboxType": "None", // not relevant
      "saasSubscriptionStatus": "Subscribed" // Indicates the status of the operation. Can be one of the following: PendingFulfillmentStart, Subscribed, Suspended or Unsubscribed.
    },
    // next SaaS subscription details, might be a different offer
    {
      "id": "<guid1>",
      "name": "Contoso Cloud Solution1",
      "publisherId": "contoso",
      "offerId": "offer2",
      "planId": "gold",
      "quantity": "",
      "beneficiary": {
        "emailId": " test@contoso.com",
        "objectId": "<guid>",
        "tenantId": "<guid>",
        "puid": "<ID of the user>"
      },
      "purchaser": {
        "emailId": "purchase@csp.com ",
        "objectId": "<guid>",
        "tenantId": "<guid>",
        "puid": "<ID of the user>"
      },
      "term": {
        "startDate": "2019-05-31", /This field is only available after the saas subscription is active.
        "endDate": "2020-04-30",  //This field is only available after the saas subscription is active.
        "termUnit": "P1Y"
      },
      "autoRenew": false,
      "allowedCustomerOperations": ["Read"],
      "sessionMode": "None",
      "isFreeTrial": false,
      "isTest": false,
      "sandboxType": "None",
      "saasSubscriptionStatus": "Suspended"
    }
  ],
  "@nextLink": "https:// https://marketplaceapi.microsoft.com/api/saas/subscriptions/?continuationToken=%5b%7b%22token%22%3a%22%2bRID%3a%7eYeUDAIahsn22AAAAAAAAAA%3d%3d%23RT%3a1%23TRC%3a2%23ISV%3a1%23FPC%3aAgEAAAAQALEAwP8zQP9%2fFwD%2b%2f2FC%2fwc%3d%22%2c%22range%22%3a%7b%22min%22%3a%22%22%2c%22max%22%3a%2205C1C9CD673398%22%7d%7d%5d&api-version=2018-08-31" // url that contains continuation token to retrieve next page of the SaaS subscriptions list, if empty or absent, this is the last page. ISV can use this url as is to retrieve the next page or extract the value of continuation token from this url.
}

Se non vengono trovate sottoscrizioni SaaS acquistate per questo editore, viene restituito il corpo della risposta vuoto.

Codice: 403 Accesso negato. Il token di autorizzazione non è disponibile, non è valido o è scaduto.

Questo errore è spesso un sintomo di non eseguire correttamente la registrazione SaaS.

Codice: errore interno del server 500. Ripetere la chiamata API. Se l'errore persiste, contattare il supporto tecnico Microsoft.

Ottieni una sottoscrizione

Questa API recupera una sottoscrizione SaaS acquistata specificata per un'offerta SaaS pubblicata dall'editore nel marketplace commerciale. Usare questa chiamata per ottenere tutte le informazioni disponibili per una sottoscrizione SaaS specifica in base al relativo ID anziché chiamando l'API usata per ottenere un elenco di tutte le sottoscrizioni.

Ottieni `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<ApiVersion>`

Parametri di query:

Parametro	Valore
`ApiVersion`	Usare 2018-08-31.
`subscriptionId`	Identificatore univoco della sottoscrizione SaaS acquistata. Questo ID viene ottenuto dopo aver risolto il token di autorizzazione del marketplace commerciale usando l'API Resolve.

Intestazioni della richiesta:

Parametro	Valore
`content-type`	`application/json`
`x-ms-requestid`	Valore stringa univoco per tenere traccia della richiesta dal client, preferibilmente un GUID. Se questo valore non viene specificato, ne viene generato uno e fornito nelle intestazioni della risposta.
`x-ms-correlationid`	Valore stringa univoco per l'operazione sul client. Questo parametro mette in correlazione tutti gli eventi dell'operazione del client con gli eventi sul lato server. Se questo valore non viene specificato, ne viene generato uno e fornito nelle intestazioni della risposta.
`authorization`	Token di accesso univoco che identifica l'autore che effettua questa chiamata API. Il formato è `"Bearer <access_token>"` quando il valore del token viene recuperato dall'editore, come illustrato in Ottenere un token basato sull'app Microsoft Entra.

Codici di risposta:

Codice: 200 Restituisce i dettagli per una sottoscrizione SaaS in base all'oggetto subscriptionId fornito.

Esempio di corpo della risposta:

{
  "id": "<guid>", // purchased SaaS subscription ID
  "name": "Contoso Cloud Solution", // SaaS subscription name
  "publisherId": "contoso", // publisher ID
  "offerId": "offer1", // purchased offer ID
  "planId": "silver", // purchased plan ID
  "quantity": 10, // purchased amount of seats is empty if plan is not per seat
  "beneficiary": { // email address, user ID and tenant ID for which SaaS subscription is purchased.
    "emailId": "test@contoso.com",
    "objectId": "<guid>",
    "tenantId": "<guid>",
    "puid": "<ID of the user>"
  },
  "purchaser": { // email address ,user ID and tenant ID that purchased the SaaS subscription. These could be different from beneficiary information for reseller (CSP) scenario
    "emailId": "test@test.com",
    "objectId": "<guid>",
    "tenantId": "<guid>",
    "puid": "<ID of the user>"
  },
  "allowedCustomerOperations": ["Read", "Update", "Delete"], // Indicates operations allowed on the SaaS subscription for beneficiary. For CSP-initiated purchases, this is always "Read" because the customer cannot update or delete subscription in this flow. Purchaser can perform all operations on the subscription.
  "sessionMode": "None", // not relevant
  "isFreeTrial": false, // true - the customer subscription is currently in free trial, false - the customer subscription is not currently in free trial. Optional field – if not returned the value is false.
  "autoRenew": true,
  "isTest": false, // not relevant
  "sandboxType": "None", // not relevant
  "created": "2022-03-01T22:59:45.5468572Z",
     "lastModified": "0001-01-01T00:00:00", //[Deprecated] Do not use.
  "saasSubscriptionStatus": " Subscribed ", // Indicates the status of the operation: PendingFulfillmentStart, Subscribed, Suspended or Unsubscribed.
  "term": { // the period for which the subscription was purchased
    "startDate": "2022-03-04T00:00:00Z", //format: YYYY-MM-DD. This is the date when the subscription was activated by the ISV and the billing started. This field is only available after the saas subscription is active.
    "endDate": "2022-04-03T00:00:00Z", // This is the last day the subscription is valid. Unless stated otherwise, the automatic renew happens the next day. This field is only available after the saas subscription is active.
    "termUnit": "P1M" //where P1M is monthly and P1Y is yearly. Also reflected in the startDate and endDate values.
  }
}

Questo errore è spesso un sintomo di non eseguire correttamente la registrazione SaaS.

Codice: 404 Non trovato. Impossibile trovare la sottoscrizione SaaS con l'oggetto specificato subscriptionId .

Codice: errore interno del server 500. Ripetere la chiamata API. Se l'errore persiste, contattare il supporto tecnico Microsoft.

Elencare i piani disponibili

Questa API recupera tutti i piani per un'offerta SaaS identificata da subscriptionId di un acquisto specifico di questa offerta. Usare questa chiamata per ottenere un elenco di tutti i piani privati e pubblici che il beneficiario di una sottoscrizione SaaS può aggiornare per la sottoscrizione. I piani restituiti sono disponibili nella stessa area geografica del piano già acquistato.

Questa chiamata restituisce un elenco di piani disponibili per il cliente oltre a quello già acquistato. L'elenco può essere presentato a un utente finale nel sito di pubblicazione. Un utente finale può modificare il piano di sottoscrizione in uno qualsiasi dei piani nell'elenco restituito. La modifica del piano a un piano non incluso nell'elenco non funziona.

Questa API recupera anche l'ID dell'offerta privata attiva associato (se si chiama l'API con il filtro planId). La chiamata all'API con il filtro planId mostra i GUID DELL'ID offerta privata attivi nel corpo della risposta nel nodo sourceOffers. Il planId passato nel parametro di filtro deve corrispondere al planId acquistato dal cliente.

Ottieni `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/listAvailablePlans?api-version=<ApiVersion>&planId=<planId>`

Parametri di query:

Parametro	Valore
`ApiVersion`	Usare 2018-08-31.
`subscriptionId`	Identificatore univoco della sottoscrizione SaaS acquistata. Questo ID viene ottenuto dopo aver risolto il token di autorizzazione del marketplace commerciale usando l'API Resolve.
`planId (Optional)`	ID piano di un piano specifico da recuperare. Questa opzione è facoltativa e, se ignorata, restituisce tutti i piani.

Intestazioni della richiesta:

Parametro	Valore
`content-type`	`application/json`
`x-ms-requestid`	Valore stringa univoco per tenere traccia della richiesta dal client, preferibilmente un GUID. Se questo valore non viene specificato, ne viene generato uno e fornito nelle intestazioni della risposta.
`x-ms-correlationid`	Valore stringa univoco per l'operazione sul client. Questo parametro mette in correlazione tutti gli eventi dell'operazione del client con gli eventi sul lato server. Se questo valore non viene specificato, ne viene generato uno e fornito nelle intestazioni della risposta.
`authorization`	Token di accesso univoco che identifica l'autore che effettua questa chiamata API. Il formato è `"Bearer <access_token>"` quando il valore del token viene recuperato dall'editore, come illustrato in Ottenere un token basato sull'app Microsoft Entra.

Codici di risposta:

Codice: 200 Restituisce un elenco di tutti i piani disponibili per una sottoscrizione SaaS esistente, inclusa quella già acquistata.

Il passaggio di planId non validi (facoltativo) restituisce un elenco vuoto di piani.

Esempio di corpo della risposta:

{
  "plans": [
    {
      "planId": "Platinum001",
      "displayName": "plan display name",
      "isPrivate": true, //returns true for private plans and customized plans created within a private offer.
      "description": "plan description",
      "minQuantity": 5,
      "maxQuantity": 100,
      "hasFreeTrials": false,
      "isPricePerSeat": true,
      "isStopSell": false,
      "market": "US",
      "planComponents": {
        "recurrentBillingTerms": [
          {
            "currency": "USD",
            "price": 1,
            "termUnit": "P1M",
            "termDescription": "term description",
            "meteredQuantityIncluded": [
              {
                "dimensionId": "Dimension001",
                "units": "Unit001"
              }
            ]
          }
        ],
        "meteringDimensions": [
          {
            "id": "MeteringDimension001",
            "currency": "USD",
            "pricePerUnit": 1,
            "unitOfMeasure": "unitOfMeasure001",
            "displayName": "unit of measure display name"
          }
        ]
      },
      "sourceOffers": [ //sourceOffers is returned when planId is passed as filter parameter (note that this is the plan that customer has purchased).
        {
          "externalId": "<guid>" //private offer id, returned when purchase is made through private offer.
        }
      ]
    }
  ]
}

Codice: 404 Non trovato. subscriptionId non trovata.

Codice: 403 Accesso negato. Il token di autorizzazione non è valido, è scaduto o non è stato specificato. La richiesta potrebbe tentare di accedere a una sottoscrizione SaaS per un'offerta annullata o pubblicata con un ID app Microsoft Entra diverso da quello usato per creare il token di autorizzazione.

Questo errore è spesso un sintomo di non eseguire correttamente la registrazione SaaS.

Codice: errore interno del server 500. Ripetere la chiamata API. Se l'errore persiste, contattare il supporto tecnico Microsoft.

Modificare il piano nella sottoscrizione

Usare questa API per aggiornare il piano esistente acquistato per una sottoscrizione SaaS a un nuovo piano (pubblico o privato). L'editore deve chiamare questa API quando un piano viene modificato sul lato editore per una sottoscrizione SaaS acquistata nel marketplace commerciale.

Questa API può essere chiamata solo per le sottoscrizioni attive . Qualsiasi piano può essere modificato in qualsiasi altro piano esistente (pubblico o privato) ma non in se stesso. Per i piani privati, il tenant del cliente deve essere definito come parte del gruppo di destinatari del piano nel Centro per i partner.

Benda `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<ApiVersion>`

Parametri di query:

Parametro	Valore
`ApiVersion`	Usare 2018-08-31.
`subscriptionId`	Identificatore univoco della sottoscrizione SaaS acquistata. Questo ID viene ottenuto dopo aver risolto il token di autorizzazione del marketplace commerciale usando l'API Resolve.

Intestazioni della richiesta:

Parametro	Valore
`content-type`	`application/json`
`x-ms-requestid`	Valore stringa univoco per tenere traccia della richiesta dal client, preferibilmente un GUID. Se questo valore non viene specificato, ne viene generato uno e fornito nelle intestazioni della risposta.
`x-ms-correlationid`	Valore stringa univoco per l'operazione sul client. Questo parametro mette in correlazione tutti gli eventi dell'operazione del client con gli eventi sul lato server. Se questo valore non viene specificato, ne viene generato uno e fornito nelle intestazioni della risposta.
`authorization`	Token di accesso univoco che identifica l'autore che effettua questa chiamata API. Il formato è `"Bearer <access_token>"` quando il valore del token viene recuperato dall'editore, come illustrato in Ottenere un token basato sull'app Microsoft Entra.

Esempio di payload della richiesta:

{
  "planId": "gold" // the ID of the new plan to be purchased
}

Codici di risposta:

Codice: 202 La richiesta di modifica del piano è stata accettata e gestita in modo asincrono. È previsto che il partner esegua il polling dell'URL percorso operazione per determinare l'esito positivo o negativo della richiesta del piano di modifica. Il polling deve essere eseguito ogni alcuni secondi fino a quando non viene ricevuto lo stato finale non riuscito, riuscito o conflitto per l'operazione. Lo stato dell'operazione finale deve essere restituito rapidamente, ma può richiedere alcuni minuti in alcuni casi.

Il partner riceve anche una notifica webhook quando l'azione è pronta per essere completata correttamente sul lato marketplace commerciale. Solo allora l'editore deve apportare la modifica del piano sul lato editore.

Intestazioni di risposta:

Parametro	Valore
`Operation-Location`	URL per ottenere lo stato dell'operazione. Ad esempio, `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/operations/<operationId>?api-version=2018-08-31`

Codice: 400 Richiesta non valida: errori di convalida.

Il nuovo piano non esiste o non è disponibile per questa sottoscrizione SaaS specifica.
Il nuovo piano è uguale al piano corrente.
Lo stato della sottoscrizione SaaS non è sottoscritto.
L'operazione di aggiornamento per una sottoscrizione SaaS non è inclusa in allowedCustomerOperations.

Questo errore è spesso un sintomo di non eseguire correttamente la registrazione SaaS.

Codice: 404 Non trovato. La sottoscrizione SaaS con subscriptionId non viene trovata.

Codice: errore interno del server 500. Ripetere la chiamata API. Se l'errore persiste, contattare il supporto tecnico Microsoft.

Nota

Il piano o la quantità di posti possono essere modificati contemporaneamente, non entrambi.

Questa API può essere chiamata solo dopo aver ottenuto l'approvazione esplicita per la modifica dall'utente finale.

Modificare la quantità di postazioni nella sottoscrizione SaaS

Usare questa API per aggiornare (aumentare o diminuire) la quantità di postazioni acquistate per una sottoscrizione SaaS. L'editore deve chiamare questa API quando il numero di postazioni viene modificato dal lato editore per una sottoscrizione SaaS creata nel marketplace commerciale.

La quantità di postazioni non può essere maggiore della quantità consentita nel piano corrente. In questo caso, l'editore deve modificare il piano prima di modificare la quantità di postazioni.

Benda `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<ApiVersion>`

Parametri di query:

Parametro	Valore
`ApiVersion`	Usare 2018-08-31.
`subscriptionId`	Identificatore univoco della sottoscrizione SaaS acquistata. Questo ID viene ottenuto dopo aver risolto il token di autorizzazione del marketplace commerciale usando l'API Resolve.

Intestazioni della richiesta:

Parametro	Valore
`content-type`	`application/json`
`x-ms-requestid`	Valore stringa univoco per tenere traccia della richiesta dal client, preferibilmente un GUID. Se questo valore non viene specificato, ne viene generato uno e fornito nelle intestazioni della risposta.
`x-ms-correlationid`	Valore stringa univoco per l'operazione sul client. Questo parametro mette in correlazione tutti gli eventi dell'operazione del client con gli eventi sul lato server. Se questo valore non viene specificato, ne viene generato uno e fornito nelle intestazioni della risposta.
`authorization`	Token di accesso univoco che identifica l'autore che effettua questa chiamata API. Il formato è `"Bearer <access_token>"` quando il valore del token viene recuperato dall'editore, come illustrato in Ottenere un token basato sull'app Microsoft Entra.

Esempio di payload della richiesta:

{
  "quantity": 5 // the new amount of seats to be purchased
}

Codici di risposta:

Codice: 202 La richiesta di modifica della quantità è stata accettata e gestita in modo asincrono. Si prevede che il partner esegua il polling dell'URL di Operation-Location per determinare un esito positivo o negativo della richiesta di quantità di modifiche. Il polling deve essere eseguito ogni alcuni secondi fino a quando non viene ricevuto lo stato finale non riuscito, riuscito o conflitto per l'operazione. Lo stato dell'operazione finale deve essere restituito rapidamente, ma può richiedere alcuni minuti in alcuni casi.

Intestazioni di risposta:

Parametro	Valore
`Operation-Location`	Collegarsi a una risorsa per ottenere lo stato dell'operazione. Ad esempio: `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/operations/<operationId>?api-version=2018-08-31`.

Codice: 400 Richiesta non valida: errori di convalida.

La nuova quantità è maggiore o inferiore al limite di piano corrente.
La nuova quantità è mancante.
La nuova quantità corrisponde alla quantità corrente.
Lo stato della sottoscrizione SaaS non è sottoscritto.
L'operazione di aggiornamento per una sottoscrizione SaaS non è inclusa in allowedCustomerOperations.

Codice: 403 Accesso negato. Il token di autorizzazione non è valido, è scaduto o non è stato specificato. La richiesta sta tentando di accedere a una sottoscrizione che non appartiene al server di pubblicazione corrente.

Questo errore è spesso un sintomo di non eseguire correttamente la registrazione SaaS.

Codice: 404 Non trovato. La sottoscrizione SaaS con subscriptionId non viene trovata.

Codice: errore interno del server 500. Ripetere la chiamata API. Se l'errore persiste, contattare il supporto tecnico Microsoft.

Nota

Solo un piano o una quantità possono essere modificati contemporaneamente, non entrambi.

Questa API può essere chiamata solo dopo aver ottenuto l'approvazione esplicita dall'utente finale per la modifica.

Annullare una sottoscrizione

Usare questa API per annullare la sottoscrizione SaaS specificata. L'editore non deve usare questa API e si consiglia ai clienti di essere indirizzati al marketplace commerciale per annullare le sottoscrizioni SaaS.

Se l'editore decide di implementare l'annullamento di una sottoscrizione SaaS acquistata nel marketplace commerciale sul lato dell'editore, deve chiamare questa API. Dopo il completamento di questa chiamata, lo stato della sottoscrizione diventa Annulla sottoscrizione sul lato Microsoft.

Il cliente non viene fatturato se una sottoscrizione viene annullata entro 72 ore dall'acquisto.

Il cliente viene fatturato se una sottoscrizione viene annullata dopo il periodo di tolleranza precedente. Il cliente perde l'accesso alla sottoscrizione SaaS sul lato Microsoft immediatamente dopo l'annullamento.

Elimina `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<ApiVersion>`

Parametri di query:

Parametro	Valore
`ApiVersion`	Usare 2018-08-31.
`subscriptionId`	Identificatore univoco della sottoscrizione SaaS acquistata. Questo ID viene ottenuto dopo aver risolto il token di autorizzazione del marketplace commerciale usando l'API Resolve.

Intestazioni della richiesta:

Parametro	Valore
`content-type`	`application/json`
`x-ms-requestid`	Valore stringa univoco per tenere traccia della richiesta dal client, preferibilmente un GUID. Se questo valore non viene specificato, ne viene generato uno e fornito nelle intestazioni della risposta.
`x-ms-correlationid`	Valore stringa univoco per l'operazione sul client. Questo parametro mette in correlazione tutti gli eventi dell'operazione del client con gli eventi sul lato server. Se questo valore non viene specificato, ne viene generato uno e fornito nelle intestazioni della risposta.
`authorization`	Token di accesso univoco che identifica l'autore che effettua questa chiamata API. Il formato è `"Bearer <access_token>"` quando il valore del token viene recuperato dall'editore, come illustrato in Ottenere un token basato sull'app Microsoft Entra.

Codici di risposta:

Codice: 202 La richiesta di annullamento della sottoscrizione è stata accettata e gestita in modo asincrono. È previsto che il partner esegua il polling dell'URL di Operation-Location per determinare l'esito positivo o negativo di questa richiesta. Il polling deve essere eseguito ogni alcuni secondi fino a quando non viene ricevuto lo stato finale non riuscito, riuscito o conflitto per l'operazione. Lo stato dell'operazione finale deve essere restituito rapidamente, ma può richiedere alcuni minuti in alcuni casi.

Il partner riceve anche una notifica webhook quando l'azione viene completata correttamente sul lato marketplace commerciale. Solo il server di pubblicazione deve annullare la sottoscrizione sul lato server di pubblicazione.

Codice: 200 La sottoscrizione è già in stato Annulla sottoscrizione.

Intestazioni di risposta:

Parametro	Valore
`Operation-Location`	Collegarsi a una risorsa per ottenere lo stato dell'operazione. Ad esempio: `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/operations/<operationId>?api-version=2018-08-31`.

Codice: 400 Richiesta non valida. L'eliminazione non è presente nell'elenco allowedCustomerOperations per questa sottoscrizione SaaS.

Codice: 403 Accesso negato. Il token di autorizzazione non è valido, è scaduto o non è disponibile.

Questo errore è spesso un sintomo di non eseguire correttamente la registrazione SaaS.

Codice: 404 Non trovato. La sottoscrizione SaaS con subscriptionId non viene trovata.

Codice: 409

Impossibile completare l'eliminazione perché la sottoscrizione è bloccata a causa di operazioni in sospeso.

Codice: errore interno del server 500. Ripetere la chiamata API. Se l'errore persiste, contattare il supporto tecnico Microsoft.

Passaggi successivi

Per altre opzioni per le offerte SaaS nel marketplace commerciale, vedere le API del servizio di misurazione del marketplace commerciale
Esaminare e usare i client per linguaggi di programmazione e esempi diversi
Per indicazioni sui test, vedere Implementazione di un webhook nel servizio SaaS

API di sottoscrizione per l'evasione SaaS v2 nel marketplace commerciale Microsoft

Risolvere una sottoscrizione acquistata

Inserisci `https://marketplaceapi.microsoft.com/api/saas/subscriptions/resolve?api-version=<ApiVersion>`

Attivare una sottoscrizione

Inserisci `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/activate?api-version=<ApiVersion>`

Ottenere l'elenco di tutte le sottoscrizioni

Ottieni `https://marketplaceapi.microsoft.com/api/saas/subscriptions?api-version=<ApiVersion>`

Ottieni una sottoscrizione

Ottieni `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<ApiVersion>`

Elencare i piani disponibili

Ottieni `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/listAvailablePlans?api-version=<ApiVersion>&planId=<planId>`

Modificare il piano nella sottoscrizione

Benda `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<ApiVersion>`

Modificare la quantità di postazioni nella sottoscrizione SaaS

Benda `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<ApiVersion>`

Annullare una sottoscrizione

Elimina `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<ApiVersion>`

Passaggi successivi

Commenti e suggerimenti

Commenti e suggerimenti

Risorse aggiuntive

API di sottoscrizione per l'evasione SaaS v2 nel marketplace commerciale Microsoft

Risolvere una sottoscrizione acquistata

Inserisci https://marketplaceapi.microsoft.com/api/saas/subscriptions/resolve?api-version=<ApiVersion>

Attivare una sottoscrizione

Inserisci https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/activate?api-version=<ApiVersion>

Ottenere l'elenco di tutte le sottoscrizioni

Ottieni https://marketplaceapi.microsoft.com/api/saas/subscriptions?api-version=<ApiVersion>

Ottieni una sottoscrizione

Ottieni https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<ApiVersion>

Elencare i piani disponibili

Ottieni https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/listAvailablePlans?api-version=<ApiVersion>&planId=<planId>

Modificare il piano nella sottoscrizione

Benda https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<ApiVersion>

Modificare la quantità di postazioni nella sottoscrizione SaaS

Benda https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<ApiVersion>

Annullare una sottoscrizione

Elimina https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<ApiVersion>

Passaggi successivi

Commenti e suggerimenti

Commenti e suggerimenti

Risorse aggiuntive

Inserisci `https://marketplaceapi.microsoft.com/api/saas/subscriptions/resolve?api-version=<ApiVersion>`

Inserisci `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/activate?api-version=<ApiVersion>`

Ottieni `https://marketplaceapi.microsoft.com/api/saas/subscriptions?api-version=<ApiVersion>`

Ottieni `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<ApiVersion>`

Ottieni `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/listAvailablePlans?api-version=<ApiVersion>&planId=<planId>`

Benda `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<ApiVersion>`

Benda `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<ApiVersion>`

Elimina `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<ApiVersion>`