Obter os itens de linha de reconciliação não faturados da fatura

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

Você pode usar os métodos a seguir para obter uma coleção de detalhes para itens de linha de fatura não faturados (também conhecidos como itens de linha de cobrança abertos).

Observação

Principais cenários e datas de migração

Para dados de NCE, essa versão da API será preterida a partir de 15 de março de 2026. A estratégia de transição de versão da API ajuda a garantir uma migração suave da API v1 para a API v2, com foco na manutenção da funcionalidade e da integridade dos dados. Aqui está um guia para ajudá-lo a selecionar a versão da API apropriada para suas necessidades:

Cenário A: Períodos recentes de cobrança:

Continue usando essa API até fevereiro de 2026, a menos que você já tenha feito a transição para a API v2 GA.

Cenário B: períodos futuros de cobrança a partir de março de 2026:

Mude para a API v2 em GA para recuperar dados futuros do período de cobrança.

A transição da API v1 para a API v2 envolve planejamento detalhado e implementação precisa. Para garantir uma transição suave para a nova API, consulte: API de itens de reconciliação não faturados v2 (GA).

Cenário C: dados de Comércio Herdado (todos os períodos de cobrança): use essa API V1 exclusivamente para todas as suas necessidades.

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.
Um identificador de fatura. Esta identifica a fatura da qual se deve recuperar os itens de linha.

C#

Para obter os itens de linha da fatura especificada, recupere o objeto da fatura:

Chame o método ById para obter uma interface para operações de fatura para a fatura especificada.
Chame o método Get ou GetAsync para recuperar o objeto da fatura.

O objeto da fatura contém todas as informações da fatura especificada:

O provedor identifica a origem das informações detalhadas não faturadas (por exemplo, OneTime).
InvoiceLineItemType especifica o tipo (por exemplo, BillingLineItem).

Para obter uma coleção de itens de linha que correspondem a uma instância invoiceDetail :

Passe as propriedades BillingProvider e InvoiceLineItemType da instância para o método By.
Chame o método Get ou GetAsync para recuperar os itens de linha associados.
Crie um enumerador para percorrer a coleção. Para obter um exemplo, consulte o código de exemplo a seguir.

O código de exemplo a seguir usa um loop foreach para processar a coleção InvoiceLineItems . Uma coleção separada de itens de linha é recuperada para cada InvoiceLineItemType.

// IAggregatePartner partnerOperations;
// string currencyCode;
// string period;
// int pageMaxSizeReconLineItems = 2000;

// all the operations executed on this partner operation instance will share the same correlation Id but will differ in request Id
IPartner scopedPartnerOperations = partnerOperations.With(RequestContextFactory.Instance.Create(Guid.NewGuid()));

var seekBasedResourceCollection = scopedPartnerOperations.Invoices.ById("unbilled").By("onetime", "billinglineitems", currencyCode, period, pageMaxSizeReconLineItems).Get();

var fetchNext = true;

ConsoleKeyInfo keyInfo;

var itemNumber = 1;
while (fetchNext)
{
    Console.Out.WriteLine("\tLine line items count: " + seekBasedResourceCollection.Items.Count());

    seekBasedResourceCollection.Items.ToList().ForEach(item =>
    {
        // Instance of type OneTimeInvoiceLineItem
        if (item is OneTimeInvoiceLineItem)
        {
            Type t = typeof(OneTimeInvoiceLineItem);
            PropertyInfo[] properties = t.GetProperties();

            foreach (PropertyInfo property in properties)
            {
                // Insert code here to work with the line item properties
            }
        }
        itemNumber++;
    });

    Console.Out.WriteLine("\tPress any key to fetch next data. Press the Escape (Esc) key to quit: \n");
    keyInfo = Console.ReadKey();

    if (keyInfo.Key == ConsoleKey.Escape)
    {
        break;
    }

    fetchNext = !string.IsNullOrWhiteSpace(seekBasedResourceCollection.ContinuationToken);

    if (fetchNext)
    {
        if (seekBasedResourceCollection.Links.Next.Headers != null && seekBasedResourceCollection.Links.Next.Headers.Any())
        {
            seekBasedResourceCollection = scopedPartnerOperations.Invoices.ById("unbilled").By("onetime", "billinglineitems", currencyCode, period, pageMaxSizeReconLineItems).Seek(seekBasedResourceCollection.ContinuationToken, SeekOperation.Next);
        }
    }
}

Para obter um exemplo semelhante, consulte:

Exemplo: aplicativo de teste do console
Projeto: Exemplos do SDK do Partner Center
Classe: GetUnBilledReconLineItemsPaging.cs

Solicitação REST

Sintaxe da solicitação

Você pode usar as seguintes sintaxes para sua solicitação REST, dependendo do seu caso de uso. Para obter mais informações, consulte as descrições de cada sintaxe.

Método	URI de solicitação	Descrição do caso de uso da sintaxe
GET	{baseURL}/v1/invoices/unbilled/lineitems?provider=onetime&invoicelineitemtype=billinglineitems¤cycode={currencycode}&period={period} HTTP/1.1	Use essa sintaxe para retornar uma lista completa de todos os itens de linha da fatura específica.
OBTER	{baseURL}/v1/invoices/unbilled/lineitems?provider=onetime&invoicelineitemtype=billinglineitems¤cycode={currencycode}&period={period}&size={size} HTTP/1.1	Para faturas grandes, use essa sintaxe com um tamanho especificado e um deslocamento baseado em 0 para retornar uma lista paginada de itens de linha.
OBTER	{baseURL}/v1/invoices/unbilled/lineitems?provider=onetime&invoicelineitemtype=billinglineitems¤cycode={currencycode}&period={period}&size={size}&seekOperation=Next	Use essa sintaxe para obter a próxima página de itens de linha de reconciliação usando `seekOperation = "Next"`.

Parâmetros de URI

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

Nome	Tipo	Obrigatório	Description
fornecedor	cadeia	Yes	O provedor: "OneTime".
Tipo de item da fatura	cadeia	Yes	O tipo de detalhe da fatura: "BillingLineItems".
parceiroGanhouCrédito	bool	Não	O valor que indica se deve retornar os itens de linha com o crédito ganho pelo parceiro aplicado. Observação: Este parâmetro será aplicado somente quando o Tipo de Provedor for OneTime e o InvoiceLineItemType for UsageLineItems.
currencyCode	cadeia	Yes	O código de moeda para os itens de linha não faturados.
period	cadeia	Yes	O período para reconciliação não faturada. exemplo: atual, anterior.
size	número	Não	O número máximo de itens a serem retornados. O tamanho padrão é 2000
seekOperation	cadeia	Não	Defina seekOperation=Next para obter a próxima página de itens de linha de reconciliação.

Cabeçalhos da solicitação

Para mais informações, consulte os cabeçalhos REST do Partner Center.

Corpo da solicitação

Nenhum.

Resposta REST

Se bem-sucedida, a resposta contém a coleção de detalhes do item de linha.

Para o item de linha ChargeType, o valor Compra é mapeado para Novo e o valor Reembolso é mapeado para Cancelar.

Códigos de erro e êxito de resposta

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

Exemplos de solicitação-resposta

Exemplo de solicitação-resposta 1

Os seguintes detalhes se aplicam a este exemplo:

Provedor: OneTime
InvoiceLineItemType: Itens de Linha de Fatura
Período: Anterior

Exemplo de solicitação 1

GET https://api.partnercenter.microsoft.com/v1//invoices/unbilled/lineitems?provider=onetime&invoicelineitemtype=billinglineitems&currencycode=usd&period=previous&size=2000 HTTP/1.1
Authorization: Bearer <token>
Accept: application/json
MS-RequestId: 1234ecb8-37af-45f4-a1a1-358de3ca2b9e
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 partir de junho de 2023, a versão mais recente do SDK do .NET do Partner Center 3.4.0 já está arquivada. Você pode baixar a versão do SDK no 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.

Exemplo de resposta 1

HTTP/1.1 200 OK
Content-Length: 2484
Content-Type: application/json; charset=utf-8
MS-CorrelationId: aaaa0000-bb11-2222-33cc-444444dddddd
MS-RequestId: 1234ecb8-37af-45f4-a1a1-358de3ca2b9e
MS-CV: bpqyomePDUqrSSYC.0
MS-ServerId: 202010406
Date: Wed, 20 Feb 2019 19:59:27 GMT

{
   "totalCount": 3,
    "items": [
        {
            "partnerId": "934f3416-bc2f-47f3-b492-77e517d4e572",
            "customerId": "c139c4bf-2e8b-4ab5-8bed-d9f50dcca7a2",
            "customerName": "Test_Test_Office R2 Reduce Seats Validation",
            "customerDomainName": "testcustomerr2t2reduce.onmicrosoft.com",
            "customerCountry": "US",
            "invoiceNumber": "",
            "mpnId": "5357564",
            "resellerMpnId": "4649221",
            "orderId": "94e858b6d855",
            "orderDate": "2021-05-20T18:30:06.6045692Z",
            "productId": "CFQ7TTC0LH0R",
            "skuId": "0002",
            "availabilityId": "CFQ7TTC0K5RQ",
            "productName": "Microsoft 365 Phone System - Virtual User",
            "skuName": "Microsoft 365 Phone System - Virtual User",
            "productQualifiers": [
                "AddOn",
                "Trial"
            ],
            "chargeType": "new",
            "unitPrice": "0",
            "effectiveUnitPrice": "0",
            "unitType": "",
            "quantity": "25",
            "subtotal": "0",
            "taxTotal": "0",
            "totalForCustomer": "0",
            "currency": "USD",
            "publisherName": "Microsoft Corporation",
            "publisherId": "",
            "subscriptionDescription": "",
            "subscriptionId": "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e",
            "subscriptionStartDate": "2021-05-20T00:00:00Z",
            "subscriptionEndDate": "2021-06-19T00:00:00Z",
            "chargeStartDate": "2021-05-20T00:00:00Z",
            "chargeEndDate": "2021-06-19T00:00:00Z",
            "termAndBillingCycle": "One-Month commitment for trial",
            "alternateId": "94e858b6d855",
            "referenceId": "0cf1202a-5b7d-4219-966e-93c637113708",
            "priceAdjustmentDescription": "",
            "discountDetails": "",
            "pricingCurrency": "USD",
            "pcToBCExchangeRate": "1",
            "pcToBCExchangeRateDate": "2021-05-01T00:00:00",
            "billableQuantity": "25",
            "meterDescription": "",
            "billingFrequency": "",
            "reservationOrderId": "99f246cf-ed96-41b4-b0cd-0aa43eb1fe91",
            "invoiceLineItemType": "billing_line_items",
            "billingProvider": "one_time",
            "promotionId": "",
            "attributes": {
                "objectType": "OneTimeInvoiceLineItem"
            }
            
        },
        {
            "partnerId": "934f3416-bc2f-47f3-b492-77e517d4e572",
            "customerId": "835a59a7-3172-47b5-bdef-d9cc65f4d0e4",
            "customerName": "TEST_TEST Test Promotions 01",
            "customerDomainName": "kyletestpromos01.onmicrosoft.com",
            "customerCountry": "US",
            "invoiceNumber": "",
            "mpnId": "5357564",
            "resellerMpnId": "0",
            "orderId": "5f9d52bb1408",
            "orderDate": "2021-05-20T18:48:30.6168285Z",
            "productId": "CFQ7TTC0HL8W",
            "skuId": "0001",
            "availabilityId": "CFQ7TTC0K59S",
            "productName": "Power BI Premium Per User",
            "skuName": "Power BI Premium Per User",
            "productQualifiers": [],
            "chargeType": "new",
            "unitPrice": "16",
            "effectiveUnitPrice": "14.4",
            "unitType": "",
            "quantity": "50",
            "subtotal": "720",
            "taxTotal": "0",
            "totalForCustomer": "0",
            "currency": "USD",
            "publisherName": "Microsoft Corporation",
            "publisherId": "",
            "subscriptionDescription": "",
            "subscriptionId": "bbbb1b1b-cc2c-dd3d-ee4e-ffffff5f5f5f",
            "subscriptionStartDate": "2021-05-20T00:00:00Z",
            "subscriptionEndDate": "2022-05-19T00:00:00Z",
            "chargeStartDate": "2021-05-20T00:00:00Z",
            "chargeEndDate": "2021-06-19T00:00:00Z",
            "termAndBillingCycle": "One-Year commitment for monthly/yearly billing",
            "alternateId": "5f9d52bb1408",
            "referenceId": "28b535e0-68f4-40b5-84f7-8ed9241eb149",
            "priceAdjustmentDescription": "[\"Price for given billing period\",\"You are getting a discount due to a pre-determined override.\",\"You are getting a discount for being a partner.\",\"You are getting a price guarantee for your price.\",\"Price for given term\"]",
            "discountDetails": "",
            "pricingCurrency": "USD",
            "pcToBCExchangeRate": "1",
            "pcToBCExchangeRateDate": "2021-05-01T00:00:00",
            "billableQuantity": "50",
            "meterDescription": "",
            "billingFrequency": "Monthly",
            "reservationOrderId": "8fdebb4a-7110-496e-9570-623e4c992797",
            "invoiceLineItemType": "billing_line_items",
            "billingProvider": "one_time",
            "promotionId": "39NFJQT1X27N:0002:39NFJQT1Q5KL",
            "attributes/objectType": "OneTimeInvoiceLineItem",
            "attributes": {
                "objectType": "OneTimeInvoiceLineItem"
            }
        },
        {
            "partnerId": "934f3416-bc2f-47f3-b492-77e517d4e572",
            "customerId": "c139c4bf-2e8b-4ab5-8bed-d9f50dcca7a2",
            "customerName": "Test_Test_Office R2 Reduce Seats Validation",
            "customerDomainName": "testcustomerr2t2reduce.onmicrosoft.com",
            "customerCountry": "US",
            "invoiceNumber": "",
            "mpnId": "1234567",
            "resellerMpnId": 0,
            "orderId": "HJVtMZMkgQ2miuCiNv0RSr51zQDans0m1",
            "orderDate": "2019-02-04T17:59:52.9460102Z",
            "productId": "DZH318Z0BXWC",
            "skuId": "0002",
            "availabilityId": "DZH318Z0BP8B",
            "productName": "Test WAF-as-a-Service",
            "skuName": "Test WaaS - Medium Plan",
            "chargeType": "New",
            "unitPrice": 820,
            "effectiveUnitPrice": 820,
            "unitType": "",
            "quantity": 1,
            "subtotal": 820,
            "taxTotal": 0,
            "totalForCustomer": 0,
            "currency": "USD",
            "publisherName": "Test Networks, Inc.",
            "publisherId": "21223810",
            "subscriptionDescription": "",
            "subscriptionId": "cccc2c2c-dd3d-ee4e-ff5f-aaaaaa6a6a6a",
            "subscriptionStartDate": "2019-02-01T00:00:00Z",
            "subscriptionEndDate": "2020-01-31T00:00:00Z",
            "chargeStartDate": "2019-02-04T09:22:40.1767993-08:00",
            "chargeEndDate": "2019-03-03T09:22:40.1767993-08:00",
            "termAndBillingCycle": "1 Year Subscription",
            "alternateId": "123456ad566",
            "priceAdjustmentDescription": "[\"15.0% Partner earned credit for services managed\"]",
            "discountDetails": "",
            "pricingCurrency": "USD",
            "pcToBCExchangeRate": 1,
            "pcToBCExchangeRateDate": "2019-08-01T00:00:00Z",
            "billableQuantity": 3.1618,
            "meterDescription": "Bandwidth - Data Transfer In (GB) - Zone 2",
            "reservationOrderId": "883d475b-0000-1234-0000-8818752f1234",
            "attributes": {
                "objectType": "OneTimeInvoiceLineItem"
            }
        }
    ]
}
    ],
    "links": {
        "self": {
            "uri": "/invoices/unbilled/lineitems?provider=onetime&invoicelineitemtype=billinglineitems&currencycode=usd&period=previous&size=2000",
            "method": "GET",
            "headers": []
        },
        "next": {
            "uri": "/invoices/unbilled/lineitems?provider=onetime&invoicelineitemtype=billinglineitems&currencycode=usd&period=previous&size=2000&seekOperation=Next",
            "method": "GET",
            "headers": [
                {
                    "key": "MS-ContinuationToken",
                    "value": "AQAAAA=="
                }
            ]
        }
    },
    "attributes": {
        "objectType": "Collection"
    }
}

Exemplo de solicitação-resposta 2