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

Aplica-se a: Partner Center (indisponível na nuvem soberana)

Nossa nova API assíncrona oferece uma maneira mais rápida e eficiente de acessar seus dados de cobrança e reconciliação 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.

A nova API de reconciliação de fatura faturada de comércio usa técnicas avançadas, como chave de manobrista e padrões assíncronos de solicitação-resposta . 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 faturada.

Nossa API usa técnicas otimizadas para aumentar sua eficiência, para que você possa obter resultados mais rápidos com menos esforço. Adote essa API para simplificar o acesso aos dados e melhorar sua eficiência geral.

Visão geral da API

Para ajudar você a recuperar itens de linha de reconciliação de fatura de novo comércio faturados de forma assíncrona, oferecemos dois endpoints principais de API. Aqui está um guia simplificado para você começar:

Ponto de extremidade de reconciliação de fatura faturada

Primeiro, use essa API para buscar novos itens de linha de reconciliação de fatura faturada pelo comércio . Ao fazer uma solicitação, você recebe um status HTTP 202 e um cabeçalho de localização com uma URL. Sonde essa URL regularmente até obter um status de êxito e uma URL de manifesto.

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. Depois que a operação for concluída, você receberá um recurso de manifesto com um link de pasta de armazenamento para baixar os dados de uso. A resposta segmenta os arquivos para melhorar a taxa de transferência e permitir o paralelismo de E/S.

Seguindo estas etapas, você pode gerenciar com eficiência seu processo de reconciliação de faturas.

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.

Sequência de ação do usuário

Para recuperar dados de reconciliação de faturas faturadas, siga estas etapas:

Etapa 1: enviar solicitação

Envie uma solicitação POST para o endpoint da API.

Obter itens de linha de reconciliação de fatura faturada

Solicitação de 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 consulta

N/D

Corpo da solicitação

Cabeçalhos da solicitação

Solicite cabeçalhos para a API usando as etapas listadas em Práticas recomendadas para usar o Microsoft Graph. Seguindo essas diretrizes, você garante confiabilidade e suporte para sua aplicação. 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 são listados na seção Status de resposta da API padrão.

Etapa 2: verificar o status da solicitação

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

Obter status da operação

Recupera o status de uma solicitação.

Solicitação de API

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

Parâmetros da solicitação

Cabeçalho da solicitação

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

Corpo da solicitação

N/D

Status 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:

Payload de resposta

A carga de resposta da API inclui os seguintes atributos:

Objeto de localização do recurso

Solicitação de 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 sendo processados.

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"  
}

Solicitação de API

(10 segundos após a solicitação 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 para "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": "0e195b37-4574-4539-bc42-0e539b9684c0",

        "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"

            }

        \]

    }

}

Etapa 3: Baixar itens de linha de reconciliação de fatura faturada do armazenamento de blobs do Azure

Primeiro, você precisa obter o token SAS (assinatura de acesso compartilhado) e o local de armazenamento de blobs. Você pode encontrar esses detalhes nas propriedades "sasToken" e "rootDirectory" da resposta da API de carga útil do manifesto. Em seguida, para baixar e descompactar o arquivo de blob, use o SDK/ferramenta do Armazenamento do Azure. Está no formato JSONLines .

Status de resposta padrão da API

Você pode obter estes status HTTP da resposta da API:

Atributos de item de linha de reconciliação de fatura faturada

Para comparar os atributos retornados pela API de reconciliação de fatura faturada para os conjuntos de atributos "completos" ou "básicos", consulte a tabela a seguir. Para saber mais sobre esses atributos, consulte Usando o arquivo de reconhecimento.

Código de exemplo

Para usar essa API, consulte o link a seguir, que inclui o código de exemplo C#.

Partner-Center-Billing-Recon-Samples: exemplos de API para obter dados de reconhecimento de cobrança do Partner Center (github.com).