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

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

Nossa API assíncrona oferece uma maneira mais rápida e gerenciável de acessar dados de cobrança e reconciliação por meio de blobs do Azure. Com essa API, você não precisa manter uma conexão aberta por horas ou percorrer os lotes de 2.000 itens de linha por vez.

Otimizamos nossa nova API de reconciliação de faturas faturadas de comércio usando 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.

Visão geral da API

Para recuperar dados de reconciliação de faturas de novos comerciais faturados de forma assíncrona, use dois endpoints de API. Veja o processo:

Ponto de extremidade de reconciliação de fatura faturada

Use essa API para recuperar novos itens de linha de reconciliação de fatura faturada pelo novo comércio . A API retorna um status HTTP 202 e um cabeçalho de localização contendo uma URL. Sonde essa URL em intervalos regulares até receber um status de êxito com uma URL de manifesto.

Ponto de extremidade de status da operação

Para obter um status de sucesso, continue chamando essa API em intervalos regulares. Se os dados não estiverem prontos, a resposta da API incluirá um cabeçalho Retry-After para informar quanto tempo esperar antes de tentar novamente. Quando a operação for concluída, você obterá um recurso de manifesto com uma pasta de armazenamento na qual poderá baixar os dados de uso. A resposta divide os arquivos em partes menores para otimizar a taxa de transferência e o paralelismo de E/S.

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.

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. Outros status possíveis, com base em suas solicitações, estão listados em Status de resposta da API padrão neste artigo.

Etapa 2: verificar o status da solicitação

Para verificar o status de uma solicitação, aguarde uma resposta HTTP 200 com um status de "bem-sucedido" ou "falha". Você receberá o URL do manifesto no atributo "resourceLocation" se a solicitação for bem-sucedida.

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.

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 neste artigo, a API 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 dados de reconciliação de fatura faturada do armazenamento de blobs do Azure

Obtenha o token SAS (assinatura de acesso compartilhado) e o local de armazenamento de blobs das propriedades "sasToken" e "rootDirectory" da resposta da API de conteúdo do manifesto. SDK/ferramenta de Armazenamento do Azure para baixar e descompactar o arquivo de blob. Está no formato JSONLines .

Status de resposta padrão da API

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

Atributos de dados 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 obter diretrizes sobre como usar a API, consulte o link a seguir que inclui o código de exemplo em C#.

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