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

Artigo
02/08/2025

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, reduzir a carga do servidor e melhorar os tempos de processamento de dados.

A nova API de reconciliação de faturas 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 faturada. 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.

Nota

A nova API não está hospedada no host da API do Partner Center. Em vez disso, você pode encontrá-lo no MS Graph em Usar a API do Microsoft Graph para exportar dados de faturamento do parceiro - Microsoft Graph v1.0. Para acessar essa API, consulte os seguintes detalhes.

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:

Registe a sua aplicação na página inicial do Microsoft Entra na secção Registos de aplicações.
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.

Usar o endpoint de reconciliação de fatura

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.

Usar o endpoint 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 uso. 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.

Diagrama que mostra as etapas para baixar dados de reconciliação.

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
Baixar itens de linha de reconciliação de faturas 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

Atributo	Necessário	Type	Description
attributeSet	False	String	Escolha "completo" para todos os atributos ou "básico" para um conjunto limitado. Se não for especificado, "full" é o valor padrão. Verifique a lista de atributos nesta seção. Opcional.
invoiceId	True	String	Um identificador exclusivo para cada fatura. Necessário.

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 status estão listados na seção Status de resposta padrão da API.

Código	Description
202 – Aceito	O seu pedido foi aceite. Para verificar o estado do seu pedido, consulte o URL fornecido no cabeçalho da localização.

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

Nome	Incluir em	Necessário	Type	Description
operationId	URI do pedido	True	String	Um identificador exclusivo para verificar o status da solicitação. Necessário.

Cabeçalho do pedido

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:

Código	Description
410 – Desaparecido	O link de manifesto expira após um tempo definido. Para obter o link do manifesto novamente, envie uma nova solicitação.

Carga útil de resposta

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

Atributo	Necessário	Description
id	True	Um identificador exclusivo para cada resposta Necessário.
status	True	Valores e ações: Obrigatório. notstarted: Aguarde a duração especificada no cabeçalho "Retry-After" e, em seguida, faça outra chamada para verificar o status. executando: Aguarde a duração especificada no cabeçalho "Retry-After" e, em seguida, faça outra chamada para verificar o status. bem-sucedido: os dados estão prontos. Recupere a carga útil do manifesto usando o URI especificado em resourceLocation. falhou: A operação falhou permanentemente. Reinicie-o.
createdDateTime	True	A hora em que o pedido foi feito. Necessário.
lastActionDateTime	True	A última vez que o status mudou. Necessário.
resourceLocation	False	O URI para a carga útil do manifesto. Opcional.
error	False	Detalhes sobre quaisquer erros, fornecidos no formato JSON. Opcional. Atributos incluídos: message: Descrição do erro. code: O tipo de erro.

Objeto de local de recurso

Atributo	Description
id	Um identificador exclusivo para o manifesto.
schemaVersion	Versão do esquema de manifesto.
dataFormat	Formato do ficheiro de dados de faturação. compressedJSON: Formato de dados em que cada blob é um arquivo compactado que contém dados no formato de linhas JSON. Para recuperar os dados de cada blob, descompacte-os.
createdDateTime	Data e hora em que o arquivo de manifesto foi criado.
eTag	Versão dos dados do manifesto. Um novo valor é gerado sempre que há uma alteração nas informações de faturamento.
partnerTenantId	ID do Microsoft Entra do locatário do parceiro.
rootDirectory	Diretório raiz do arquivo.
sasToken	Token SAS (assinatura de acesso compartilhado) que permite ler todos os arquivos no diretório.
Tipo de partição	Divide os dados em vários blobs com base no atributo partitionValue . O sistema divide partições que excedem o número suportado. Por padrão, os dados são particionados com base no número de itens de linha no arquivo. Evite fixar contagens de itens de linha ou tamanhos de arquivo, pois estes podem mudar.
blobContagem	Número total de ficheiros para este ID de inquilino parceiro.
blobs	Uma matriz JSON de objetos "blob" que contêm os detalhes do arquivo para a ID do locatário parceiro.
objeto blob	Um objeto que contém os seguintes detalhes: nome e partitionValue
nome	Nome do blob.
partitionValue	Partição que contém o arquivo. A partição grande é dividida em vários arquivos com base em certos critérios, como tamanho do arquivo ou número de registros, com cada arquivo contendo o mesmo "partitionValue".

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"

            }

        \]

    }

}

Descarregue os itens de linha de reconciliação da fatura a partir do armazenamento de blobs do Azure

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

Gorjeta

Certifique-se de verificar o nosso exemplo de código . Ele mostra como baixar e descompactar o arquivo de blob do Azure para seu banco de dados local.

Status de resposta padrão da API

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

Código	Description
400 – Mau Pedido	O pedido está em falta ou contém dados incorretos. Verifique o corpo da resposta para obter detalhes do erro.
401 – Não autorizado	A autenticação é necessária antes de fazer a primeira chamada. Autentique-se com o serviço de API do parceiro.
403 – Proibido	Você não tem a autorização necessária para fazer a solicitação.
404 – Não encontrado	Os recursos solicitados não estão disponíveis com os parâmetros de entrada fornecidos.
410 – Desaparecido	O link de manifesto não é mais válido ou ativo. Envie uma nova solicitação.
500 – Erro interno do servidor	A API ou suas dependências não podem atender à solicitação no momento. Tente novamente mais tarde.
5000 – dados não disponíveis	O sistema não tem dados para os parâmetros de entrada fornecidos.

Atributos do 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 "completo" ou "básico", consulte esta tabela. Para saber mais sobre esses atributos e seus significados, consulte Usar o arquivo de reconciliação.

Atributo	Total	Básica
Identificação do parceiro	sim	sim
ID do Cliente	sim	sim
CustomerName	sim	sim
CustomerDomainName	sim	não
País do Cliente	sim	não
Número da fatura	sim	sim
MpnId	sim	não
Tier2MpnId	sim	sim
OrderId	sim	sim
OrderDate	sim	sim
ProductId	sim	sim
SkuId	sim	sim
AvailabilityId	sim	sim
SkuName	sim	não
ProductName	sim	sim
ChargeType	sim	sim
UnitPrice	sim	sim
Quantidade	sim	não
Subtotal	sim	sim
TaxTotal	sim	sim
Total	sim	sim
Moeda	sim	sim
PreçoAjusteDescrição	sim	sim
Nome do Editor	sim	sim
PublisherId	sim	não
SubscriçãoDescrição	sim	não
SubscriptionId	sim	sim
ChargeStartDate	sim	sim
ChargeEndDate	sim	sim
TermAndBillingCycle	sim	sim
EffectiveUnitPrice	sim	sim
Tipo de Unidade	sim	não
AlternateId	sim	não
FaturávelQuantidade	sim	sim
FaturaçãoFrequência	sim	não
PricingCurrency	sim	sim
PCToBCExchangeRate	sim	sim
PCToBCExchangeRateDate	sim	não
MedidorDescrição	sim	não
ReservationOrderId	sim	sim
CreditReasonCode	sim	sim
AssinaturaStartDate	sim	sim
SubscriptionEndDate	sim	sim
ReferenceId	sim	sim
Qualificadores de Produto	sim	não
PromotionId	sim	sim
ProductCategory	sim	sim

Importante

Anote essas alterações ao mudar da API v1 para a v2.

Cada nome de atributo agora começa com uma letra maiúscula para manter a consistência com o arquivo e melhorar a legibilidade.

Obter o código de exemplo da API

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

exemplos de API para obter dados de reconciliação de faturamento do Partner Center.

Partilhar via

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

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

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

Saiba mais sobre os principais pontos de extremidade da API

Usar o endpoint de reconciliação de fatura

Usar o endpoint de status da operação

Rever o diagrama de sequência

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

Enviar uma solicitação POST

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

Pedido da API

Parâmetros de consultas

Corpo do pedido

Cabeçalhos do pedido

Resposta da API

Verificar o estado do pedido

Obter o status da operação

Pedido da API

Parâmetros de solicitação

Cabeçalho do pedido

Corpo do pedido

Estado da resposta

Carga útil de resposta

Objeto de local de recurso

Pedido da API

Resposta da API

Pedido da API

Resposta da API

Descarregue os itens de linha de reconciliação da fatura a partir do armazenamento de blobs do Azure

Status de resposta padrão da API

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

Obter o código de exemplo da API

Comentários

Recursos adicionais

Partilhar via

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

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

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

Saiba mais sobre os principais pontos de extremidade da API

Usar o endpoint de reconciliação de fatura

Usar o endpoint de status da operação

Rever o diagrama de sequência

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

Enviar uma solicitação POST

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

Pedido da API

Parâmetros de consultas

Corpo do pedido

Cabeçalhos do pedido

Resposta da API

Verificar o estado do pedido

Obter o status da operação

Pedido da API

Parâmetros de solicitação

Cabeçalho do pedido

Corpo do pedido

Estado da resposta

Carga útil de resposta

Objeto de local de recurso

Pedido da API

Resposta da API

Pedido da API

Resposta da API

Descarregue os itens de linha de reconciliação da fatura a partir do armazenamento de blobs do Azure

Status de resposta padrão da API

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

Obter o código de exemplo da API

Conteúdo relacionado

Comentários

Recursos adicionais