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.
Observação
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 cobrança de parceiros – Microsoft Graph v1.0. Para acessar essa API, consulte os detalhes a seguir.
Importante
Para conceder ao seu aplicativo a permissão necessária para acessar os dados de cobrança do parceiro, você precisa seguir este link e saber mais sobre os conceitos básicos de autenticação e autorização do Microsoft Graph.
Normalmente, você pode usar o portal do Azure ou o Centro de administração do Entra para atribuir a permissão necessária: "PartnerBilling.Read.All". Aqui estão as etapas para fazer isso:
- Registre seu aplicativo na home page do Microsoft Entra na seção Registros de aplicativo.
- Atribua permissão ao seu aplicativo na página Aplicativo Microsoft Entra na seção Permissões de API. Selecione "Adicionar uma permissão" e escolha o escopo "PartnerBilling.Read.All".
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
Atributo | Obrigatório | Type | Descrição |
---|---|---|---|
conjunto de atributos | Falso | String | Escolha "completo" para todos os atributos ou "básico" para um conjunto limitado. O valor padrão é "full". (Veja a lista de atributos neste artigo). Opcional. |
invoiceId | True | String | Um identificador exclusivo para cada fatura. Obrigatória. |
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.
Código | Descrição |
---|---|
202 – Aceito | Seu pedido foi aceito. Para verificar o status da sua solicitação, consulte a URL fornecida no cabeçalho do local. |
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
Nome | Incluir em | Obrigatório | Type | Descrição |
---|---|---|---|---|
operationId | URI da solicitação | True | String | Uma ID exclusiva para verificar o status da solicitação. Obrigatória. |
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:
Código | Descrição |
---|---|
410 - Desaparecido | O link do manifesto expira após um tempo definido. Para obter o link do manifesto novamente, envie uma nova solicitação. |
Payload de resposta
A carga de resposta da API inclui os seguintes atributos:
Atributo | Obrigatório | Descrição |
---|---|---|
id | Verdadeiro | Um ID exclusivo para cada resposta Obrigatória. |
status | Verdadeiro | Valores e ações: obrigatório. notstarted: aguarde o tempo especificado no cabeçalho "Retry-After" e faça outra chamada para verificar o status. running: aguarde o tempo especificado no cabeçalho "Retry-After" e faça outra chamada para verificar o status. succeeded: os dados estão prontos. Recupere a carga do manifesto usando o URI especificado em resourceLocation. failed: a operação falhou permanentemente. Reinicie-o. |
createdDateTime | Verdadeiro | A hora em que a solicitação foi feita. Obrigatória. |
lastActionDateTime | Verdadeiro | A hora em que o status foi alterado pela última vez. Obrigatória. |
resourceLocation | Falso | O URI para a carga do manifesto. Opcional. |
erro | Falso | Se a operação falhar, os detalhes do erro serão fornecidos no formato JSON. Opcional. Os seguintes atributos estão incluídos: message: Uma descrição detalhada do erro. code: o tipo de erro que ocorreu. |
Objeto de localização do recurso
Atributo | Descrição |
---|---|
ID | Um identificador exclusivo para o manifesto. |
schemaVersion | Versão do esquema de manifesto. |
dataFormat | Formato do arquivo de dados de faturamento. 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. Uma alteração nas informações de cobrança gera um novo valor. |
partnerTenantId | ID do locatário do parceiro. |
diretório raiz | Diretório raiz do arquivo. |
sasToken | Token SAS (assinatura de acesso compartilhado) que permite ler todos os arquivos no diretório. |
partitionType | Divide os dados em vários blobs com base no atributo partitionValue . O sistema divide as 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. Não defina um número fixo de itens de linha ou tamanho de arquivo no código, pois esses valores podem ser alterados. |
blobCount | Número total de arquivos para essa ID de locatário de parceiro. |
blobs | Uma matriz JSON de objetos "blob" que contêm os detalhes do arquivo para a ID do locatário do parceiro. |
objeto blob | Um objeto que contém os seguintes detalhes: name: Nome do blob. partitionValue: Partição que contém o arquivo. A partição grande é dividida em vários arquivos, com cada arquivo contendo o mesmo "partitionValue". |
name | O nome do blob. |
partitionValue | Partição que contém o arquivo. A partição grande é dividida em vários arquivos, com cada arquivo contendo o mesmo "partitionValue". |
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 .
Dica
Confira nosso código de exemplo para baixar e descompactar o arquivo de blob do Azure em seu banco de dados local.
Status de resposta padrão da API
Você pode obter esses status HTTP da resposta da API:
Código | Descrição |
---|---|
400 – Solicitação incorreta | A solicitação está ausente ou contém dados incorretos. Verifique o corpo da resposta para obter detalhes do erro. |
401 - Não autorizado | O chamador não é autenticado e você deve se autenticar com o serviço de API do parceiro antes de fazer a primeira chamada. |
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 de servidor interno | A API ou uma de suas dependências não pode atender à solicitação no momento. Tente novamente depois. |
5000 – Dados não disponíveis | O sistema não possui dados para os parâmetros de entrada fornecidos. |
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.
Atributo | Completo | Basic |
---|---|---|
PartnerId | sim | sim |
CustomerId | sim | sim |
CustomerName | sim | sim |
CustomerDomainName | sim | não |
CustomerCountry | sim | não |
InvoiceNumber | 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 |
PriceAdjustmentDescription | sim | sim |
PublisherName | sim | sim |
PublisherId | sim | não |
SubscriptionDescription | sim | não |
SubscriptionId | sim | sim |
ChargeStartDate | sim | sim |
ChargeEndDate | sim | sim |
TermAndBillingCycle | sim | sim |
EffectiveUnitPrice | sim | sim |
UnitType | sim | não |
AlternateId | sim | não |
BillableQuantity | sim | sim |
BillingFrequency | sim | não |
PricingCurrency | sim | sim |
PCToBCExchangeRate | sim | sim |
PCToBCExchangeRateDate | sim | não |
MeterDescription | sim | não |
ReservationOrderId | sim | sim |
CreditReasonCode | sim | sim |
SubscriptionStartDate | sim | sim |
SubscriptionEndDate | sim | sim |
ReferenceId | sim | sim |
ProductQualifiers | sim | não |
PromotionId | sim | sim |
ProductCategory | sim | sim |
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#.