API di riconciliazione fatturata v2 (GA)

Si applica a: Centro per i partner (non disponibile nel cloud sovrano)

La nuova API asincrona offre un modo più rapido ed efficiente per accedere ai dati di fatturazione e riconciliazione tramite BLOB di Azure. Anziché mantenere aperta una connessione per ore o elaborare batch di 2.000 voci, è ora possibile semplificare il flusso di lavoro.

La nuova API di riconciliazione delle fatture fatturate per il commercio usa tecniche avanzate come la chiave di registrazione e i modelli asincroni di richiesta-risposta . Questa API fornisce un token di firma di accesso condiviso che è possibile usare per accedere a tutti gli attributi o a un subset dei dati di riconciliazione fatturati fatturati.

L'API usa tecniche ottimizzate per migliorare l'efficienza, in modo da ottenere risultati più veloci con meno sforzo. Adottare questa API per semplificare l'accesso ai dati e migliorare l'efficienza complessiva.

Nota

La nuova API non è ospitata nell'host API del Centro per i partner. Al contrario, è possibile trovarla in MS Graph in Usare l'API Microsoft Graph per esportare i dati di fatturazione dei partner - Microsoft Graph v1.0. Per accedere a questa API, fare riferimento ai dettagli seguenti.

Importante

Per consentire all'app di accedere ai dati di fatturazione dei partner, seguire questo collegamento e acquisire familiarità con le nozioni di base sull'autenticazione e sull'autorizzazione per Microsoft Graph.

È possibile assegnare l'autorizzazione "PartnerBilling.Read.All" usando il portale di Azure o l'interfaccia di amministrazione di Entra. Ecco come fare:

• Registrare l'app nella home page di Microsoft Entra nella sezione Registrazioni app.
• Per concedere l'autorizzazione necessaria, passare alla pagina Microsoft Entra App nella sezione Autorizzazioni API. Selezionare "Aggiungi un'autorizzazione" e scegliere l'ambito "PartnerBilling.Read.All".

Completando questi passaggi, assicurarsi che l'app abbia l'accesso necessario ai dati di fatturazione dei partner.

Panoramica delle API

Per aiutarti a recuperare in modo asincrono le voci di riconciliazione delle fatture commerciali fatturate in modo asincrono, offriamo due endpoint API chiave. Ecco una guida semplificata per iniziare:

Endpoint di riconciliazione fatturata

Prima di tutto, usare questa API per recuperare le nuove voci di riconciliazione fatturate per il commercio . Quando si effettua una richiesta, si riceve uno stato HTTP 202 e un'intestazione di posizione con un URL. Eseguire regolarmente il polling di questo URL fino a ottenere lo stato di esito positivo e l'URL del manifesto.

Endpoint dello stato dell'operazione

Continuare quindi a controllare lo stato dell'operazione chiamando questa API a intervalli regolari. Se i dati non sono pronti, la risposta include un'intestazione Retry-After che indica quanto tempo attendere prima di riprovare. Al termine dell'operazione, si riceve una risorsa manifesto con un collegamento alla cartella di archiviazione per scaricare i dati di utilizzo. La risposta segmenta i file per migliorare la velocità effettiva e consentire il parallelismo di I/O.

Seguendo questa procedura, è possibile gestire in modo efficiente il processo di riconciliazione della fattura.

Diagramma sequenza

Ecco un diagramma di sequenza che illustra i passaggi per scaricare nuovi dati di riconciliazione delle fatture commerciali.

Sequenza di azioni utente

Per recuperare i dati di riconciliazione fatturati, seguire questa procedura:

Passaggio 1: Inviare una richiesta

Inviare una richiesta POST all'endpoint API.

Ottenere le voci di riconciliazione fatturate

Richiesta API

POST https://graph.microsoft.com/v1.0/reports/partners/billing/reconciliation/billed/export

Accept: application/json

Content-Type: application/json

{

"invoiceId": "G016907411",

"attributeSet": "basic"

}

Parametri di query

N/D

Testo della richiesta

Attributo	Richiesto	Type	Descrizione
attributeSet	Falso	String	Scegliere "full" per tutti gli attributi o "basic" per un set limitato. Se non specificato, "full" è il valore predefinito. Controllare l'elenco degli attributi in questa sezione. Facoltativo.
invoiceId	Vero	String	Identificatore univoco per ogni fattura. Obbligatorio.

Intestazioni delle richieste

Intestazioni di richiesta per l'API usando i passaggi elencati in Procedure consigliate per l'uso di Microsoft Graph. Seguendo queste linee guida, si garantisce affidabilità e supporto per l'applicazione. L'attenzione ai dettagli in questo passaggio è fondamentale per un'integrazione senza interruzioni e prestazioni ottimali.

Risposta dell'API

HTTP/1.1 202 Accepted  
Location: <https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14>

L'API risponde in genere con uno stato HTTP 202. È anche possibile riscontrare altri stati a seconda delle richieste. Questi stati sono elencati nella sezione Stati di risposta API Standard.

Codice	Descrizione
202 – Accettato	La richiesta è stata accettata. Per controllare lo stato della richiesta, eseguire una query sull'URL fornito nell'intestazione del percorso.

Passaggio 2: Controllare lo stato della richiesta

Per tenere traccia dello stato di una richiesta, assicurarsi di ricevere una risposta HTTP 200 che indica "succeeded" o "failed". In caso di esito positivo, l'URL del manifesto viene trovato nell'attributo "resourceLocation". Questo attributo fornisce un endpoint per l'accesso alle informazioni necessarie.

Ottenere lo stato dell'operazione

Recupera lo stato di una richiesta.

Richiesta API

GET <https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14>

Parametri della richiesta

Nome	Includi in	Richiesto	Type	Descrizione
operationId	URI delle richiesta	Vero	String	ID univoco per controllare lo stato della richiesta. Obbligatorio.

Intestazione della richiesta

Intestazioni di richiesta per l'API usando i passaggi elencati in Procedure consigliate per l'uso di Microsoft Graph. Seguendo queste linee guida, si garantisce affidabilità e supporto per l'applicazione. L'attenzione ai dettagli in questo passaggio è fondamentale per un'integrazione senza interruzioni e prestazioni ottimali.

Testo della richiesta

N/D.

Stato della risposta

Oltre agli stati HTTP standard elencati negli stati di risposta api standard, l'API può restituire anche lo stato HTTP seguente:

Codice	Descrizione
410 - Via	Il collegamento al manifesto scade dopo un periodo di tempo impostato. Per ottenere di nuovo il collegamento al manifesto, inviare una nuova richiesta.

Payload della risposta

Il payload della risposta API include gli attributi seguenti:

Attributo	Obbligatorio	Descrizione
id	Vero	Identificatore univoco per ogni risposta Obbligatorio.
stato	Vero	Valori e azioni: obbligatorio. notstarted: attendere l'ora specificata nell'intestazione "Retry-After", quindi effettuare un'altra chiamata per controllare lo stato. running: attendere il tempo specificato nell'intestazione "Retry-After", quindi effettuare un'altra chiamata per controllare lo stato. succeeded: i dati sono pronti. Recuperare il payload del manifesto usando l'URI specificato in resourceLocation. failed: l'operazione non è riuscita in modo permanente. Riavviarlo.
createdDateTime	Vero	Ora in cui è stata effettuata la richiesta. Obbligatorio.
lastActionDateTime	Vero	Ora dell'ultima modifica dello stato. Obbligatorio.
resourceLocation	Falso	URI per il payload del manifesto. Facoltativo.
Errore	Falso	Informazioni dettagliate su eventuali errori, forniti in formato JSON. Facoltativo. Attributi inclusi: message: Descrizione dell'errore. code: tipo di errore.

Oggetto percorso risorsa

Attributo	Descrizione
id	Identificatore univoco per il manifesto.
schemaVersion	Versione dello schema del manifesto.
dataFormat	Formato del file di dati di fatturazione. compressedJSON: formato di dati in cui ogni BLOB è un file compresso che contiene dati in formato righe JSON . Per recuperare i dati da ogni BLOB, decomprimerli.
createdDateTime	Data e ora di creazione del file manifesto.
eTag	Versione dei dati del manifesto. Viene generato un nuovo valore ogni volta che viene apportata una modifica alle informazioni di fatturazione.
partnerTenantId	ID Microsoft Entra del tenant del partner.
rootDirectory	Directory radice del file.
sasToken	Token di firma di accesso condiviso (firma di accesso condiviso) che consente di leggere tutti i file nella directory.
partitionType	Divide i dati in più BLOB in base all'attributo partitionValue . Il sistema suddivide le partizioni che superano il numero supportato. Per impostazione predefinita, i dati vengono partizionati in base al numero di elementi di riga nel file. Non impostare un numero fisso di voci o dimensioni del file nel codice, perché questi valori possono cambiare.
blobCount	Numero totale di file per questo ID tenant partner.
blob	Matrice JSON di oggetti "BLOB" che contengono i dettagli del file per l'ID tenant del partner.
oggetto BLOB	Oggetto contenente i dettagli seguenti: name e partitionValue
name	Nome del BLOB.
partitionValue	Partizione contenente il file. Partizione che contiene il file. Le partizioni di grandi dimensioni sono suddivise in più file, ognuno contenente lo stesso "partitionValue".

Richiesta API

GET <https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14>

Risposta dell'API

La risposta consiglia di attendere 10 secondi prima di riprovare quando i dati sono ancora in fase di elaborazione.

HTTP/1.1 200 OK  
Retry-After: 10  
{  
"id": "9ab9cb54-d07f-4f52-9ea6-a09d7de52c14",  
"createdDateTime": "2022-06-1T10-01-03.4Z",  
"lastActionDateTime": "2022-06-1T10-01-05Z",  
"status": "running"  
}

Richiesta API

(10 secondi dopo la richiesta precedente...)

GET <https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14>

Risposta dell'API

L'API restituisce lo stato "succeeded" e l'URI per "resourceLocation".

HTTP/1.1 200 OK  
Content-Type: application/json  
{

    "@odata.context": "https://graph.microsoft.com/v1.0/\$metadata#reports/partners/billing/operations/\$entity",

    "@odata.type": "#microsoft.graph.partners.billing.exportSuccessOperation",

    "id": "f2170b13-6a8e-47d6-b481-6988490dc0cb",

    "createdDateTime": "2023-12-05T21:17:29Z",

    "lastActionDateTime": "2023-12-05T21:18:00.8897902Z",

    "status": "succeeded",

    "resourceLocation": {

        "id": "44e8500b-ab92-490e-8ac3-90500a1d3427",

        "createdDateTime": "2023-11-06T19:58:47.513Z",

        "schemaVersion": "2",

        "dataFormat": "compressedJSON",

        "partitionType": "default",

        "eTag": "RwDrn7fbiTXy6UULE",

        "partnerTenantId": "0e195b37-4574-4539-bc42-0e539b9684c0",

        "rootDirectory": "https://adlsreconbuprodeastus201.blob.core.windows.net/path_id",

        "sasToken": "{token}",

        "blobCount": 1,

        "blobs": \[

            {

                "name": "part-00123-5a93fa5d-749f-48bc-a372-9b021d93c3fa.c000.json.gz",

                "partitionValue": "default"

            }

        \]

    }

}

Passaggio 3: Scaricare le voci di riconciliazione fatturate dall'archivio BLOB di Azure

Prima di tutto, è necessario ottenere il token di firma di accesso condiviso e il percorso di archiviazione BLOB. Questi dettagli sono disponibili nelle proprietà "sasToken" e "rootDirectory" della risposta dell'API del payload del manifesto. Quindi, per scaricare e decomprimere il file BLOB, usare lo strumento/SDK Archiviazione di Azure. È nel formato JSONLines .

Suggerimento

Assicurarsi di controllare il codice di esempio. Illustra come scaricare e decomprimere il file BLOB di Azure nel database locale.

Stati di risposta API standard

È possibile ottenere questi stati HTTP dalla risposta dell'API:

Codice	Descrizione
400 - Richiesta non valida	La richiesta è mancante o contiene dati non corretti. Controllare il corpo della risposta per i dettagli dell'errore.
401 - Non autorizzato	L'autenticazione è necessaria prima di effettuare la prima chiamata. Eseguire l'autenticazione con il servizio API partner.
403 - Accesso negato	Non si dispone dell'autorizzazione necessaria per effettuare la richiesta.
404 - Non trovato	Le risorse richieste non sono disponibili con i parametri di input forniti.
410 - Via	Il collegamento al manifesto non è più valido o attivo. Inviare una nuova richiesta.
500 - Errore interno del server	L'API o le relative dipendenze non possono soddisfare la richiesta al momento. Riprovare.
5000 - Nessun dato disponibile	Il sistema non dispone di dati per i parametri di input forniti.

Attributi della voce di riconciliazione fatturata

Per confrontare gli attributi restituiti dall'API di riconciliazione fatturata per i set di attributi "full" o "basic", vedere la tabella seguente. Per altre informazioni su questi attributi, vedere Uso del file di riconciliazione.

Attributo	Completo	Di base
PartnerId	yes	yes
CustomerId	yes	yes
CustomerName	yes	yes
CustomerDomainName	yes	no
CustomerCountry	yes	no
InvoiceNumber	yes	yes
MpnId	yes	no
Tier2MpnId	yes	yes
OrderId	yes	yes
DataOrdine	yes	yes
ProductId	yes	yes
SkuId	yes	yes
AvailabilityId	yes	yes
SkuName	yes	no
ProductName	yes	yes
ChargeType	yes	yes
UnitPrice	yes	yes
Quantità	yes	no
Subtotale	yes	yes
TaxTotal	yes	yes
Totale	yes	yes
Valuta	yes	yes
PriceAdjustmentDescription	yes	yes
PublisherName	yes	yes
PublisherId	yes	no
SubscriptionDescription	yes	no
SubscriptionId	yes	yes
ChargeStartDate	yes	yes
ChargeEndDate	yes	yes
TermAndBillingCycle	yes	yes
EffectiveUnitPrice	yes	yes
UnitType	yes	no
AlternateId	yes	no
BillableQuantity	yes	yes
BillingFrequency	yes	no
PricingCurrency	yes	yes
PCToBCExchangeRate	yes	yes
PCToBCExchangeRateDate	yes	no
MeterDescription	yes	no
ReservationOrderId	yes	yes
CreditReasonCode	yes	yes
SubscriptionStartDate	yes	yes
SubscriptionEndDate	yes	yes
ReferenceId	yes	yes
ProductQualifiers	yes	no
PromotionId	yes	yes
ProductCategory	yes	yes

Codice di esempio

Per usare questa API, vedere il collegamento seguente, che include il codice di esempio C#.

Partner-Center-Billing-Recon-Samples: esempi per l'API per ottenere i dati di riconciliazione della fatturazione dal Centro per i partner (github.com).