Concedi prodotti gratuiti

  • Articolo

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.