Concedi prodotti gratuiti

Articolo
03/22/2024

Usare questo metodo nell'API di acquisto di Microsoft Store per concedere un'app o un componente aggiuntivo gratuito (anche denominato prodotto in-app o IAP) a un determinato utente.

Attualmente, è possibile concedere solo prodotti gratuiti. Se il servizio tenta di usare questo metodo per concedere un prodotto non gratuito, questo metodo restituirà un errore.

Prerequisiti

Per utilizzare questo metodo, avrai bisogno di:

Un token di accesso di Azure AD con il valore URI del gruppo di destinatari https://onestore.microsoft.com.
Chiave ID di Microsoft Store che rappresenta l'identità dell'utente a cui si desidera concedere un prodotto gratuito.

Per ulteriori informazioni, vedere Gestire i diritti dei prodotti di un servizio.

Richiedi

Sintassi della richiesta

metodo	URI della richiesta
POST	`https://purchase.mp.microsoft.com/v6.0/purchases/grant`

Intestazione della richiesta

Intestazione	Type	Descrizione
Autorizzazione	stringa	Obbligatorio. Token di accesso di Azure AD nel formato Token di<connessione>.
Host	string	Deve essere impostato sul valore purchase.mp.microsoft.com.
Content-Length	number	Lunghezza del corpo della richiesta.
Content-Type	string	Specifica il tipo di richiesta e risposta. Attualmente, l'unico valore supportato è application/json.

Testo della richiesta

Parametro	Tipo	Descrizione	Richiesto
availabilityId	string	ID di disponibilità del prodotto da concedere dal catalogo di Microsoft Store.	Sì
b2bKey	string	Chiave ID di Microsoft Store che rappresenta l'identità dell'utente a cui si desidera concedere un prodotto.	Sì
devOfferId	string	ID dell'offerta specificato dallo sviluppatore che verrà visualizzato nell'elemento Collection dopo l'acquisto.
lingua	string	Lingua dell'utente.	Sì
market	string	Mercato dell'utente.	Sì
orderId	guid	GUID generato per l'ordine. Questo valore è univoco per l'utente, ma non è necessario che sia univoco in tutti gli ordini.	Sì
productId	string	LoStore ID per il prodotto nel catalogo del Microsoft Store. Un esempio di ID negozio per un prodotto è 9NBLGGH42CFD..	Sì
quantity	int	Quantità da acquistare. Attualmente l'unico valore supportato è 1 Se non specificato, il valore predefinito è 1.	No
skuId	string	Lo Store ID per il prodottoSKU nel catalogo del Microsoft Store. Un esempio di ID negozio per uno SKU è 0010.	Sì

Esempio di richiesta

POST https://purchase.mp.microsoft.com/v6.0/purchases/grant HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJK……
Content-Length: 1863
Content-Type: application/json

{
    "b2bKey" : "eyJ0eXAiOiJK……",
    "availabilityId" : "9RT7C09D5J3W",
    "productId" : "9NBLGGH5WVP6",
    "skuId" : "0010",
    "language" : "en-us",
    "market" : "us",
    "orderId" : "3eea1529-611e-4aee-915c-345494e4ee76",
}

Response

Corpo della risposta

Parametro	Tipo	Descrizione	Richiesto
clientContext	ClientContextV6	Informazioni contestuali del client per questo ordine. Questo valore verrà assegnato al valore clientID del token di Azure AD.	Sì
createdtime	datetimeoffset	L'ora in cui è stato creato l'ordine.	Sì
currencyCode	string	Codice della valuta per totalAmount e totalTaxAmount. N/D per gli elementi gratuiti.	Sì
friendlyName	string	Nome descrittivo dell'ordine. N/D per gli ordini effettuati usando l'API di acquisto di Microsoft Store.	Sì
isPIRequired	boolean	Indica se è necessario uno strumento di pagamento (PI) come parte dell'ordine di acquisto.	Sì
lingua	string	ID della lingua per l'ordine (ad esempio, "en").	Sì
market	string	ID del mercato per l'ordine (ad esempio, "US").	Sì
orderId	string	ID che identifica l'ordine di un determinato utente.	Sì
orderLineItems	list<OrderLineItemV6>	Elenco di voci per l'ordine. In genere è presente 1 voce per ordine.	Sì
orderState	string	Stato dell'ordine. Gli stati validi sono Editing, CheckingOut, Pending, Purchased, Refunded, ChargedBack e Cancelled.	Sì
orderValidityEndTime	string	Fine del periodo di validità del prezzo dell'ordine prima dell'invio. N/D per le app gratuite.	Sì
orderValidityStartTime	string	Inizio del periodo di validità del prezzo dell'ordine prima dell'invio. N/D per le app gratuite.	Sì
purchaser	IdentityV6	Oggetto che descrive l'identità dell'acquirente.	Sì
totalAmount	decimale	Importo totale di acquisto di tutti gli articoli nell'ordine, imposta inclusa.	Sì
totalAmountBeforeTax	decimale	Importo totale di acquisto di tutti gli articoli nell'ordine al netto dell'imposta.	Sì
totalChargedToCsvTopOffPI	decimale	Se si usa uno strumento di pagamento separato e un valore archiviato (CSV), l'importo addebitato su CSV.	Sì
totalTaxAmount	decimale	Importo totale delle imposte per tutte le voci.	Sì

L'oggetto ClientContext contiene i parametri seguenti.

Parametro	Tipo	Descrizione	Richiesto
client	string	L'ID client che ha creato l'ordine.	No

L'oggetto OrderLineItemV6 contiene i parametri seguenti.

Parametro	Tipo	Descrizione	Richiesto
agente	IdentityV6	Ultimo agente che ha modificato la voce. Per ulteriori informazioni su questo oggetto, vedere la tabella seguente.	No
availabilityId	string	ID di disponibilità del prodotto da acquistare dal catalogo di Microsoft Store.	Sì
beneficiary	IdentityV6	Identità del beneficiario dell'ordine.	No
billingState	string	Stato di fatturazione dell'ordine. Viene impostato su Charged al completamento.	No
campaignId	string	ID della campagna per questo ordine.	No
currencyCode	string	Codice valuta usato per i dettagli dei prezzi.	Sì
descrizione	stringa	Descrizione localizzata della voce.	Sì
devofferId	string	ID dell'offerta per l'ordine specifico, se presente.	No
fulfillmentDate	datetimeoffset	Data in cui si è verificata l'evasione.	No
fulfillmentState	string	Stato dell'evasione della voce. Viene impostato su Fulfilled al completamento.	No
isPIRequired	boolean	Indica se per questa voce è necessario uno strumento di pagamento.	Sì
isTaxIncluded	boolean	Indica se l'imposta è inclusa nei dettagli dei prezzi dell'articolo.	Sì
legacyBillingOrderId	string	ID di fatturazione legacy.	No
lineItemId	string	ID della voce per l'articolo in questo ordine.	Sì
listPrice	decimale	Prezzo di listino dell'articolo in questo ordine.	Sì
productId	string	ID dello Store per il prodotto che rappresenta la voce nel catalogo di Microsoft Store. Un esempio di ID dello Store per un prodotto è 9NBLGGH42CFD.	Sì
productType	string	Tipo del prodotto. I valori supportati sono Durable, Application e UnmanagedConsumable.	Sì
quantity	int	Quantità dell'articolo ordinato.	Sì
retailPrice	decimale	Prezzo al dettaglio dell'articolo ordinato.	Sì
revenueRecognitionState	string	Stato di riconoscimento dei ricavi.	Sì
skuId	string	ID dello Store per lo SKU della voce nel catalogo di Microsoft Store. Un esempio di ID dello Store per uno SKU è 0010.	Sì
taxAmount	decimale	Importo dell'imposta per la voce.	Sì
taxType	string	Tipo di imposta per le imposte applicabili.	Sì
Title	string	Titolo localizzato della voce.	Sì
totalAmount	decimale	Importo totale di acquisto dell'articolo, imposta inclusa.	Sì

L'oggetto IdentityV6 contiene i parametri seguenti.

Parametro	Tipo	Descrizione	Richiesto
identityType	string	Contiene il valore "pub".	Sì
identityValue	string	Il valore della stringa publisherUserId dalla chiave ID di Microsoft Store specificata.	Sì

Risposta di esempio

Content-Length: 1203
Content-Type: application/json
MS-CorrelationId: fb2e69bc-f26a-4aab-a823-7586c19f5762
MS-RequestId: c1bc832c-f742-47e4-a76c-cf061402f698
MS-CV: XjfuNWLQlEuxj6Mt.8
MS-ServerId: 030032362
Date: Tue, 13 Oct 2015 21:21:51 GMT

{
    "clientContext": {
        "client": "86b78998-d05a-487b-b380-6c738f6553ea"
    },
    "createdTime": "2015-10-13T21:21:51.1863494+00:00",
    "currencyCode": "USD",
    "isPIRequired": false,
    "language": "en-us",
    "market": "us",
    "orderId": "3eea1529-611e-4aee-915c-345494e4ee76",
    "orderLineItems": [{
        "availabilityId": "9RT7C09D5J3W",
        "beneficiary": {
            "identityType": "pub",
            "identityValue": "user1"
        },
        "billingState": "Charged",
        "currencyCode": "USD",
        "description": "Jewels, Jewels, Jewels - Consumable 2",
        "fulfillmentDate": "2015-10-13T21:21:51.639478+00:00",
        "fulfillmentState": "Fulfilled",
        "isPIRequired": false,
        "isTaxIncluded": true,
        "lineItemId": "2814d758-3ee3-46b3-9671-4fb3bdae9ffe",
        "listPrice": 0.0,
        "payments": [],
        "productId": "9NBLGGH5WVP6",
        "productType": "UnmanagedConsumable",
        "quantity": 1,
        "retailPrice": 0.0,
        "revenueRecognitionState": "None",
        "skuId": "0010",
        "taxAmount": 0.0,
        "taxType": "NoApplicableTaxes",
        "title": "Jewels, Jewels, Jewels - Consumable 2",
        "totalAmount": 0.0
    }],
    "orderState": "Purchased",
    "orderValidityEndTime": "2015-10-14T21:21:51.1863494+00:00",
    "orderValidityStartTime": "2015-10-13T21:21:51.1863494+00:00",
    "purchaser": {
        "identityType": "pub",
        "identityValue": "user1"
    },
    "testScenarios": "None",
    "totalAmount": 0.0,
    "totalTaxAmount": 0.0
}

Codici di errore

Codice	Error	Codice di errore interno	Descrizione
401	Non autorizzata	AuthenticationTokenInvalid	Il token di accesso di Azure AD non è valido. In alcuni casi i dettagli del ServiceError conterranno più informazioni, ad esempio quando il token è scaduto o manca l'attestazione appid.
401	Non autorizzata	PartnerAadTicketRequired	Un token di accesso di Azure AD non è stato passato al servizio nell'intestazione dell'autorizzazione.
401	Non autorizzata	InconsistentClientId	L'attestazione clientId nella chiave ID di Microsoft Store nel corpo della richiesta e l'attestazione appid nel token di accesso di Azure AD nell'intestazione dell'autorizzazione non corrispondono.
400	BadRequest	InvalidParameter	I dettagli contengono informazioni relative al corpo della richiesta e ai campi che contengono un valore non valido.

Condividi tramite

Concedi prodotti gratuiti

Prerequisiti

Richiedi

Sintassi della richiesta

Intestazione della richiesta

Testo della richiesta

Esempio di richiesta

Response

Corpo della risposta

Risposta di esempio

Codici di errore

Commenti e suggerimenti

Risorse aggiuntive

Condividi tramite

Concedi prodotti gratuiti

Prerequisiti

Richiedi

Sintassi della richiesta

Intestazione della richiesta

Testo della richiesta

Esempio di richiesta

Response

Corpo della risposta

Risposta di esempio

Codici di errore

Argomenti correlati

Commenti e suggerimenti

Risorse aggiuntive