Obter uma coleção de faturas

  • Artigo

Aplica-se a: Partner Center | Partner Center operado pela 21Vianet | Partner Center for Microsoft Cloud for US Government

Como recuperar uma cobrança das faturas do parceiro.

Pré-requisitos

  • Credenciais conforme descrito na autenticação do Partner Center. Este cenário oferece suporte à autenticação com credenciais autônomas de Aplicativo e Aplicativo+Usuário.

C#

Para obter uma coleção de todas as faturas disponíveis, use a propriedade Invoices para obter uma interface para operações de fatura e, em seguida, chame o método Get ou GetAsync para recuperar a coleção.

Para obter uma coleção paginada de faturas, primeiro chame o método BuildIndexedQuery e passe-lhe o tamanho da página para criar um objeto IQuery. Em seguida, use a propriedade Invoices para obter uma interface para operações de fatura e, em seguida, passe o objeto IQuery para o método Query ou QueryAsync para enviar a solicitação e obter a primeira página.

Em seguida, use a propriedade Enumerators para obter uma interface para a coleção de enumeradores de coleção de recursos suportados e, em seguida, chame Invoices.Create para criar um enumerador para percorrer a coleção de faturas. Finalmente, use o enumerador para recuperar e trabalhar com cada página de faturas, conforme mostrado no exemplo de código a seguir. Cada chamada para o método Next envia uma solicitação para a próxima página de faturas com base no tamanho da página.

// 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();
}

Para obter um exemplo ligeiramente diferente, consulte Exemplo: aplicativo de teste de console. Projeto: Exemplos de SDK do Partner Center Classe: GetPagedInvoices.cs

Nota

A mesma API é usada para todas as compras comerciais modernas, bem como licenças 145p e Office. O tamanho e o deslocamento só são considerados para faturas antigas. Para todas as compras comerciais modernas, o tamanho da página e o deslocamento serão ignorados.

Pedido REST

Sintaxe da solicitação

Método URI do pedido
GET {baseURL}/v1/faturas?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

Parâmetros de URI

Use os seguintes parâmetros de consulta ao criar a solicitação.

Nome Type Obrigatório Description
size número inteiro Não O número de recursos de fatura a serem retornados na resposta. Este parâmetro é opcional.
offset número inteiro Não O índice baseado em zero da primeira fatura a ser devolvida.
filtrar string Não Critérios de filtro personalizados baseados em texto para reduzir os recursos de fatura na resposta. Use essa condição para evitar erro de tempo limite. Veja como usar a condição do filtro

Como usar a condição do filtro

Um exemplo da condição do filtro:

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

Os critérios de filtragem consistem em três partes:

  • LeftFilter: A primeira construção de filtro, onde você especifica o campo, o valor e o operador para o lado esquerdo da expressão de filtro.

    Campo: Atributo a ser usado para filtrar. Valor: Valor do atributo

    Por exemplo, "LeftFilter": {"Field":"InvoiceDate","Value":"01/01/2023","Operator":"greater_than_or_equals"} significa que você deseja filtrar faturas que tenham uma data de fatura em ou após 1º de janeiro de 2023.

  • RightFilter: A segunda construção de filtro, onde você especifica o campo, o valor e o operador para o lado direito da expressão de filtro.

    Por exemplo, "RightFilter":{"Field":"InvoiceDate","Value":"31/12/2023","Operator":"less_than_or_equals"} significa que você deseja filtrar faturas que tenham uma data de fatura em ou antes de 31 de dezembro de 2023.

  • Operador: O operador lógico que conecta os filtros esquerdo e direito. Você pode usar "e" ou "ou" como operador.

    Por exemplo, "Operador": "e" significa que você deseja filtrar faturas que atendam aos critérios de filtro esquerdo e direito.

Para usar um único filtro, basta inserir o nome do campo, o valor e o operador. Não há necessidade da construção "LeftFilter" ou "RightFilter".

Cabeçalhos do pedido

Para obter mais informações, consulte Cabeçalhos REST do Partner Center.

Corpo do pedido

Nenhuma

Exemplo de solicitação

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 partir de junho de 2023, a versão 3.4.0 mais recente do SDK do .NET do Partner Center foi arquivada. Você pode baixar a versão do SDK do GitHub, juntamente com um arquivo readme que contém informações úteis.

Os parceiros são incentivados a continuar a usar as APIs REST do Partner Center.

Resposta do REST

Se bem-sucedida, o corpo da resposta contém a coleção de recursos da fatura .

Códigos de sucesso e erro de resposta

Cada resposta vem com um código de status HTTP que indica sucesso ou falha e outras informações de depuração. Use uma ferramenta de rastreamento de rede para ler esse código, tipo de erro e outros parâmetros. Para obter a lista completa, consulte Códigos de erro REST do Partner Center.

Exemplo de resposta

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