Visã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:

• Oferta privada de ISV para o 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 oferta privada de ISV para clientes.
• Oferta privada de ISV para parceiro CSP – Também denominada oferta privada de parceiro 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 ISV dirigida a parceiros CSP .
• Oferta privada multiparte(MPO) – Um negócio personalizado configurado colaborativamente 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 a compra do MPO seguem o mesmo processo que o ISV para ofertas privadas ao cliente. Saiba mais sobre a oferta multipartes privada .

Terminologia

• MPO originator – MPO é uma colaboração entre ISV e parceiro de canais 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 final ao cliente e a apresenta ao cliente é o vendedor da MPO. Só pode haver um vendedor para cada MPO.
• Product – 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.
• Job – 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
• Crie uma oferta privada para um revendedor
• Criar uma oferta privada de vários participantes para um cliente
• Excluir uma oferta privada
• Retirar uma oferta privada
• Consultar uma lista de ofertas privadas multipartidárias
• Consulta para obter 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 uma aplicação do Microsoft Entra ID à sua conta do Partner Center e obter a sua identificação 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 a secção Service to Service Calls Using Client Credentials 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 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

ID	Onde encontrá-los
ID do cliente	Veja Associar uma aplicação Microsoft Entra à sua conta do Partner Center.
ID do inquilino	Veja Associar uma aplicação Microsoft Entra à sua conta do Partner Center.
segredo_do_cliente	Veja Como associar uma aplicação Microsoft Entra à sua conta do Partner Center.
productId	Neste artigo, consulte Recuperar produtos.
planId	Consulte Recuperar planos para um produto específico neste artigo.
privateofferId	Veja Obter ofertas privadas no presente artigo.

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á Concluído ou Falhado. Para evitar problemas de desempenho, não sonde um trabalho mais de uma vez por minuto.

situação do emprego	Descrição
Não Iniciado	O trabalho ainda não começou; isso faz parte da resposta sobre o pedido inicial.
Corrida	O trabalho ainda está em execução.
Concluído	O trabalho foi concluído. Consulte jobResult para obter mais detalhes.
resultadoDoTrabalho	Descrição
Pendente	O trabalho ainda não foi concluído.
Bem sucedido	O trabalho foi concluído com êxito. Esta tarefa também retorna um "resourceURI" que se refere à oferta privada relacionada à tarefa. Use este resourceURI para obter todos os detalhes de uma oferta privada.
Falhou	O trabalho falhou. Isso também retorna quaisquer erros relevantes para ajudar a determinar a causa da falha.

Para obter mais informações, consulte Consultar o estado 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 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:

Operação da API	ISV (Originador)	Parceiro de canal (Vendedor)
Criar	O público-alvo é o vendedorparceiro (vendedor) quando a chamada de API é publicada, o cliente final não verá a oferta privada até que o parceiro de canal envie Recursos editáveis: Datas de entrada em vigor Beneficiário pretendido (cliente) Parceiro de canal para colaborar na oferta, limitado a 1 por oferta privada Contactos adicionais de ISV a serem notificados sobre o estado da oferta privada Termos e condições personalizados do ISV Produtos/planos incluídos na oferta privada Duração dos contratos para cada produto/plano Quantidades incluídas para cada produto (se aplicável) Atributos do plano sem preços (se aplicável) Preço de atacado com desconto disponível para o parceiro de canal nos produtos/plano incluídos ISV - Notas de venda	O público-alvo é o cliente final no momento em que a chamada de API é efetuada. Recursos editáveis: Termos e condições personalizados para parceiros de canal Preparado por Ajuste do cliente (percentagem de aumento) sobre o preço grossista do ISV para cada produto/plano incluído na oferta privada, o que determina o preço final para o cliente. Contatos adicionais de parceiros de canal a serem informados sobre o estado da oferta exclusiva Notas de vendas de parceiros de canal
Suprimir	Suporte para ofertas privadas em estado de rascunho	Não suportado
Retirar	Suportado para ofertas privadas publicadas pelo ISV, mas ainda não publicadas pelo parceiro de canal ou retiradas pelo parceiro de canal.	Suporte para ofertas privadas publicadas e disponíveis para clientes finais, mas ainda não aceitas.

Conteúdo relacionado

• Criar uma oferta privada para um cliente
• Crie uma oferta privada para um revendedor
• Criar oferta privada multilateral para API do cliente