Obter itens de linha de reconciliação não faturados da fatura de forma assíncrona API v2 (GA)

Aplica-se a: Partner Center (indisponível na China 21Vianet e para dados de comércio legados)

Você pode usar essa API para obter uma coleção de detalhes para itens de linha de fatura não faturados (também conhecidos como itens de linha de faturamento abertos).

Nossa nova API assíncrona oferece uma maneira mais rápida e eficiente de acessar seus dados de cobrança e reconciliação não faturados por meio de blobs do Azure. Em vez de manter uma conexão aberta por horas ou processar lotes de 2.000 itens de linha, agora você pode simplificar seu fluxo de trabalho, reduzir a carga do servidor e melhorar os tempos de processamento de dados.

A nova API de reconciliação de faturas não faturadas do comércio usa técnicas avançadas como chave de manobrista e padrões assíncronos de solicitação-resposta . O padrão de chave de manobrista suporta acesso seguro a recursos sem compartilhar credenciais, enquanto o padrão assíncrono solicitação-resposta permite uma comunicação eficiente entre sistemas.

Essa API fornece um token de assinatura de acesso compartilhado (SAS) que você pode usar para acessar todos os atributos ou um subconjunto dos dados de reconciliação de fatura não faturados. Esse token aumenta a segurança concedendo acesso por tempo limitado e oferece flexibilidade no gerenciamento de permissões de acesso a dados.

Ao adotar nossas APIs otimizadas, você pode obter resultados mais rápidos com menos esforço, simplificar o acesso aos dados e melhorar a eficiência geral. Adote essas ferramentas para simplificar seu fluxo de trabalho e gerenciar permissões de forma mais eficaz.

Entenda a arquitetura

A nova API assíncrona oferece avanços significativos na forma como lidamos com o acesso a dados de faturamento e reconciliação não faturados. Essa abordagem resolve desafios associados aos métodos síncronos tradicionais, como a manutenção de conexões de longa duração e o processamento de grandes lotes de dados. Aqui estão os principais benefícios e mecanismos desta API:

Componentes-chave

Acesso seguro com padrão de chave de manobrista

O padrão de chave de manobrista fornece acesso seguro e limitado aos seus dados de faturamento não faturados. Semelhante a como uma chave de manobrista permite que alguém dirija seu carro sem acessar o porta-malas, esse padrão garante um controle de acesso granular. Em vez de compartilhar credenciais, um token de assinatura de acesso compartilhado (SAS) concede acesso limitado e limitado ao tempo a recursos específicos. Esse padrão reduz o risco de acesso não autorizado, configurando tempos de expiração precisos e permissões de acesso.

Eficiência aprimorada por meio de um padrão assíncrono de solicitação-resposta

Pense nisso como pedir em um restaurante movimentado. Em vez de esperar no balcão, você recebe uma campainha e pode fazer outras coisas enquanto seu pedido é preparado. Quando os dados estiverem prontos, o sistema notifica-o.

A natureza assíncrona da API significa que você faz uma solicitação e o sistema a processa em segundo plano. Essa solicitação-resposta assíncrona usa recursos de forma eficiente, reduz a carga do servidor e minimiza tempos limite e falhas comuns à recuperação síncrona de dados.

Flexibilidade nas permissões de acesso a dados

Os tokens SAS oferecem flexibilidade no gerenciamento de permissões de acesso a dados. Você pode gerar tokens que concedem acesso a todos os atributos dos dados de reconciliação de fatura não faturados ou limitam o acesso a subconjuntos específicos. Essa granularidade permite que as organizações adaptem o acesso aos dados de acordo com políticas internas e requisitos regulamentares, aprimorando a segurança e a conformidade.

Fluxo de trabalho simplificado e tempos de processamento de dados melhorados

O padrão assíncrono solicitação-resposta simplifica o processamento de dados permitindo acesso dinâmico em vez de lotes fixos de 2.000 itens de linha. Essa abordagem leva a resultados mais rápidos e tempos de processamento aprimorados, simplificando a integração de dados de faturamento e reconciliação não faturados em sistemas e fluxos de trabalho existentes.

Benefícios

• Benefícios de desempenho

  Em vez de manter conexões de longa duração e processar lotes fixos, o novo sistema permite:

  • Faça um pedido inicial rápido.
  • Receba um token de acesso seguro.
  • Processe dados ao seu próprio ritmo.
  • Acesse exatamente o que você precisa quando precisar.

• Melhorias de segurança

  O padrão de chave de manobrista, implementado por meio de tokens SAS, fornece:

  • Acesso limitado no tempo.
  • Permissões restritas.
  • Eliminação do compartilhamento ou armazenamento de credenciais permanentes.
  • Controle de acesso refinado.

• Vantagens arquitetónicas

  O padrão assíncrono solicitação-resposta age como um assistente pessoal que:

  • Aceita o seu pedido.
  • Manipula a tarefa em segundo plano.
  • Notifica quando tudo estiver pronto.

Adote APIs otimizadas para melhorar o desempenho

A adoção dessas APIs otimizadas simplifica o fluxo de trabalho e melhora o desempenho geral no gerenciamento de dados. Usando controle de acesso seguro e mecanismos de recuperação eficientes, você obtém melhores resultados com menos esforço, levando a uma maior eficiência operacional.

Em conclusão, a nova API assíncrona para aceder a dados de faturação e reconciliação não faturados através de blobs do Azure é uma ferramenta poderosa. Ele oferece acesso seguro e eficiente a dados financeiros, simplificando fluxos de trabalho, reduzindo cargas de servidor e melhorando os tempos de processamento, tudo com alta segurança e conformidade.

Permitir que seu aplicativo acesse com segurança os dados de faturamento do parceiro

Para permitir que seu aplicativo acesse os dados de cobrança do parceiro, siga este link e familiarize-se com as noções básicas de autenticação e autorização do Microsoft Graph. Esta etapa é crucial, pois garante que seu aplicativo possa acessar com segurança os dados necessários.

Registre seu aplicativo e atribua a permissão PartnerBilling.Read.All

Você pode atribuir a permissão "PartnerBilling.Read.All" usando o portal do Azure ou o centro de administração do Microsoft Entra. Ao concluir estas etapas, você ajuda a garantir que seu aplicativo tenha o acesso necessário aos dados de faturamento do parceiro. Saiba como:

1. Registe a sua aplicação na página inicial do Microsoft Entra na secção Registos de aplicações.
2. Conceda a permissão necessária acessando a página do Microsoft Entra App. Na seção Permissões da API, selecione Adicionar uma permissão e escolha o escopo PartnerBilling.Read.All .

Saiba mais sobre os principais pontos de extremidade da API

Para ajudá-lo a recuperar novos itens de linha de reconciliação de fatura comercial não faturados de forma assíncrona, oferecemos dois pontos de extremidade de API principais. Estes terminais ajudam-no a gerir eficientemente o seu processo de reconciliação de faturas não faturadas. Siga este guia simplificado para começar rapidamente.

Usar o ponto de extremidade de reconciliação de fatura não faturada

Primeiro, use essa API para buscar novos itens de linha de reconciliação de fatura não faturados do comércio. Ao fazer uma solicitação, você recebe um status HTTP 202 e um cabeçalho de local com uma URL. Analise este URL regularmente até obter um status de sucesso e um URL de manifesto.

Usar o ponto de extremidade de status da operação

Em seguida, continue verificando o status da operação chamando essa API em intervalos regulares. Se os dados não estiverem prontos, a resposta incluirá um cabeçalho Retry-After indicando quanto tempo esperar antes de tentar novamente. Quando a operação for concluída, você receberá um recurso de manifesto com um link de pasta de armazenamento para baixar os dados de reconciliação. A resposta segmenta os arquivos para melhorar a taxa de transferência e permitir paralelismo de E/S.

Rever o diagrama de sequência

Aqui está um diagrama de sequência que mostra as etapas para baixar novos dados de reconciliação de fatura não faturada do comércio.

Siga a sequência de ação do usuário para recuperar dados de reconciliação de faturas não faturadas

Aqui está a sequência de ação do usuário para recuperar dados de reconciliação de fatura não faturada:

1. Enviar uma solicitação POST
2. Verificar o estado do pedido
3. Baixar itens de linha de reconciliação não faturados do armazenamento de blobs do Azure

Enviar uma solicitação POST

Envie uma solicitação POST para o ponto de extremidade da API.

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

Obtenha os itens de linha de reconciliação de fatura não faturados.

Pedido da API

POST https://graph.microsoft.com/v1.0/reports/partners/billing/reconciliation/unbilled/export

Accept: application/json

Content-Type: application/json

{
"attributeSet": "full",
"billingPeriod": "current",
"currencyCode": "USD"
}

Parâmetros de consultas

N/A

Corpo de solicitação

Cabeçalhos da requisição

Solicite cabeçalhos para a API usando as etapas listadas em Práticas recomendadas para usar o Microsoft Graph. Ao seguir essas diretrizes, você garante confiabilidade e suporte para seu aplicativo. A sua atenção aos detalhes nesta etapa é crucial para uma integração perfeita e um desempenho ideal.

Resposta da API

HTTP/1.1 202 Accepted  
Location: <https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14>

A API geralmente responde com um status HTTP 202. Você também pode encontrar outros status, dependendo de suas solicitações. Esses status estão listados na seção Status de resposta padrão da API.

Verificar o estado do pedido

Para acompanhar o status de uma solicitação, certifique-se de receber uma resposta HTTP 200, que é um código de status padrão indicando "bem-sucedido" ou "reprovado". Se for bem-sucedido, você encontrará a URL do manifesto no atributo "resourceLocation". Este atributo fornece um ponto de extremidade para acessar as informações necessárias.

Obter o status da operação

Recupera o status de uma solicitação.

Pedido da API

GET <https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14>

Parâmetros de solicitação

Cabeçalho do pedido

Solicite cabeçalhos para a API usando as etapas listadas em Práticas recomendadas para usar o Microsoft Graph. Ao seguir essas diretrizes, você garante confiabilidade e suporte para seu aplicativo. A sua atenção aos detalhes nesta etapa é crucial para uma integração perfeita e um desempenho ideal.

Corpo de solicitação

N/A.

Estado da resposta

Além dos status HTTP padrão listados em Status de resposta da API padrão, a API também pode retornar o seguinte status HTTP:

Carga útil de resposta

A carga útil de resposta da API inclui os seguintes atributos:

Objeto de local de recurso

Pedido da API

GET <https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14>

Resposta da API

A resposta recomenda aguardar 10 segundos antes de tentar novamente quando os dados ainda estiverem em processamento.

HTTP/1.1 200 OK  
Retry-After: 10  
{  
"id": "9ab9cb54-d07f-4f52-9ea6-a09d7de52c14",  
"createdDateTime": "2022-06-1T10-01-03.4Z",  
"lastActionDateTime": "2022-06-1T10-01-05Z",  
"status": "running"  
}

Pedido da API

(10 segundos após o pedido anterior...)

GET <https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14>

Resposta da API

A API retorna o status "bem-sucedido" e o URI de "resourceLocation".

HTTP/1.1 200 OK  
Content-Type: application/json  
{

    "@odata.context": "https://graph.microsoft.com/v1.0/\$metadata#reports/partners/billing/operations/\$entity",

    "@odata.type": "#microsoft.graph.partners.billing.exportSuccessOperation",

    "id": "f2170b13-6a8e-47d6-b481-6988490dc0cb",

    "createdDateTime": "2023-12-05T21:17:29Z",

    "lastActionDateTime": "2023-12-05T21:18:00.8897902Z",

    "status": "succeeded",

    "resourceLocation": {

        "id": "44e8500b-ab92-490e-8ac3-90500a1d3427",

        "createdDateTime": "2023-11-06T19:58:47.513Z",

        "schemaVersion": "2",

        "dataFormat": "compressedJSON",

        "partitionType": "default",

        "eTag": "RwDrn7fbiTXy6UULE",

        "partnerTenantId": "aaaabbbb-0000-cccc-1111-dddd2222eeee",

        "rootDirectory": "https://adlsreconbuprodeastus201.blob.core.windows.net/path_id",

        "sasToken": "{token}",

        "blobCount": 1,

        "blobs": \[

            {

                "name": "part-00123-5a93fa5d-749f-48bc-a372-9b021d93c3fa.c000.json.gz",

                "partitionValue": "default"

            }

        \]

    }

}

Baixar itens de linha de reconciliação não faturados do armazenamento de blobs do Azure

Primeiro, você precisa obter o token de assinatura de acesso compartilhado (SAS) e o local de armazenamento de blob (combine o diretório raiz e o nome do blob). Encontre esses detalhes no sasToken, rootDirectorye blobs propriedades da resposta da API de carga útil do manifesto.

Para continuar, siga estes passos:

1. Baixe o arquivo de blob usando o SDK/ferramenta de Armazenamento do Azure.
2. Descompacte o arquivo, que está no formato JSONLines .

Status de resposta padrão da API

Você pode obter os seguintes status HTTP da resposta da API:

Compare atributos de reconciliação básicos e completos não faturados

Para comparar os atributos retornados pela API de reconciliação de fatura não faturada para os conjuntos de atributos "completo" ou "básico", consulte esta tabela. Para saber mais sobre esses atributos e seus significados, veja como usar o arquivo de reconciliação.

Código de exemplo

Se precisar de ajuda com a migração para essa API, consulte o link que inclui o código de exemplo em C#.

Exemplos de API para obter dados de reconciliação não faturados do Partner Center.

Conteúdo relacionado

• SDK/ferramenta de armazenamento do Azure
• Usar a API do Microsoft Graph para exportar dados de faturamento de parceiros