API de reconciliação de faturas faturadas v2 (GA)
Aplica-se a: Partner Center (não disponí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 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 faturamento de parceiros - Microsoft Graph v1.0. Para acessar essa API, consulte os detalhes a seguir.
Você pode usar essa API somente para a nuvem pública/global do MS Graph agora. Ele ainda não está disponível para o Azure Government, Azure Alemanha ou Azure China 21Vianet.
Visão geral da API
Para recuperar dados de reconciliação de fatura de comércio novo cobrado de forma assíncrona, use dois pontos de extremidade 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 de comércio . A API retorna um status HTTP 202 e um cabeçalho de local contendo uma URL. Pesquise essa URL em intervalos regulares até receber um status de êxito com uma URL de manifesto.
Ponto de extremidade do status da operação
Para obter um status de sucesso, continue chamando essa API em um intervalo regular. 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 estiver concluída, você obterá um recurso de manifesto com uma pasta de armazenamento onde poderá baixar os dados de uso. A resposta divide os arquivos em partes menores para taxa de transferência otimizada e 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 faturas comerciais.
Sequência de ações do usuário
Para recuperar dados de reconciliação de fatura faturada, siga estas etapas:
Etapa 1: Enviar solicitação
Envie uma solicitação POST para o ponto de extremidade da API.
Obter itens de linha de reconciliação de fatura faturados
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 |
|---|---|---|---|
| attributeSet | Falso | String | Escolha "full" para todos os atributos ou "basic" 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 de API padrão neste artigo.
| Código | Descrição |
|---|---|
| 202 – Aceito | Seu pedido foi aceito. Para verificar o status da 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-sucedida" ou "falhou". Você obtém a 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 | Um ID exclusivo 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 de API padrão neste artigo, a API pode retornar o seguinte status HTTP:
| Código | Descrição |
|---|---|
| 410 – Desaparecido | O link de manifesto expira após um tempo definido. Para obter o link de 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. em execução: aguarde o tempo especificado no cabeçalho "Retry-After" e faça outra chamada para verificar o status. Os dados estão prontos. Recupere a carga do manifesto usando o URI especificado em resourceLocation. falhou: a operação falhou permanentemente. Reinicie-o. |
| createdDateTime | Verdadeiro | O momento em que o pedido foi feito. Obrigatória. |
| lastActionDateTime | Verdadeiro | A hora em que o status foi alterado pela última vez. Obrigatória. |
| resourceLocation | Falso | O URI para a carga de manifesto. Opcional. |
| error | 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. código: 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 onde 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 faturamento gera um novo valor. |
| partnerTenantId | ID do inquilino 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 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 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: 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 seus 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 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 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 cobrada do armazenamento de blobs do Azure
Obtenha o token de assinatura de acesso compartilhado (SAS) e o local de armazenamento de blob das propriedades "sasToken" e "rootDirectory" da resposta da API de carga útil 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 da API padrão
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 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 – Não existem dados disponíveis | O sistema não tem 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 "completo" ou "básico", consulte a tabela a seguir.
| 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 orientação sobre como usar a API, consulte o link a seguir que inclui código de exemplo em C#.
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de