Introducción a la API de envío de ofertas privadas

  • Artículo

Las ofertas privadas permiten a publicadores y clientes realizar transacciones de uno o varios productos en Azure Marketplace mediante la creación de precios limitados en el tiempo con términos personalizados. Las API de envío de ofertas privadas permiten a los publicadores crear y administrar ofertas privadas para clientes o asociados de CSP mediante programación. Esta API usa microsoft Entra ID para autenticar las llamadas desde la aplicación o el servicio.

Hay tres tipos principales de ofertas privadas disponibles en el Centro de partners y compatibles con la API de envío de ofertas privadas:

  • ISV a la oferta privada del cliente: también se denomina oferta privada del cliente en el Centro de partners. Se trata de una oferta personalizada entre un ISV y un cliente específico con términos y precios personalizados para un producto específico en Azure Marketplace. Obtenga más información sobre isv a la oferta privada del cliente.
  • ISV a la oferta privada de asociados de CSP: también se denomina oferta privada de asociados de CSP en el Centro de partners. Este tipo de oferta privada permite al ISV especificar el margen de tiempo limitado para crear un precio mayorista para su asociado de CSP. Obtenga más información sobre la oferta privada del asociado de CSP para ISV.
  • Oferta privada de varias partes (MPO): una oferta personalizada configurada de forma colaborativa por un ISV y un asociado de venta preferido de un cliente específico con términos y precios personalizados para productos específicos en Azure Marketplace. El ISV define el precio mayorista con descuento disponible para el socio, el socio vendedor puede agregar marcado sobre el precio mayorista para llegar al precio final del cliente y presentar la oferta al cliente para su aceptación y compra. La aceptación y compra del MPO sigue el mismo flujo que isV a las ofertas privadas del cliente. Obtenga más información sobre la oferta privada de varias partes.

Terminología

  • Originador de MPO: MPO es una colaboración entre ISV y partner de venta en la misma oferta personalizada para un cliente específico, la entidad que primero crea el MPO se designa como el "originador" de la oferta, normalmente el ISV de los productos incluidos en el MPO. Solo puede haber un originador para cualquier MPO determinado.
  • Vendedor de MPO : el socio de venta que prepara la oferta con el precio final del cliente y presenta la oferta al cliente es el vendedor del MPO. Solo puede haber un vendedor para cualquier MPO determinado.
  • Producto : una sola unidad que representa una oferta en Azure Marketplace. Hay un producto por página de descripción.
  • Plan : una sola versión de un producto determinado. Puede haber varios planes para un producto determinado que represente varios niveles de precios o términos.
  • Trabajo : una tarea creada al realizar una solicitud en esta API. Al usar esta API para administrar ofertas privadas y ofertas privadas de varias partes, se crea un trabajo para completar la solicitud. Una vez completado el trabajo, puede obtener más información sobre la oferta privada pertinente (multiparty).

Escenarios admitidos

Prepárese para usar esta API

Antes de escribir código para llamar a la API de ofertas privadas, asegúrese de que ha completado los siguientes requisitos previos. Se aplican los mismos requisitos previos a todos los asociados de publicación.

Paso 1: Completar los requisitos previos para usar la API de ingesta de productos de Microsoft (una vez)

Usted o su organización deben tener un directorio de Microsoft Entra y un permiso de administrador global. Si ya usa Microsoft 365 u otros servicios empresariales de Microsoft, ya tiene el directorio Microsoft Entra. Si no es así, puede crear un nuevo identificador de Microsoft Entra en el Centro de partners de forma gratuita.

Debe asociar una aplicación de id. de Microsoft Entra a su cuenta del Centro de partners y obtener el identificador de inquilino, el identificador de cliente y la clave. Necesita estos valores para obtener el token de acceso de Microsoft Entra que usará en llamadas a la API de ofertas privadas.

Paso 2: Obtener un token de acceso de Microsoft Entra (cada vez)

Antes de llamar a cualquiera de los métodos de la API de envío de Microsoft Store, necesita un token de acceso de Microsoft Entra para pasar al encabezado de autorización de cada método de la API. Tiene 60 minutos para usar un token antes de que expire. Después de que expire, puedes actualizar un token para que puedas continuar usándolo en llamadas adicionales a la API.

Para obtener el token de acceso, vea las Llamadas de servicio a servicio utilizando las credenciales del cliente para enviar un HTTP POST al punto de conexión https://login.microsoftonline.com/<tenant_id>/oauth2/token. Esta es una solicitud de ejemplo:

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 el valor tenant_id en el URI de POST y los parámetros client_id y client_secret, especifique el id. de inquilino, el de cliente y la clave de la aplicación que recuperó del Centro de partners en la sección anterior. Para el parámetro de recurso, debe especificar https://graph.microsoft.com/.

Buscar identificadores de producto, plan y oferta privada

ID Dónde encontrarlos
client_id Consulta Asociar una aplicación de Microsoft Entra a tu cuenta del Centro de partners.
tenant_id Consulta Asociar una aplicación de Microsoft Entra a tu cuenta del Centro de partners.
client_secret Consulta Asociar una aplicación de Microsoft Entra a tu cuenta del Centro de partners.
productId Consulte Recuperación de productos en este artículo.
planId Consulte Recuperación de planes para un producto específico en este artículo.
privateofferId Consulte Recuperación de ofertas privadas en este artículo.

Recuperación de productos

Una oferta privada se basa en un producto existente en la cuenta del Centro de partners. Para ver una lista de productos asociados a tu cuenta del Centro de partners, usa esta llamada API:

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

La respuesta aparece en el siguiente formato de ejemplo:

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

Recuperación de planes para un producto específico

En el caso de los productos que contienen más de un plan, es posible que desee crear una oferta privada basada en un plan específico. Si es así, necesita el identificador del plan. Obtenga una lista de los planes (como variantes o SKU) para el producto mediante la siguiente llamada API:

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

La respuesta aparece en el siguiente formato de ejemplo:

{
  "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 una lista de todas las ofertas privadas, incluidas las ofertas privadas de varias partes, asociadas a su cuenta, use la siguiente llamada API:

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

Cómo usar la API

La API de oferta privada permite crear y administrar ofertas privadas asociadas a productos y planes dentro de la cuenta del Centro de partners. Este es un resumen del patrón de llamada típico al usar esta API.

Flowchart showing multiparty private offers steps.

Paso 1: Realizar la solicitud

Al realizar una llamada API para crear, eliminar, retirar o actualizar una oferta privada, se crea un nuevo trabajo para completar la tarea solicitada. La respuesta de la API contiene un jobId asociado al trabajo.

Paso 2: Sondear el estado del trabajo

Con el valor de jobId de la respuesta inicial de la API, sondee para obtener el estado del trabajo. El estado del trabajo será En ejecución o Completado. Una vez completado el trabajo, el resultado será Correcto o Erróneo. Para evitar problemas de rendimiento, no sondee un trabajo más de una vez por minuto.

jobStatus Descripción
NotStarted El trabajo aún no se ha iniciado; esto forma parte de la respuesta en la solicitud inicial.
En ejecución El trabajo todavía se está ejecutando.
Completado Se ha completado el trabajo. Consulte jobResult para obtener más detalles.
jobResult Descripción
Pending El trabajo aún no se ha completado.
Correcto El trabajo se ha completado correctamente. Este trabajo también devuelve un resourceURI que hace referencia a la oferta privada relacionada con el trabajo. Use este resourceURI para obtener los detalles completos de una oferta privada.
Con errores El trabajo ha sufrido un error. Esto también devuelve los errores pertinentes para ayudar a determinar la causa del error.

Para obtener más información, consulte Consulta del estado de un trabajo existente.

Paso 3: Obtener información de los trabajos completados

Un trabajo correcto devuelve un resourceUri que hace referencia a la oferta privada pertinente. Use este URI de recurso para obtener más detalles sobre la oferta privada en el futuro, como privateofferId.

Un trabajo con errores contiene errores que proporcionan detalles sobre por qué se produjo un error en el trabajo y cómo resolver el problema.

Para obtener más información, consulte Obtener detalles de una oferta privada existente.

Cómo el ISV y el asociado de venta deben usar de forma colaborativa la API para la oferta privada de varias partes

Tanto el ISV como el asociado de venta pueden usar las mismas API para la creación y administración de un MPO determinado. Sin embargo, los recursos de un MPO que pueden afectar a la API dependen de si el autor de la llamada de la API es el ISV (originador) o el asociado de venta (vendedor) del MPO. El mismo flujo de publicación de partners/ventas de ISV y reglas de negocio que rigen el Centro de partners se reflejan en la API. Esta es una introducción:

Operación de API ISV (originador) Vendedor (vendedor)
Create
  • La audiencia prevista es el partner de venta(vendedor) cuando se publica la llamada API, el cliente final no verá la oferta privada hasta que el asociado de venta envíe.
Recursos editables:
  • Fecha de entrada en vigor
  • Beneficiario previsto (cliente)
  • Vender asociado para colaborar en la oferta, limitado a 1 por oferta privada
  • Contactos de ISV adicionales para recibir una notificación del estado de la oferta privada
  • Términos y condiciones personalizados de ISV
  • Productos y planes incluidos en la oferta privada
  • Duración del contrato para cada producto o plan
  • Cantidades incluidas para cada producto (si procede)
  • Atributos de plan que no son de ordenación (si procede)
  • Precio mayorista con descuento disponible para el socio de venta en los productos o planes incluidos
  • Notas de ventas de ISV
  • La audiencia prevista es el cliente final cuando se publica la llamada API.
Recursos editables:
  • Venta de términos y condiciones personalizados para asociados
  • Preparado por
  • Ajuste del cliente (porcentaje de marcado) sobre el precio mayorista del ISV para cada producto o plan incluido en la oferta privada, esto determina el precio final del cliente final.
  • Contactos de partners de venta adicionales para recibir una notificación del estado de la oferta privada
  • Ventas de notas de ventas de asociados
Eliminar
  • Compatible con ofertas privadas en estado de borrador
  • No se admite
Withdraw
  • Compatible con las ofertas privadas publicadas por el ISV, pero aún no publicadas por el partner de venta o si el partner vendedor lo retira
  • Compatible con ofertas privadas publicadas y disponibles para los clientes finales, pero aún no aceptadas

Pasos siguientes