API de reconciliação de fatura faturada v2 (GA)

Aplica-se a: Partner Center (indisponível no Azure Government ou no Azure China 21Vianet)

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. 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 valet key fornece acesso seguro e limitado aos seus dados de faturamento. 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. Esses pedidos e respostas assíncronos usam recursos de forma eficiente, reduzem a carga do servidor e minimizam tempos limite e falhas comuns à recuperação de dados síncrona.

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 faturada 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 melhores tempos de processamento, simplificando a integração de dados de faturamento e reconciliação em sistemas e fluxos de trabalho existentes.

Benefícios

1. 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.

2. Melhorias de segurança

   O padrão de chave valet, implementado através de tokens SAS, fornece:

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

3. Vantagens arquitetônicas

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

   • Aceita o seu pedido.
   • Executa 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 acessar dados de cobrança e reconciliação por meio 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 a sua aplicação aceda aos dados de faturação do parceiro, clique nesta ligação e familiarize-se com as noções básicas de autenticação e autorização de para o 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 de permissões da API, selecione Adicionar uma permissão e escolha o âmbito de 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 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. Siga este guia simplificado para começar rapidamente.

Utilize o endpoint de reconciliação de fatura emitida

Primeiro, use essa API para buscar novos itens de linha de reconciliação de fatura faturados pelo 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.

Utilize o ponto final 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 estiver concluída, receberá um recurso de manifesto com um link para uma pasta de armazenamento para descarregar os dados de utilizaçã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 comercial.

Siga a sequência de ações do usuário para recuperar dados de reconciliação de fatura faturada

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

• Enviar uma solicitação POST
• Verificar o status da solicitação
• Descarregar itens de linha de reconciliação 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 faturados

Obtenha os itens de linha de reconciliação da fatura emitida.

Pedido da API

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

Accept: application/json

Content-Type: application/json

{

"invoiceId": "G016907411",

"attributeSet": "basic"

}

Parâmetros de consultas

N/A

Corpo do pedido

Cabeçalhos 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.

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 estados estão listados na secção Estados 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 do pedido

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 localização 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 estado "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 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 nas propriedades sasToken, rootDirectorye blobs da resposta de API do manifesto de carga útil.

Para continuar, siga estes passos:

1. Baixe o ficheiro blob utilizando o SDK ou ferramenta de Armazenamento 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 básicos e completos de reconciliação de faturas

Para comparar os atributos retornados pela API de reconciliação de fatura faturada para os conjuntos de atributos "completo" ou "básico", consulte esta tabela. Para saber mais sobre esses atributos e seus significados, consulte 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 de faturamento do Partner Center.

Conteúdo relacionado

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