Obter os itens de linha de consumo comercial cobrados na fatura

Artigo
04/26/2024

Observação

Você ainda pode usar essa API após 30 de setembro de 2024 para seus novos dados de uso de comércio gerados antes de setembro de 2022. Escolha a versão correta com base nestes detalhes:

Para acessar os itens de linha de uso nominal diário para faturas de setembro de 2022 a setembro de 2024, use essa API até 30 de setembro de 2024, a menos que você já tenha mudado para a API v2 GA.
Para períodos de faturamento anteriores a setembro de 2022, obtenha itens de linha de uso nominal diário somente com esta API.
Para obter itens de linha de uso com classificação diária para faturas a partir de setembro de 2022, use apenas a API v2 GA.

Siga este link para se preparar para as novas APIs:

API v2 (GA) de reconciliação de uso nominal diária cobrada e não faturada

Você pode usar os seguintes métodos para obter uma coleção de detalhes para itens de linha de fatura de consumo comercial (também conhecidos como itens de linha de uso diário nominal fechados) para uma fatura especificada.

Importante

Os dados de uso nominal diário não incluem os encargos para estes produtos:

Reserva do Azure
Plano de economia do Azure
Office
Dynamics
Microsoft Power Apps
Software perpétuo
Assinatura de software
Produto SaaS de terceiros

Pré-requisitos

Credenciais, conforme descrito em Autenticação do Partner Center. Esse cenário oferece suporte à autenticação com credenciais autônomas de Aplicativo e Aplicativo+Usuário.
O ID da fatura para obter os itens de linha.

C#

Para obter os itens de linha comercial para a fatura especificada, você deve recuperar o objeto de 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 de fatura. O objeto invoice contém todas as informações da fatura especificada.

O Provedor identifica a origem das informações detalhadas cobradas (por exemplo, uma única vez). O InvoiceLineItemType especifica o tipo (por exemplo, UsageLineItem).

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

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

Passe 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, conforme mostrado no exemplo a seguir.

// IAggregatePartner partnerOperations;
// string invoiceId;
// string curencyCode;
// 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(invoiceId).By("onetime", "usagelineitems", curencyCode, 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 DailyRatedUsageLineItem
        if (item is DailyRatedUsageLineItem)
        {
            Type t = typeof(DailyRatedUsageLineItem);
            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(invoiceId).By("onetime", "usagelineitems", curencyCode, period, pageMaxSizeReconLineItems).Seek(seekBasedResourceCollection.ContinuationToken, SeekOperation.Next);
        }
    }
}

Veja um exemplo:

Exemplo: Aplicativo de teste de console
Projeto: Exemplos de SDK do Partner Center
Classe: GetBilledConsumptionReconLineItemsPaging.cs

Solicitação REST

Sintaxe da solicitação

Use a primeira sintaxe para retornar uma lista completa de cada item de linha para a fatura especificada. Para grandes faturas, use a segunda sintaxe com um tamanho especificado e o deslocamento de base 0 para retornar uma lista paginada de itens de linha. Use a terceira sintaxe para obter a próxima página de itens de linha recon usando seekOperation = "Next".

Método	URI da solicitação
GET	{baseURL}/v1/invoices/{invoice-id}/lineitems?provider=onetime&invoicelineitemtype=usagelineitems¤cycode={currencycode} HTTP/1.1
GET	{baseURL}/v1/invoices/{invoice-id}/lineitems?provider=onetime&invoicelineitemtype=usagelineitems¤cycode={currencycode}&size={size} HTTP/1.1
GET	{baseURL}/v1/invoices/{invoice-id}/lineitems?provider=onetime&invoicelineitemtype=usagelineitems¤cycode={currencycode}&size={size}&seekOperation=Next

Parâmetros do URI

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

Nome	Digitar	Obrigatória	Descrição
id da nota fiscal	string	Yes	Uma cadeia de caracteres que identifica a fatura.
provedor	string	Yes	O provedor: "OneTime".
invoice-line-item-type	string	Yes	O tipo de detalhe da fatura: "UsageLineItems".
currencyCode	string	Yes	O código de moeda para os itens de linha cobrados.
period	string	Yes	O período para reconhecimento faturado. Exemplo: atual, anterior.
tamanho	número	Não	O número máximo de itens a serem devolvidos. O tamanho padrão é 2000
seekOperation	string	Não	Defina seekOperation=Next para obter a próxima página de itens de linha recon.

Cabeçalhos da solicitação

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

Corpo da solicitação

Nenhum.

Resposta REST

Se for bem-sucedida, a resposta conterá a coleção de detalhes do item de linha.

Para o item de linha ChargeType, o valor Purchase é mapeado para New. O valor Reembolso é mapeado para Cancelar.

Códigos de êxito e de 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 mais parâmetros. Para obter a lista completa, confira Códigos de erro REST do Partner Center.

Exemplos de REST

Exemplo de solicitação-resposta 1

Os detalhes para este exemplo de solicitação e resposta REST são os seguintes:

Provedor: OneTime
InvoiceLineItemType: UsageLineItems
Período: Anterior

Exemplo de solicitação 1

GET https://api.partnercenter.microsoft.com/v1/invoices/T000001234/lineitems?provider=onetime&invoicelineitemtype=usagelineitems&currencycode=usd&period=previous&size=2000 HTTP/1.1
Authorization: Bearer <token>
Accept: application/json
MS-RequestId: 1234ecb8-37af-45f4-a1a1-358de3ca2b9e
MS-CorrelationId: 5e612512-4345-4bb0-866e-47aeda031234
X-Locale: en-US
MS-PartnerCenter-Application: Partner Center .NET SDK Samples
Host: api.partnercenter.microsoft.com