API de reconciliação de fatura faturada v2 (GA)
Aplica-se a: Partner Center (indisponível no Azure Governamental ou no Azure China 21Vianet)
Entender a arquitetura
A nova API assíncrona oferece avanços significativos na forma como lidamos com o acesso a dados de cobrança e reconciliação. Essa abordagem resolve os desafios associados aos métodos síncronos tradicionais, como manter conexões de longa duração e processar grandes lotes de dados. Aqui estão os principais benefícios e mecanismos desta API:
Componentes principais
Garantir o acesso seguro com o padrão de chave limitada
O padrão de chave limitada fornece acesso seguro e limitado aos seus dados de cobrança. Semelhante a uma chave de manobrista que permite que alguém dirija seu carro sem acessar o porta-malas, esse padrão garante um controle de acesso granular. Em vez de compartilhar credenciais, um token SAS (assinatura de acesso compartilhado) concede acesso limitado e com prazo determinado a recursos específicos. Esse padrão reduz o risco de acesso não autorizado configurando tempos de expiração precisos e permissões de acesso.
Eficiência aprimorada por meio do padrão assíncrono solicitação-resposta
Pense nisso como pedir em um restaurante ocupado. Em vez de esperar no balcão, você recebe uma campainha e pode fazer outras coisas enquanto seu pedido está preparado. Quando os dados estiverem prontos, o sistema notificará você.
A natureza assíncrona da API significa que você faz uma solicitação e o sistema a processa em segundo plano. Essa solicitação-resposta assíncrona usa recursos com eficiência, reduz a carga do servidor e minimiza tempos limite e falhas comuns com a recuperação de dados síncrona.
Flexibilidade nas permissões de acesso a dados
Os tokens SAS oferecem flexibilidade no gerenciamento de permissões de acesso a dados. Você pode gerar tokens que concedem acesso a todos os atributos dos dados de reconciliação de fatura cobrados ou limitam o acesso a subconjuntos específicos. Essa granularidade permite que as organizações adaptem o acesso a dados de acordo com políticas internas e requisitos regulatórios, aprimorando a segurança e a conformidade.
Fluxo de trabalho simplificado e tempos de processamento de dados aprimorados
O padrão assíncrono de solicitação-resposta simplifica o processamento de dados permitindo acesso dinâmico em vez de lotes fixos de 2.000 itens de linha. Essa abordagem leva a resultados mais rápidos e tempos de processamento aprimorados, simplificando a integração de dados de cobrança e reconciliação em sistemas e fluxos de trabalho existentes.
Benefícios
Benefícios de desempenho
Em vez de manter conexões de longa duração e processar lotes fixos, o novo sistema permite que você:
Faça uma solicitação inicial rápida.
Receba um token de acesso seguro.
Processe dados em seu próprio ritmo.
Acesse exatamente o que você precisa quando precisar.
melhorias de segurança
O padrão de chave limitada, implementado por meio de tokens SAS, fornece:
Acesso limitado por tempo.
Permissões restritas.
Eliminação do compartilhamento ou do armazenamento de credenciais permanentes.
Controle de acesso refinado.
vantagens arquitetônicas
O padrão assíncrono de solicitação-resposta age como um assistente pessoal que:
Aceita sua solicitação.
Executa a tarefa em segundo plano.
Notifica você quando tudo está pronto.
Adotar APIs otimizadas para melhorar o desempenho
A adoção dessas APIs otimizadas simplifica o fluxo de trabalho e melhora o desempenho geral no gerenciamento de dados. Usando o controle de acesso seguro e mecanismos de recuperação eficientes, você obtém melhores resultados com menos esforço, levando a uma melhor eficiência operacional.
Em conclusão, a nova API assíncrona para acessar dados de cobrança e reconciliação por meio de blobs do Azure é uma ferramenta poderosa. Ele oferece acesso seguro e eficiente a dados financeiros, simplificando fluxos de trabalho, reduzindo cargas de servidor e melhorando os tempos de processamento, tudo com alta segurança e conformidade.
Observação
A nova API não está hospedada no host da API do Partner Center. Em vez disso, você pode encontrá-lo no Microsoft 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.
Permitir que seu aplicativo acesse com segurança os dados de cobrança do parceiro
Para permitir que seu aplicativo acesse dados de cobrança de parceiros, siga este link e familiarize-se com as noções básicas de autenticação e autorização para o Microsoft Graph. Essa 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 essas etapas, você ajuda a garantir que seu aplicativo tenha o acesso necessário aos dados de cobrança do parceiro. Aqui está como:
- Registre seu aplicativo na home page do Microsoft Entra na seção Registros de aplicativo.
- Conceda a permissão necessária acessando a página do aplicativo Microsoft Entra. Na seção de permissões de API, selecione Adicionar uma permissão e escolha o escopo PartnerBilling.Read.All.
Saiba mais sobre os principais pontos de extremidade da API
Para ajudar você a recuperar itens de linha de reconciliação de fatura de novo comércio faturados de maneira assíncrona, oferecemos dois pontos de extremidade principais de API. Esses endpoints ajudam você a gerenciar com eficiência o processo de conciliação de faturas. Siga esse guia simplificado para começar rapidamente.
Usar o ponto de extremidade de reconciliação de fatura cobrada
Primeiro, use essa API para buscar novos itens de linha de reconciliação de fatura faturada pelo novo comércio. Ao fazer uma solicitação, você recebe um status HTTP 202 e um cabeçalho de localização com uma URL. Sonde essa URL regularmente até obter um status de êxito e uma URL de manifesto.
Usar o ponto de extremidade 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. Depois que 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 aprimorar a taxa de transferência e permitir o paralelismo de E/S.
Examinar 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.
Siga a sequência de ação do usuário para obter dados de reconciliação de fatura.
Aqui está a sequência de ações do usuário para recuperar dados de conciliação de faturas cobradas.
- enviar uma solicitação POST
- Verificar o status da solicitação
- Baixar itens de linha de reconciliação do armazenamento de blobs do Azure
Enviar uma solicitação POST
Envie uma solicitação POST para o ponto de extremidade da API.
Obtenha os itens de linha de reconciliação de fatura cobrada
Obtenha os itens de linha de reconciliação de fatura cobrada.
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 | Tipo | Descrição |
|---|---|---|---|
| attributeSet | False | Cadeia de caracteres | Escolha "full" para todos os atributos ou "basic" 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 | Cadeia de caracteres | Um identificador exclusivo para cada fatura. Obrigatório. |
Cabeçalhos de solicitação
Solicite cabeçalhos para a API usando as etapas listadas em Práticas recomendadas para usar o Microsoft Graph. Seguindo essas diretrizes, você garante confiabilidade e suporte para seu aplicativo. 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 são listados na seção Status de resposta da API Standard.
| Código | Descrição |
|---|---|
| 202 – Aceito | Sua solicitação foi aceita. Para verificar o status da sua solicitação, consulte a URL fornecida no cabeçalho do local. |
Verificar o status da solicitação
Para acompanhar o status de uma solicitação, certifique-se de que você recebeu uma resposta HTTP 200 que é um código de status padrão indicando "bem-sucedido" ou "com falha". Se for bem-sucedido, você encontrará o URL do manifesto no atributo "resourceLocation". Esse 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.
Solicitação de 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 | Obrigatório | Tipo | Descrição |
|---|---|---|---|---|
| operationId | URI de solicitação | True | Cadeia de caracteres | Um identificador exclusivo para verificar o status da solicitação. Obrigatório. |
Cabeçalho da solicitação
Solicite cabeçalhos para a API usando as etapas listadas em Práticas recomendadas para usar o Microsoft Graph. Seguindo essas diretrizes, você garante confiabilidade e suporte para seu aplicativo. Sua atenção aos detalhes nesta etapa é crucial para uma integração perfeita e um desempenho ideal.
Corpo da solicitação
N/A.
Status da resposta
Além dos status HTTP padrão listados em Status de resposta da API Standard, a API também pode retornar o seguinte status HTTP:
| Código | Descrição |
|---|---|
| 410 – Passado | O link do manifesto expira após um tempo definido. Para obter o link do manifesto novamente, envie uma nova solicitação. |
Payload da resposta
O payload da resposta da API inclui os seguintes atributos:
| Atributo | Obrigatório | Descrição |
|---|---|---|
| id | True | Um identificador exclusivo para cada resposta Obrigatório. |
| status | True | Valores e ações: obrigatório. notstarted: aguarde a duração especificada no cabeçalho "Retry-After" e faça outra chamada para verificar o status. running: aguarde a duração especificada 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-a. |
| createdDateTime | True | A hora em que a solicitação foi feita. Obrigatório. |
| lastActionDateTime | True | A última vez que o status foi alterado. Obrigatório. |
| resourceLocation | False | O URI para o payload do manifesto. Opcional. |
| erro | False | Detalhes sobre quaisquer erros, fornecidos no formato JSON. Opcional. Os atributos incluíam: message: uma descrição do erro. code: O tipo de erro. |
Objeto de local 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. Um novo valor é gerado sempre que há uma alteração nas informações de cobrança. |
| partnerTenantId | Microsoft Entra ID 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. |
| partitionType | Divide os dados em vários blobs com base no atributo partitionValue. O sistema divide as partições que excedem o número com suporte. Por padrão, os dados são particionados com base no número de itens de linha no arquivo. Evite codificar de forma fixa as contagens de itens de linha ou tamanhos de arquivo, pois eles podem mudar. |
| 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 de blob | Um objeto que contém os seguintes detalhes: name e partitionValue |
| name | O nome do blob. |
| partitionValue | A partição que contém o arquivo. A partição grande é dividida em vários arquivos com base em determinados critérios, como tamanho do arquivo ou número de registros, 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 dez 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": "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"
}
\]
}
}
Baixar os itens de linha de reconciliação de fatura cobrada do armazenamento de blobs do Azure
Primeiro, você precisa obter o token SAS (assinatura de acesso compartilhado) e o local de armazenamento de blobs. Encontre esses detalhes nas propriedades sasToken e rootDirectory da resposta da API de conteúdo do manifesto.
Para continuar, siga estas etapas:
- Baixe o arquivo de blob usando o SDK/ferramenta do Armazenamento do Microsoft Azure.
- Descompacte o arquivo, que está no formato JSONLines.
Dica
Não deixe de conferir nosso código de exemplo . Ele mostra como baixar e descompactar o arquivo de blob do Azure no banco de dados local.
Status de resposta da API Standard
Você pode obter os seguintes status HTTP da resposta à 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 | A autenticação é necessária antes de fazer a primeira chamada. Autentique com o serviço de API do parceiro. |
| 403 – Forbidden | 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 – Passado | O link do manifesto não é mais válido ou ativo. Envie uma nova solicitação. |
| 500 – Erro Interno do Servidor | A API ou as dependências dela não podem atender à solicitação no momento. Tente novamente mais tarde. |
| 5000 – Sem dados disponíveis | O sistema não tem dados para os parâmetros de entrada fornecidos. |
Comparar atributos básicos e completos de reconciliação de fatura
Para comparar os atributos retornados pela API de reconciliação de fatura cobrada para os conjuntos de atributos "full" ou "basic", consulte esta tabela. Para saber mais sobre esses atributos e seus significados, consulte Usar o arquivo de reconciliação.
| Atributo | Full | 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 |
| Quantity | sim | não |
| Subtotal | sim | sim |
| TaxTotal | sim | sim |
| Total | sim | sim |
| Currency | 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 |
Importante
Cada nome de campo ou atributo começa com uma letra maiúscula para manter a consistência com o arquivo e melhorar a legibilidade.
Código de exemplo
Se você precisar de assistência para migrar para essa API, consulte o link que inclui o código de exemplo do C#.
Exemplos de uso da API para obter dados de reconciliação de faturamento do Partner Center.