Ottenere una raccolta di fatture

  • Articolo

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

Come recuperare una raccolta delle fatture del partner.

Prerequisiti

C#

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

Per ottenere una raccolta di fatture di paging, chiamare prima il metodo BuildIndexedQuery e passarlo alle dimensioni della pagina per creare un oggetto IQuery. Usare quindi la proprietà Invoices per ottenere un'interfaccia per le operazioni della fattura e quindi passare l'oggetto IQuery al metodo Query o QueryAsync per inviare la richiesta e ottenere la prima pagina.

Usare quindi la proprietà Enumerator per ottenere un'interfaccia per la raccolta di enumeratori della raccolta di risorse supportati e quindi chiamare Invoices.Create per creare un enumeratore per attraversare la raccolta di 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 alle dimensioni 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, vedi Esempio: App di test della console. Project: Partner Center SDK Samples Class: GetPagedInvoices.cs

Nota

La stessa API viene usata per tutti gli acquisti commerciali moderni, nonché per le licenze di Office e 145p. Le dimensioni e gli offset vengono considerati solo per le fatture legacy. Per tutti gli acquisti commerciali moderni, paginezza e offset verranno ignorati.

Richiesta REST

Sintassi della richiesta

metodo URI della richiesta
GET {baseURL}/v1/invoices?size={size}&offset={offset} HTTP/1.1
GET {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 Digita Obbligatorio Descrizione
size int No Numero di risorse della fattura da restituire nella risposta. Il parametro è facoltativo.
offset int No Indice in base zero della prima fattura da restituire.
filter string No Criteri di filtro personalizzati basati su testo per ridurre le risorse della fattura nella risposta. Utilizzare questa condizione per evitare errori di timeout. Vedere come usare la condizione di 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"}

I criteri di filtro sono costituiti da tre parti:

  • LeftFilter: primo costrutto di filtro, in cui si specifica il campo, il valore e l'operatore per il lato sinistro dell'espressione di filtro.

    Campo: attributo da usare per filtrare. Valore: valore dell'attributo

    Ad esempio, "LeftFilter": {"Field":"InvoiceDate","Value":"01/01/2023","Operator":"greater_than_or_equals"} indica che si desidera filtrare le fatture con una data di fattura il 1° gennaio 2023.

  • RightFilter: secondo costrutto di filtro, in cui si specificano il campo, il valore e l'operatore per il lato destro dell'espressione di filtro.

    Ad esempio, "RightFilter":{"Field":"InvoiceDate","Value":"12/31/2023","Operator":"less_than_or_equals"} indica che si desidera filtrare le fatture con una data di fattura il 31 dicembre 2023.

  • Operatore: operatore logico che connette i filtri sinistro e destro. È possibile usare "and" o "or" come operatore.

    Ad esempio, "Operator": "and" indica che si vogliono filtrare le fatture che soddisfano sia i criteri di filtro sinistro che destro.

Per usare un singolo filtro, è sufficiente immettere il nome, il valore e l'operatore del campo. Non è necessario il costrutto "LeftFilter" o "RightFilter".

Intestazioni delle richieste

Per altre informazioni, vedi Intestazioni REST del Centro per i partner.

Testo della richiesta

None

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: de894e18-f027-4ac0-8b5a-34f0c222af0c
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 di esito 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, vedi Codici di errore REST del Centro per i partner.

Risposta di esempio

HTTP/1.1 200 OK
Content-Length: 256
Content-Type: application/json; charset=utf-8
MS-CorrelationId: 57eb2ca7-755f-450f-9187-eae1e75a0114
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"
    }
}