Ottenere una raccolta di fatture

Si applica a: Centro per i partner gestito da 21Vianet | Centro per i partner per Microsoft Cloud per il governo degli Stati Uniti

Nota

Per gli acquisti commerciali moderni, questa API è applicabile solo per l'utilizzo valutato giornaliero e le fatture generate prima del 15 maggio 2025.

Come recuperare una raccolta delle fatture del partner.

Prerequisiti

C#

Per ottenere una raccolta di tutte le fatture disponibili, utilizzare la proprietàFatture per ottenere un'interfaccia per le operazioni della fattura e quindi chiamare il metodo geto GetAsync per recuperare la raccolta.

Per ottenere una raccolta paginata di fatture, per prima cosa chiamare il metodo BuildIndexedQuery e passargli la dimensione della pagina per creare un oggetto IQuery. Usare quindi la proprietàInvoices per ottenere un'interfaccia per le operazioni di fatturazione e quindi passare l'oggetto IQuery all'queryo metodo queryAsync per inviare la richiesta e ottenere la prima pagina.

Usare quindi la proprietàEnumeratoriper ottenere un'interfaccia per la raccolta di enumeratori di risorse supportati e quindi chiamare Invoices.Create per creare un enumeratore per scorrere la raccolta delle fatture. Usare infine l'enumeratore per recuperare e usare ogni pagina di fatture, come illustrato nell'esempio di codice seguente. Ogni chiamata al metodo Next invia una richiesta per la pagina successiva delle fatture in base alla dimensione della pagina.

// IAggregatePartner partnerOperations;
// int invoicePageSize;

// Is this an unpaged or paged request?
bool isUnpaged = (this.invoicePageSize <= 0);

// If the scenario is unpaged, get all the invoices, otherwise get the first page.
var invoicesPage = (isUnpaged)
                 ? partnerOperations.Invoices.Get()
                 : partnerOperations.Invoices.Query(QueryFactory.Instance.BuildIndexedQuery(this.invoicePageSize));

// Create an invoice enumerator for traversing the invoice pages.
var invoicesEnumerator = partnerOperations.Enumerators.Invoices.Create(invoicesPage);
int lineCounter = 1;

while (invoicesEnumerator.HasValue)
{
    // Print the current invoice results page.
    var invoices = invoicesEnumerator.Current.Items;

    foreach (var i in invoices)
    {
        Console.WriteLine(String.Format("{0,3}. {1}  {2}  {3,16:C2}",
            lineCounter++,
            i.Id,
            i.InvoiceDate.ToString("yyyy&#39;-&#39;MM&#39;-&#39;dd&#39;T&#39;HH&#39;:&#39;mm&#39;:&#39;ss&#39;Z&#39;"),
            i.TotalCharges));
    }

    Console.WriteLine();
    Console.Write("Press any key to retrieve the next invoices page");
    Console.ReadKey();

    // Get the next page of invoices.
    invoicesEnumerator.Next();
}

Per un esempio leggermente diverso, vedere esempio: app console di test. Project: Esempi di SDK del Centro partner Classe: GetPagedInvoices.cs

Nota

La stessa API viene usata per tutti gli acquisti commerciali moderni (fatture generate prima del 15 maggio 2025), oltre a 145p e licenze di Office. Le dimensioni e gli offset vengono considerati solo per le fatture precedenti. Per tutti gli acquisti commerciali moderni, la dimensione pagina & offset verrà ignorata.

Richiesta REST

Sintassi della richiesta

Metodo URI della richiesta
OTTIENI {baseURL}/v1/invoices?size={size}&offset={offset} HTTP/1.1
OTTIENI {baseURL}/v1/invoices?size={size}&offset={offset}&filter={"LeftFilter":{"Field":{field},"Value":{value},"Operator":{operator}},"RightFilter":{"Field":{field},"Value":{value},"Operator":{operator}},"Operator":{operator}} HTTP/1.1

Parametri URI

Usare i parametri di query seguenti durante la creazione della richiesta.

Nome Digitare Obbligatorio Descrizione
grandezza Int NO Numero di risorse della fattura da restituire nella risposta. Questo parametro è facoltativo.
scarto Int NO Indice in base zero della prima fattura da restituire.
filtro corda NO Criteri di filtro personalizzati basati su testo per ridurre le risorse della fattura nella risposta. Utilizzare questa condizione per evitare errori di timeout. Vedi come usare la condizione del filtro

Come usare la condizione di filtro

Esempio della condizione di filtro:

/v1/invoices?size=10&offset=0&filter={"LeftFilter":{"Field":"InvoiceDate","Value":"01/01/2023","Operator":"greater_than_or_equals"},"RightFilter":{"Field":"InvoiceDate","Value":"12/31/2023","Operator":"less_than_or_equals"},"Operator":"and"}

Per filtrare i dati in modo efficace, comprendere i tre componenti principali dei criteri di filtro:

  • LeftFilter: Specificare il campo, il valore e l'operatore per il lato sinistro dell'espressione di filtro per impostare la condizione iniziale.
  • Campo: attributo da usare per filtrare
  • Valore: valore dell'attributo

Ad esempio, "LeftFilter": {"Field":"InvoiceDate","Value":"01/01/2023","Operator":"greater_than_or_equals"} filtra le fatture dal 1° gennaio 2023 in poi.

  • RightFilter: Definire il campo, il valore e l'operatore per il lato destro dell'espressione di filtro per completare la condizione.

Ad esempio, "RightFilter":{"Field":"InvoiceDate","Value":"12/31/2023","Operator":"less_than_or_equals"} filtra le fatture il 31 dicembre 2023 o prima del 31 dicembre 2023.

  • Operatore : Connettere i filtri sinistro e destro con un operatore logico. Usare "e" o "o" per combinare i criteri.

Ad esempio, "Operator": "and" assicura che il filtro includa fatture che soddisfano entrambe le condizioni.

Per un singolo filtro, immettere il nome del campo, il valore e l'operatore senza bisogno dei costrutti "LeftFilter" o "RightFilter".

Questo approccio consente di filtrare i dati in modo preciso ed efficiente.

Intestazioni della richiesta

Per altre informazioni, vedere intestazioni REST del Centro per i partner.

Corpo della richiesta

Nessuno

Esempio di richiesta

GET https://api.partnercenter.microsoft.com/v1/invoices?size=200&offset=0 HTTP/1.1
Authorization: Bearer <token>
Accept: application/json
MS-RequestId: e88d014d-ab70-41de-90a0-f7fd1797267d
MS-CorrelationId: aaaa0000-bb11-2222-33cc-444444dddddd
X-Locale: en-US
MS-PartnerCenter-Application: Partner Center .NET SDK Samples
Host: api.partnercenter.microsoft.com

Importante

A partire da giugno 2023, la versione più recente di .NET SDK del Centro per i partner 3.4.0 è ora archiviata. È possibile scaricare la versione dell'SDK da GitHub, insieme a un file leggimi che contiene informazioni utili.

I partner sono invitati a continuare a usare le API REST del Centro per i partner .

Risposta REST

In caso di esito positivo, il corpo della risposta contiene la raccolta di risorse Invoice.

Codici di errore e esito positivo della risposta

Ogni risposta viene fornita con un codice di stato HTTP che indica l'esito positivo o negativo e altre informazioni di debug. Usare uno strumento di traccia di rete per leggere questo codice, il tipo di errore e altri parametri. Per l'elenco completo, vedere codici di errore REST del Centro per i partner.

Esempio di risposta

HTTP/1.1 200 OK
Content-Length: 256
Content-Type: application/json; charset=utf-8
MS-CorrelationId: bbbb1111-cc22-3333-44dd-555555eeeeee
MS-RequestId: a45e6643-1caf-4429-8f90-07c03d85bc2b
Date: Thu, 24 Mar 2016 05:21:01 GMT
{
    "totalCount": 2,
    "items": [
        {
            "id": "D02005YFHI",
            "invoiceDate": "2017-01-21T00:00:00Z",
            "totalCharges": 24606.35,
            "paidAmount": 1000,
            "currencyCode": "GBP",
            "currencySymbol": "£",
            "pdfDownloadLink": "/invoices/D02005YFHI/documents/statement",
            "taxReceipts": [
                {
                    "id": "123456",
                    "taxReceiptPdfDownloadLink": "/invoices/D02005YFHI/receipts/123456/documents/statement"
                }
            ],
            "invoiceDetails": [
                {
                    "invoiceLineItemType": "billing_line_items",
                    "billingProvider": "office",
                    "links": {
                        "self": {
                            "uri": "/invoices/Recurring-D02005YFHI/lineitems/Office/BillingLineItems",
                            "method": "GET",
                            "headers": []
                        }
                    },
                    "attributes": {
                        "objectType": "InvoiceDetail"
                    }
                }
            ],
            "documentType": "invoice",
            "invoiceType": "Recurring",
            "links": {
                "self": {
                    "uri": "/invoices/Recurring-D02005YFHI",
                    "method": "GET",
                    "headers": []
                }
            },
            "attributes": {
                "objectType": "Invoice"
            }
        },
        {
            "id": "G000024130",
            "invoiceDate": "2018-02-08T01:22:47.603895Z",
            "totalCharges": 586366,
            "paidAmount": 0,
            "currencyCode": "CHF",
            "currencySymbol": "CHF",
            "pdfDownloadLink": "/invoices/G000024130/documents/statement",
            "taxReceipts": [
                {
                    "id": "234567",
                    "taxReceiptPdfDownloadLink": "/invoices/G000024130/receipts/234567/documents/statement"
                }
            ],
            "invoiceDetails": [
                {
                    "invoiceLineItemType": "billing_line_items",
                    "billingProvider": "one_time",
                    "links": {
                        "self": {
                            "uri": "/invoices/OneTime-G000024130/lineitems/OneTime/BillingLineItems",
                            "method": "GET",
                            "headers": []
                        }
                    },
                    "attributes": {
                        "objectType": "InvoiceDetail"
                    }
                }
            ],
            "amendments": [
                {
                    "id": "G000024131",
                    "invoiceDate": "2018-02-08T18:44:37.5381456Z",
                    "totalCharges": 107661.12,
                    "paidAmount": 0,
                    "currencyCode": "CHF",
                    "currencySymbol": "CHF",
                    "invoiceDetails": [
                        {
                            "invoiceLineItemType": "billing_line_items",
                            "billingProvider": "one_time",
                            "attributes": {
                                "objectType": "InvoiceDetail"
                            }
                        }
                    ],
                    "documentType": "adjustment_note",
                    "amendsOf": "G000024130",
                    "invoiceType": "OneTime",
                    "attributes": {
                        "objectType": "Invoice"
                    }
                }
            ],
            "documentType": "void_note",
            "invoiceType": "OneTime",
            "links": {
                "self": {
                    "uri": "/invoices/OneTime-G000024130",
                    "method": "GET",
                    "headers": []
                }
            },
            "attributes": {
                "objectType": "Invoice"
            }
        }
    ],
    "links": {
        "self": {
            "uri": "/invoices?size=2&offset=0",
            "method": "GET",
            "headers": []
        },
        "next": {
            "uri": "/invoices?size=2&offset=2",
            "method": "GET",
            "headers": []
        }
    },
    "attributes": {
        "objectType": "Collection"
    }
}

Nota

Per gli acquisti commerciali moderni, questa API restituisce il percorso "deprecato" per le riconciliazione delle fatture generate dopo il 15 maggio 2025.

Immagine con il confronto delle risposte per i percorsi deprecati.

  • Last updated on