Obter uma coleção de faturas

  • Artigo

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

Como recuperar uma coleção de faturas do parceiro.

Pré-requisitos

  • Credenciais, conforme descrito em Autenticação do Partner Center. Esse cenário dá 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 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 com suporte e, em seguida, chame Invoices.Create para criar um enumerador para percorrer a coleção de faturas. Por fim, 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 um pouco diferente, consulte Exemplo: aplicativo de teste de console. Projeto: Exemplos do SDK do Partner Center Classe: GetPagedInvoices.cs

Observação

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

Solicitação REST

Sintaxe da solicitação

Método URI da solicitação
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 do URI

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

Nome Digitar Obrigatória Descrição
tamanho int Não O número de recursos de fatura a serem retornados na resposta. Esse parâmetro é opcional.
deslocamento int Não O índice baseado em zero da primeira fatura a ser retornada.
filtro string Não Critérios de filtro personalizados baseados em texto para reduzir os recursos da fatura na resposta. Use essa condição para evitar erro de tempo limite. Veja como usar a condição de filtro

Como usar a condição de 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":"12/31/2023","Operator":"less_than_or_equals"},"Operator":"and"}

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

  • LeftFilter: a primeira construção de filtro, em que 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 com data de fatura igual ou posterior a 1º de janeiro de 2023.

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

    Por exemplo, "RightFilter":{"Field":"InvoiceDate","Value":"12/31/2023","Operator":"less_than_or_equals"} significa que você deseja filtrar faturas com uma data de fatura igual ou superior a 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 da solicitação

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

Corpo da solicitação

Nenhum

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

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

Resposta REST

Se for bem-sucedido, o corpo da resposta conterá a coleção de recursos da fatura .

Códigos de êxito e de erro de resposta

Cada resposta vem com um código de status HTTP que indica êxito 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, confira 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"
    }
}