Descrição geral da API de envio de ofertas privadas

As ofertas privadas permitem que editores e clientes transacionem um ou mais produtos no Azure Marketplace criando preços com limite de tempo com termos personalizados. As APIs de envio de ofertas privadas permitem que os editores criem e gerenciem programaticamente ofertas privadas para clientes e/ou parceiros CSP. Essa API usa a ID do Microsoft Entra para autenticar as chamadas do seu aplicativo ou serviço.

Existem três tipos principais de ofertas privadas disponíveis no Partner Center e suportadas pela API de envio de ofertas privadas:

• ISV para oferta privada do cliente – Também denominada oferta privada do cliente no Partner Center. Este é um acordo personalizado entre um ISV e um cliente específico com termos e preços personalizados para um produto específico no Azure Marketplace. Saiba mais sobre ISV para oferta privada ao cliente.
• Oferta privada de ISV para parceiro CSP – Também denominada oferta privada de parceiros CSP no Partner Center. Esse tipo de oferta privada permite que o ISV especifique a margem limitada no tempo para criar um preço de atacado para seu parceiro CSP. Saiba mais sobre a oferta privada de parceiros ISV para CSP.
• Oferta privada de várias partes (MPO) – Um negócio personalizado configurado de forma colaborativa por um ISV e um parceiro de canal preferencial de um cliente específico com termos e preços personalizados para produtos específicos no Azure Marketplace. O ISV define o preço de atacado com desconto disponibilizado ao parceiro, o parceiro de canal pode então adicionar markup em cima do preço de atacado para chegar ao preço do cliente final e apresenta a oferta ao cliente para aceitação e compra. A aceitação e compra do MPO segue o mesmo fluxo do ISV para ofertas privadas do cliente. Saiba mais sobre a oferta privada de vários participantes.

Terminologia

• Originador MPO – MPO é uma colaboração entre ISV e parceiro de canal no mesmo negócio personalizado para um cliente específico, a parte que primeiro cria o MPO é designada o "originador" da oferta, normalmente o ISV dos produtos incluídos no MPO. Só pode haver um originador para cada MPO.
• Vendedor MPO – O parceiro de canal que prepara a oferta com o preço do cliente final e apresenta a oferta ao cliente é o vendedor do MPO. Só pode haver um vendedor para cada MPO.
• Produto – Uma única unidade que representa uma oferta no Azure Marketplace. Há um produto por página de anúncio.
• Plano – Uma única versão de um determinado produto. Pode haver vários planos para um determinado produto que representam vários níveis de preços ou termos.
• Trabalho – Uma tarefa criada ao fazer uma solicitação nesta API. Ao usar essa API para gerenciar ofertas privadas e ofertas privadas de vários participantes, um trabalho é criado para concluir a solicitação. Uma vez concluído o trabalho, você pode obter mais informações sobre a oferta privada relevante (multipartes).

Cenários suportados

• Criar uma oferta privada para um cliente
• Criar uma oferta privada para um revendedor
• Criar uma oferta privada com vários participantes para um cliente
• Excluir uma oferta privada
• Retirar uma oferta privada
• Consulta de uma lista de ofertas privadas de vários participantes
• Consultar uma lista de produtos e planos

Prepare-se para usar esta API

Antes de escrever código para chamar a API de ofertas privadas, certifique-se de ter concluído os seguintes pré-requisitos. Os mesmos pré-requisitos aplicam-se a todos os parceiros de publicação.

Etapa 1: Concluir os pré-requisitos para usar a API de ingestão de produtos Microsoft (uma vez)

Você ou sua organização devem ter um diretório do Microsoft Entra e permissão de administrador global. Se você já usa o Microsoft 365 ou outros serviços empresariais da Microsoft, você já tem o diretório Microsoft Entra. Caso contrário, você pode criar uma nova ID do Microsoft Entra no Partner Center gratuitamente.

Você deve associar um aplicativo Microsoft Entra ID à sua conta do Partner Center e obter sua ID de locatário, ID de cliente e chave. Você precisa desses valores para obter o token de acesso do Microsoft Entra que você usará em chamadas para a API de ofertas privadas.

Etapa 2: Obter um token de acesso do Microsoft Entra (sempre)

Antes de chamar qualquer um dos métodos na API de envio da Microsoft Store, você precisa de um token de acesso do Microsoft Entra para passar para o cabeçalho de autorização de cada método na API. Você tem 60 minutos para usar um token antes que ele expire. Após a expiração, você pode atualizar um token para continuar a usá-lo em outras chamadas para a API.

Para obter o token de acesso, consulte Service to Service Calls Using Client Credentials para enviar um HTTP POST para o https://login.microsoftonline.com/<ponto de extremidade tenant_id>/oauth2/token . Aqui está um exemplo de solicitação:

POST https://login.microsoftonline.com/<tenant_id>/oauth2/token HTTP/1.1
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded; charset=utf-8
grant_type=client_credentials
&client_id=<your_client_id>
&client_secret=<your_client_secret>
&resource=https://graph.microsoft.com/

Para obter o valor tenant_id no URI POST e os parâmetros client_id e client_secret, especifique a ID do locatário, a ID do cliente e a chave do aplicativo que você recuperou do Partner Center na seção anterior. Para o parâmetro resource, você deve especificar https://graph.microsoft.com/.

Encontre IDs de produtos, planos e ofertas privadas

Recuperar produtos

Uma oferta privada baseia-se num produto existente na sua conta do Partner Center. Para ver uma lista de produtos associados à sua conta do Partner Center, use esta chamada de API:

GET https://graph.microsoft.com/rp/product-ingestion/product?$version=2022-07-01

A resposta aparece no seguinte formato de exemplo:

{
  "value": [
    {
      "$schema": "https://schema.mp.microsoft.com/schema/product/2022-07-01",
      "id": "string",
      "identity": {
        "externalId": "string"
      },
      "type": "enum",
      "alias": "string"
    }
  ],
  "@nextLink": "opaque_uri"
}

Recuperar planos para um produto específico

Para produtos que contêm mais de um plano, convém criar uma oferta privada com base em um plano específico. Se sim, você precisa do ID do plano. Obtenha uma lista dos planos (como variantes ou SKUs) para o produto usando a seguinte chamada de API:

GET https://graph.microsoft.com/rp/product-ingestion/plan?product=<product-id>&$version=2022-07-01

A resposta aparece no seguinte formato de exemplo:

{
  "value": [
    {
      "$schema": "https://schema.mp.microsoft.com/schema/plan/2022-07-01",
      "product": "string",
      "id": "string",
      "identity": {
        "externalId": "string"
      },
      "alias": "string"
    }
  ]
}

Recuperar ofertas privadas

Para ver uma lista de todas as ofertas privadas, incluindo ofertas privadas de vários participantes, associadas à sua conta, use a seguinte chamada de API:

GET https://graph.microsoft.com/rp/product-ingestion/private-offer/query?$version=2023-07-15

Como usar a API

A API de oferta privada permite-lhe criar e gerir ofertas privadas associadas a produtos e planos na sua conta do Partner Center. Aqui está um resumo do padrão de chamada típico ao usar essa API.

Passo 1: Faça o pedido

Quando você faz uma chamada de API para criar, excluir, retirar ou atualizar uma oferta privada, um novo trabalho é criado para concluir a tarefa solicitada. A resposta da API contém um jobId associado ao trabalho.

Etapa 2: Enquete para o status do trabalho

Usando o jobId da resposta inicial da API, pesquise para obter o status do trabalho. O status do trabalho será Em execução ou Concluído. Quando o trabalho for concluído, o resultado será Bem-sucedido ou Reprovado. Para evitar problemas de desempenho, não sonde um trabalho mais de uma vez por minuto.

Para obter mais informações, consulte Consultar o status de um trabalho existente.

Etapa 3: Obter informações de trabalhos concluídos

Um trabalho bem-sucedido retorna um resourceUri fazendo referência à oferta privada relevante. Use este recurso Uri para obter mais detalhes sobre a oferta privada no futuro, como o privateofferId.

Um trabalho com falha contém erros que fornecem detalhes sobre por que o trabalho falhou e como resolver o problema.

Para obter mais informações, consulte Obter detalhes de uma oferta privada existente.

Como o ISV e o parceiro de canal devem usar colaborativamente a API para ofertas privadas de várias partes

Tanto o ISV quanto o parceiro de canal podem usar as mesmas APIs para a criação e o gerenciamento de um determinado MPO. No entanto, os recursos em um MPO que podem afetar a API dependem se o chamador da API é o ISV (originador) ou o parceiro de canal (vendedor) do MPO. O mesmo fluxo de publicação de ISV/parceiro de canal e as mesmas regras de negócios que regem o Partner Center são espelhados na API. Aqui está uma visão geral:

Conteúdos relacionados

• Criar uma oferta privada para um cliente
• Criar uma oferta privada para um revendedor
• Criar oferta privada de vários participantes para a API do cliente