Condividi tramite


API di riconciliazione delle fatture addebitate v2 (GA)

si applica a: Centro per i partner (non disponibile in Azure per enti pubblici o Azure Cina 21Vianet)

Comprendere l'architettura

La nuova API asincrona offre miglioramenti significativi nella gestione dell'accesso ai dati di fatturazione e riconciliazione. Questo approccio risolve i problemi associati ai metodi sincroni tradizionali, ad esempio la gestione di connessioni di lunga durata e l'elaborazione di batch di dati di grandi dimensioni. Ecco i principali vantaggi e meccanismi di questa API:

Componenti fondamentali

Proteggere l'accesso con lo schema di chiave del valet

Il modello di chiave di servizio fornisce un accesso sicuro e limitato ai dati di fatturazione. Analogamente al modo in cui una chiave di controllo consente a qualcuno di guidare la tua auto senza accedere al bagagliaio, questo modello garantisce un controllo di accesso granulare. Invece di condividere le credenziali, un token di firma di accesso condiviso concede un accesso limitato e associato a tempo a risorse specifiche. Questo modello riduce il rischio di accesso non autorizzato configurando precise scadenze e autorizzazioni di accesso.

Miglioramento dell'efficienza tramite un modello asincrono di richiesta-risposta

Pensaci come ordinare in un ristorante affollato. Invece di aspettare al banco, ricevi un ronzio e puoi fare altre cose mentre il tuo ordine è preparato. Quando i dati sono pronti, il sistema invia una notifica.

La natura asincrona dell'API significa effettuare una richiesta e il sistema lo elabora in background. Questo richiesta-risposta asincrona usa in modo efficiente le risorse, riduce il carico del server e riduce al minimo i timeout e i fallimenti comuni con il recupero sincrono dei dati.

Flessibilità nelle autorizzazioni di accesso ai dati

I token SAS offrono flessibilità nella gestione dei permessi di accesso ai dati. È possibile generare token che concedono l'accesso a tutti gli attributi dei dati di riconciliazione fatturati o limitare l'accesso a subset specifici. Questa granularità consente alle organizzazioni di personalizzare l'accesso ai dati in base ai criteri interni e ai requisiti normativi, migliorando la sicurezza e la conformità.

Flusso di lavoro semplificato e tempi di elaborazione dei dati migliorati

Il modello richiesta-risposta asincrono semplifica l'elaborazione dei dati consentendo un accesso dinamico anziché attraverso lotti fissi di 2.000 elementi. Questo approccio porta a risultati più rapidi e tempi di elaborazione migliorati, semplificando l'integrazione dei dati di fatturazione e riconciliazione in sistemi e flussi di lavoro esistenti.

Vantaggi

  1. Vantaggi delle prestazioni

    Anziché mantenere connessioni di lunga durata ed elaborare batch fissi, il nuovo sistema consente di:

    • Effettuare una rapida richiesta iniziale.
    • Ricevere un token di accesso sicuro.
    • Elaborare i dati in base al proprio ritmo.
    • Accedere esattamente a ciò di cui hai bisogno quando ti serve.
  2. miglioramenti della sicurezza

    Il modello di chiave di valletto, implementato tramite token SAS, fornisce:

    • Accesso limitato al tempo.
    • Autorizzazioni limitate.
    • Eliminazione della condivisione o dell'archiviazione di credenziali permanenti.
    • Controllo di accesso con granularità fine.
  3. Vantaggi Architettonici

    Il modello di richiesta-risposta asincrona funziona come un assistente personale che:

    • Accetta la richiesta.
    • Gestisce l'attività in background.
    • Notifica quando tutto è pronto.

Adottare API ottimizzate per migliorare le prestazioni

L'adozione di queste API ottimizzate semplifica il flusso di lavoro e migliora le prestazioni complessive nella gestione dei dati. Usando il controllo degli accessi sicuro e meccanismi di recupero efficienti, si ottengono risultati migliori con meno sforzo, con conseguente miglioramento dell'efficienza operativa.

In conclusione, la nuova API asincrona per l'accesso ai dati di fatturazione e riconciliazione tramite BLOB di Azure è uno strumento potente. Offre accesso sicuro ed efficiente ai dati finanziari, semplificando i flussi di lavoro, riducendo i carichi del server e migliorando i tempi di elaborazione, tutto con sicurezza e conformità elevate.

Nota

La nuova API non è ospitata nell'host API del Centro per i partner. Al contrario, è possibile trovarla in Microsoft 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.

Consentire all'app di accedere in modo sicuro ai dati di fatturazione dei partner

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. Questo passaggio è fondamentale perché garantisce che l'app possa accedere in modo sicuro ai dati necessari.

Registrare l'app e assegnare l'autorizzazione PartnerBilling.Read.All

È possibile assegnare l'autorizzazione "PartnerBilling.Read.All" usando il portale di Azure o l'interfaccia di amministrazione di Microsoft Entra. Completando questi passaggi, si garantisce che l'app abbia l'accesso necessario ai dati di fatturazione dei partner. Ecco come fare:

  1. Registrare l'app nella home page di Microsoft Entra nella sezione Registrazioni app.
  2. Concedere l'autorizzazione necessaria passando alla pagina dell'app Microsoft Entra. Nella sezione Autorizzazioni API selezionare Aggiungi un'autorizzazione e scegliere l'ambito PartnerBilling.Read.All.

Informazioni sugli endpoint principali dell'API

Per aiutarti a recuperare in modo asincrono le voci di riconciliazione delle fatture del nuovo commercio, offriamo due endpoint API chiave. Questi endpoint consentono di gestire in modo efficiente il processo di riconciliazione delle fatture. Seguire questa guida semplificata per iniziare rapidamente.

Usare l'endpoint di riconciliazione della fattura

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. Verificare regolarmente questo URL fino a ottenere uno stato di successo e un URL del manifest.

Utilizzare l'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.

Esaminare il diagramma di sequenza

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

Diagramma che mostra i passaggi per il download dei dati di riconciliazione.

Seguire la sequenza di azioni dell'utente per recuperare i dati di riconciliazione delle fatture emesse

Ecco la sequenza di azioni dell'utente per recuperare i dati di riconciliazione delle fatture:

Inviare una richiesta POST

Inviare una richiesta POST all'endpoint API.

Ottenere le voci di riconciliazione delle fatture fatturate

Ottieni le voci delle righe di riconciliazione della fattura.

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 Tipo Descrizione
insieme di attributi Falso Stringa Scegliere "full" per tutti gli attributi o "basic" per un set limitato. Se non specificato, "full" è il valore predefinito. Controlla l'elenco degli attributi in questa sezione. Facoltativo.
ID fattura 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 tue 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, consultare l'URL fornito nell'intestazione della posizione.

Controllare lo stato della richiesta

Per tenere traccia dello stato di una richiesta, assicurarsi di ricevere una risposta HTTP 200, che è un codice di stato standard che indica "riuscito" o "fallito". In caso di esito positivo, l'URL del manifest si trova 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 Includere in Richiesto Tipo Descrizione
operationId URI della richiesta Vero Stringa Identificatore univoco per controllare lo stato della richiesta. Obbligatorio.

Intestazione della richiesta

Intestazioni di richiesta per l'API utilizzando 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 - Non più disponibile 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 Richiesto Descrizione
id Vero Identificatore univoco per ogni risposta
Obbligatorio.
stato Vero Valori e azioni: obbligatorio.
non avviato: attendere la durata specificata nell'intestazione "Retry-After", quindi effettuare una nuova chiamata per controllare lo stato.
attivo: attendere la durata specificata 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.
dataOraUltimaAzione Vero L'ultima volta che lo stato è cambiato.
Obbligatorio.
resourceLocation Falso URI per il payload del manifest.
Facoltativo.
Errore Falso Informazioni dettagliate su eventuali errori, forniti in formato JSON.
Facoltativo.
Attributi inclusi:
message: Descrizione dell'errore.
code: tipo di errore.

Oggetto di posizione risorsa

Attributo Descrizione
id Identificatore univoco per il manifesto.
schemaVersion Versione dello schema del manifest.
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 manifest. Viene generato un nuovo valore ogni volta che viene apportata una modifica alle informazioni di fatturazione.
partnerTenantId ID del tenant del partner di Microsoft Entra.
rootDirectory Directory radice del file.
sasToken Token SAS (firma di accesso condiviso) che consente di leggere tutti i file nella directory indicata.
tipo di partizione Divide i dati in più BLOB basati sull'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. Evitare di codificare il numero di elementi o le dimensioni dei file, poiché potrebbero cambiare.
blobCount Numero totale di file per questo ID tenant partner.
blocchi Una matrice JSON di oggetti "blob" che contengono i dettagli del file per l'ID del tenant del partner.
oggetto BLOB Oggetto contenente i dettagli seguenti:
name e partitionValue
nome Nome del BLOB.
valore di partizione Partizione che contiene il file. La partizione di grandi dimensioni è suddivisa in più file in base a determinati criteri, ad esempio le dimensioni del file o il numero di record, con ogni file 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": "aaaabbbb-0000-cccc-1111-dddd2222eeee",

        "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"

            }

        \]

    }

}

Scaricare gli elementi della riga di riconciliazione dall'archivio BLOB di Azure

Prima di tutto, è necessario ottenere il token di firma di accesso condiviso (SAS) e la posizione di memorizzazione del BLOB (unendo la directory radice e il nome del BLOB). Trova questi dettagli nelle proprietà sasToken, rootDirectorye blobs della risposta API del payload manifesto.

Per procedere, effettuare i seguenti passaggi:

  1. Scaricare il file BLOB usando l'SDK/strumento di archiviazione di Azure .
  2. Decomprimere il file, che si trova nel formato JSONLines.

Suggerimento

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

Stati di risposta API standard

È possibile ottenere gli stati HTTP seguenti 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 - Vietato 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 - Non Disponibile 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.

Confrontare gli attributi di riconciliazione delle fatture di base e completi

Per confrontare gli attributi restituiti dall'API di riconciliazione delle fatture per i set di attributi "full" o "basic", fare riferimento a questa tabella. Per altre informazioni su questi attributi e sui relativi significati, vedere come usare il file di riconciliazione.

Attributo Completo Di base
PartnerId
ID Cliente
NomeCliente
NomeDominioCliente no
Paese del Cliente no
NumeroFattura
MpnId no
Tier2MpnId
OrderId
DataOrdine
ProductId
SkuId
AvailabilityId
SkuName no
ProductName
Tipo di Addebito
PrezzoUnitario
Quantità no
Subtotale
Totale tasse
Totale
Valuta
DescrizioneAdeguamentoPrezzo
PublisherName
ID Pubblicatore no
Descrizione dell'abbonamento no
ID abbonamento
DataInizioAddebito
ChargeEndDate
Termine e Ciclo di Fatturazione
EffectiveUnitPrice
TipoUnità no
AlternateId no
Quantità Fatturabile
Frequenza di Fatturazione no
Valuta di Prezzo
PCToBCExchangeRate
PCToBCExchangeRateDate no
Descrizione del Contatore no
IDOrdinePrenotazione
CodiceMotivoCredito
DataInizioAbbonamento
SubscriptionEndDate
ID di Riferimento
Qualificatori del Prodotto no
PromotionId
Categoria di Prodotto

Importante

Ogni nome di campo o attributo inizia con un lettera maiuscola per mantenere la coerenza con il file e migliorare la leggibilità.

Codice di esempio

Se è necessaria assistenza per la migrazione a questa API, fare riferimento al collegamento che include il codice di esempio C#.

esempi di API per ottenere i dati di riconciliazione della fatturazione dal Centro per i partner.