Visão geral da API de envio de ofertas privadas

As ofertas privadas permitem que fornecedores e clientes negociem um ou mais produtos no Azure Marketplace criando ofertas por tempo limitado 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.

Há três tipos principais de ofertas privadas disponíveis no Partner Center e compatíveis com a API de envio de oferta privada:

• 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 a oferta privada do ISV para o 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 com limite de tempo para criar um preço de atacado para seu parceiro CSP. Saiba mais sobre a oferta privada de ISV para parceiro CSP.
• MPO (oferta privada com vários participantes) – uma oferta personalizada configurada 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 adicionar margem de lucro sobre o preço de atacado para chegar ao preço final do cliente e apresentar a oferta ao cliente para aceitação e compra. A aceitação e a compra do MPO seguem o mesmo fluxo que o ISV para ofertas privadas do cliente. Saiba mais sobre a oferta privada com vários participantes.

Terminologia

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

Cenários com suporte

• 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
• Consultar uma lista de ofertas privadas com vários participantes
• Consultar uma lista de produtos e planos

Prepare-se para usar essa API

Antes de escrever o código para chamar a API de ofertas privadas, verifique se você concluiu os pré-requisitos a seguir. Os mesmos pré-requisitos se aplicam a todos os parceiros de publicação.

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

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

Você deve associar um aplicativo de ID do Microsoft Entra à sua conta do Partner Center e obter sua ID de locatário, ID do cliente e chave. Você precisa desses valores para obter o token de acesso do Microsoft Entra que 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 de ele expirar. Depois que o token expirar, você poderá atualizar o token para que você possa continuar a usá-lo em outras chamadas à API.

Para obter o token de acesso, consulte Serviço para chamadas de serviço usando credenciais de cliente para enviar um HTTP POST para o ponto de extremidade https://login.microsoftonline.com/<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 o valor tenant_id no POST URI e os parâmetros client_id e client_secret, especifique a ID do locatário, a ID do cliente e a chave para seu 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 é baseada em um produto existente em 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 amostra:

{
  "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, talvez você queira criar uma oferta privada com base em um plano específico. Nesse caso, você precisa do ID desse 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 amostra:

{
  "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 com 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 criar e gerenciar ofertas privadas associadas a produtos e planos em sua conta do Partner Center. Aqui está um resumo do padrão de chamada típico ao usar essa API.

Etapa 1: fazer a solicitação

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: sondar 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. Depois que o trabalho for concluído, o resultado será Bem-sucedido ou Falha. 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 que faz 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 o motivo da falha do trabalho 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 oferta privada com vários participantes

O ISV e o parceiro de canal podem usar as mesmas APIs para criação e 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 regras de negócios que regem o Partner Center são espelhados na API. Aqui está uma visão geral:

Conteúdo relacionado

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