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 de cada vez.
Otimizamos nossa nova API de reconciliação de faturas faturadas no 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.
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.
Você pode usar essa API somente para a nuvem pública/global do MS Graph agora. Ainda não está disponível para o Azure Government, Azure Germany ou Azure China 21Vianet.
Descrição Geral da API
Para recuperar novos dados de reconciliação de fatura comercial faturados de forma assíncrona, use dois pontos de extremidade de API. Segue-se o processo:
Ponto de extremidade de reconciliação de fatura faturada
Use esta API para recuperar novos itens de linha de reconciliação de fatura faturados no comércio . A API retorna um status HTTP 202 e um cabeçalho de local contendo uma URL. Sonde este URL em intervalos regulares até receber um status de êxito com um 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 fatura comercial.
Sequência de ação do usuário
Para recuperar dados de reconciliação de fatura faturada, siga estas etapas:
Passo 1: Submeter pedido
Envie uma solicitação POST para o ponto de extremidade da API.
Obter itens de linha de reconciliação de fatura faturados
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. O valor padrão é "full". (Veja a lista de atributos neste artigo). Opcional. |
| invoiceId | True | String | Um identificador exclusivo para cada fatura. Obrigatório. |
Cabeçalhos do pedido
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 | 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. |
Etapa 2: Verificar o status da solicitação
Para verificar o status de uma solicitação, aguarde uma resposta HTTP 200 com o status "bem-sucedido" ou "falhou". Você obtém a URL do manifesto no atributo "resourceLocation" se a solicitação for bem-sucedida.
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 ID exclusivo para verificar o status da solicitação. Obrigatório. |
Cabeçalho do pedido
Solicite cabeçalhos para a API usando as etapas listadas em Práticas recomendadas para usar o Microsoft Graph.
Corpo do pedido
N/A.
Estado 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 | 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 | Descrição |
|---|---|---|
| id | True | Um ID exclusivo para cada resposta Obrigatório. |
| status | True | Valores e ações: Obrigatório. notstarted: aguarde o tempo especificado no cabeçalho "Retry-After" e, em seguida, faça outra chamada para verificar o status. Em execução: aguarde o tempo especificado 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. Obrigatório. |
| lastActionDateTime | True | A hora em que o status foi alterado pela última vez. Obrigatório. |
| resourceLocation | False | O URI para a carga útil do manifesto. Opcional. |
| error | False | 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 local de recurso
| Atributo | Descrição |
|---|---|
| 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. Uma alteração nas informações de faturamento gera um novo valor. |
| partnerTenantId | ID do inquilino 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. Não defina um número fixo de itens de linha ou tamanho de arquivo no código, pois esses valores podem ser alterados. |
| 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: 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". |
| nome | 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". |
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": "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 blob 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 do Armazenamento do Azure/ferramenta para baixar e descompactar o arquivo de blob. Está no formato JSONLines .
Gorjeta
Confira nosso código de exemplo para 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 esses 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 | 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 interno do servidor | A API ou uma de suas dependências não pode 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 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 | 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 |
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
Brevemente: Ao longo de 2024, vamos descontinuar progressivamente o GitHub Issues como mecanismo de feedback para conteúdos e substituí-lo por um novo sistema de feedback. Para obter mais informações, veja: https://aka.ms/ContentUserFeedback.
Submeter e ver comentários