Información general sobre la API de envío de ofertas privadas

2025-06-21

Las ofertas privadas permiten a los editores y clientes realizar transacciones con uno o varios productos en Azure Marketplace mediante la creación de precios por tiempo con términos personalizados. Las API de envío de ofertas privadas permiten a los editores crear y administrar ofertas privadas mediante programación para clientes o asociados de CSP. Esta API usa el identificador de Microsoft Entra para autenticar las llamadas de 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:

Oferta privada de ISV a cliente : también denominada oferta privada de cliente en el Centro de partners. Se trata de un acuerdo personalizado entre un ISV y un cliente específico con términos y precios personalizados para un producto específico en Azure Marketplace. Más información sobre la oferta privada de ISV a cliente.
Oferta privada de asociado de ISV a CSP : también se denomina oferta privada de asociados de CSP en el Centro de partners. Este tipo de oferta privada permite a ISV especificar un margen de tiempo determinado para crear un precio mayorista para su asociado de CSP. Obtenga más información sobre la oferta privada de asociados de ISV a CSP.
Oferta privada entre varias partes(MPO): una oferta personalizada configurada de forma colaborativa por un ISV y un asociado de canal 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 que se pone a disposición del socio, el socio de canal puede agregar un margen de beneficio sobre el precio mayorista para llegar al precio final al cliente y presenta la oferta al cliente para su aceptación y compra. La aceptación y compra de la MPO sigue el mismo flujo que el ISV a las ofertas privadas del cliente. Obtén más información sobre la oferta privada de varios participantes.

Terminología

Originador de MPO : MPO es una colaboración entre ISV y socio de canal en el mismo acuerdo personalizado para un cliente específico, la parte que primero crea la MPO se designa como el "originador" de la oferta, generalmente el ISV de los productos incluidos en la MPO. Solo puede haber un originador para cualquier MPO dado.
Vendedor de MPO : el socio de canal que prepara la oferta con el precio final para el cliente y presenta la oferta al cliente es el vendedor de la MPO. Solo puede haber un vendedor para cada MPO.
Producto : una sola unidad que representa una oferta en Azure Marketplace. Hay un producto por página de listado.
Plan : una sola versión de un producto en particular. Puede haber varios planes para un producto determinado que representen 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 finalizado el trabajo, puede obtener más información sobre la oferta privada (multipartita) correspondiente.

Escenarios admitidos

Prepárese para usar esta API

Antes de escribir código para llamar a la API de ofertas privadas, asegúrese de haber completado los siguientes requisitos previos. Los mismos requisitos previos se aplican a todos los socios editoriales.

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

Usted o su organización deben tener un directorio de Microsoft Entra. Si ya usa Microsoft 365 u otros servicios empresariales de Microsoft, ya tiene el directorio Microsoft Entra. De lo contrario, puede crear un nuevo identificador de Microsoft Entra en el Centro de partners de forma gratuita.

Debe asociar una aplicación de identificador 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 las 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 pasarlo al encabezado de autorización de cada método de la API. Tienes 60 minutos para usar un token antes de que caduque. Después de la expiración, puede actualizar un token para poder seguir usándolo en futuras llamadas a la API.

Para obtener el token de acceso, consulte Llamadas de servicio a servicio mediante credenciales de cliente para enviar un HTTP POST al https://login.microsoftonline.com/<punto de conexión 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 del URI POST y los parámetros client_id y client_secret, especifique el identificador de inquilino, el identificador 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 productos, planes y ofertas privadas

IDENTIFICACIÓN	Dónde encontrarlos
ID de cliente	Consulte Asociar una aplicación de Microsoft Entra a su cuenta del Centro de partners.
identificador_de_inquilino	Consulte Asociar una aplicación de Microsoft Entra a su cuenta del Centro de partners.
secreto_del_cliente	Consulte Asociar una aplicación de Microsoft Entra a su cuenta del Centro de partners.
ID de producto	Consulte Recuperar productos en este artículo.
planId	Consulte Recuperar planes para un producto específico en este artículo.
privateofferId	Consulte Recuperar ofertas privadas en este artículo.

Recuperar productos

Una oferta privada se basa en un producto existente en su cuenta del Centro de partners. Para ver una lista de productos asociados a su cuenta del Centro de partners, use 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"
}

Recuperar planos 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 ID de ese plan. Obtenga una lista de los planes (como variantes o SKU) para el producto mediante la siguiente llamada a la 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 tu cuenta, usa la siguiente llamada a la API:

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

Cómo usar la API

La API de ofertas privadas le permite crear y administrar ofertas privadas asociadas a productos y planes dentro de su cuenta del Centro de partners. A continuación, se muestra un resumen del patrón de llamada típico al usar esta API.

Paso 1: Realizar la solicitud

Al realizar una llamada a la 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: Sondeo para conocer el estado del trabajo

Con el jobId de la respuesta inicial de la API, sondeo 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 ha comenzado; Esto es parte de la respuesta a la solicitud inicial.
Correr	El trabajo sigue en ejecución.
Completado	El trabajo se ha completado. Consulte jobResult para obtener más detalles.
jobResult	Descripción
Pendiente	El trabajo aún no se ha completado.
Tuvo éxito	El trabajo se ha completado con éxito. Este trabajo también devuelve un resourceURI que hace referencia a la oferta privada relacionada con el trabajo. Use este resourceURI para obtener todos los detalles de una oferta privada.
Fracasado	Error en el trabajo. Esto también devuelve cualquier error relevante para ayudar a determinar la causa del error.

Para obtener más información, consulte Consultar el 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 relevante. 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 partner de canal deben usar de forma colaborativa la API para la oferta privada de varias partes

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

Operación de API	ISV (originador)	Socio de canal (Vendedor)
Crear	El público objetivo es el sociocomercial (vendedor) cuando se publica la llamada a la API, el cliente final no verá la oferta privada hasta que el socio de canal la envíe Recursos editables: Fecha de entrada en vigor Beneficiario previsto (cliente) Socio de canal para colaborar en la oferta, limitado a 1 por oferta privada Contactos de ISV adicionales a los que se notificará el estado de la oferta privada Términos y condiciones personalizados de ISV Productos/planes incluidos en la oferta privada Duraciones de los contratos para cada producto/plan Cantidades incluidas para cada producto (si corresponde) Atributos del plan sin precios (si corresponde) Precio mayorista con descuento disponible para el socio de canal en los productos/plan incluidos Notas de ventas de ISV	El público objetivo es el cliente final cuando se publica la llamada a la API Recursos editables: Términos y condiciones personalizados para socios de canal Preparado por Ajuste del cliente (porcentaje de recargo) sobre el precio mayorista del ISV para cada producto/plan incluido en la oferta privada, esto determina el precio final para el cliente final Contactos de socios de canal adicionales para recibir notificaciones del estado de la oferta privada Notas de ventas para socios de canal
Borrar	Compatible con ofertas privadas en estado de borrador	No compatible
Retirar	Compatible con las ofertas privadas publicadas por el ISV, pero que aún no han sido publicadas por el socio de canal o si el socio de canal las retira	Compatible con ofertas privadas publicadas y disponibles para clientes finales, pero aún no aceptadas

Operación de API

ISV (originador)

Socio de canal (Vendedor)

Crear

El público objetivo es el sociocomercial (vendedor) cuando se publica la llamada a la API, el cliente final no verá la oferta privada hasta que el socio de canal la envíe

Recursos editables:

Fecha de entrada en vigor
Beneficiario previsto (cliente)
Socio de canal para colaborar en la oferta, limitado a 1 por oferta privada
Contactos de ISV adicionales a los que se notificará el estado de la oferta privada
Términos y condiciones personalizados de ISV
Productos/planes incluidos en la oferta privada
Duraciones de los contratos para cada producto/plan
Cantidades incluidas para cada producto (si corresponde)
Atributos del plan sin precios (si corresponde)
Precio mayorista con descuento disponible para el socio de canal en los productos/plan incluidos
Notas de ventas de ISV

El público objetivo es el cliente final cuando se publica la llamada a la API