Creación de una oferta privada de varias partes a través de la API

En este artículo se proporcionan instrucciones técnicas sobre el uso de las API de envío de ofertas privadas del Centro de partners para crear y administrar ofertas privadas de varias partes mediante programación para Microsoft Marketplace. Detalla las llamadas API necesarias, esquemas y flujos de trabajo basados en roles para empresas de software y asociados de canal, incluida la configuración de precios, la administración del ciclo de vida de la oferta y el envío para la aceptación del cliente en los tipos de oferta admitidos.

Los asociados colaboradores usan el mismo conjunto de llamadas API para crear una oferta privada de varias partes. Este es el flujo esperado.

  1. La empresa de software crea la oferta privada de múltiples partes y la envía para que sea visible a los socios de canal

  2. La empresa de software notifica al asociado de canal que una oferta privada de múltiples partes está disponible para que la revisen y tomen las medidas necesarias.

  3. El asociado de canal revisa y completa la configuración de la oferta privada y la envía para que sea visible al cliente final.

Este es el método a invocar para la creación de la oferta privada de varias partes.

Solicitar

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

Encabezado de solicitud

Encabezado Tipo Descripción
Autorización Cadena Necesario. Token de acceso de Microsoft Entra con el formato Bearer <token>.

Opcional: clientID

Parámetros de solicitud

$version: obligatorio. Esta es la versión del esquema que se usa en la solicitud.

Registro de cambios de versión del esquema

Anterior New Fecha de vigencia
https://schema.mp.microsoft.com/schema/private-offer/ 2024-09-30 https://schema.mp.microsoft.com/schema/private-offer/ 2026-02-01 17 de abril de 2026
https://schema.mp.microsoft.com/schema/price-and-availability-private-offer-plan/ 2023-07-15 https://schema.mp.microsoft.com/schema/price-and-availability-private-offer-plan/ 2025-06-01 17 de abril de 2026

Cuerpo de la solicitud

Las siguientes opciones reflejan las opciones del Centro de partners al crear una oferta privada de varias partes para un cliente. Estas opciones se definen mediante los siguientes valores offerPricingType :

valor de tipo de precio de oferta Equivalente a la opción de creación de ofertas privadas del Centro de partners
editarSoloElPrecioDeUnaOfertaExistente Precios personalizados para planes y ofertas públicas existentes: use esta opción para crear una oferta privada para todos los tipos de ofertas transaccionables: SaaS, Azure Virtual Machines y Azure Applications. Puede personalizar los precios de los asociados a través de precios absolutos o descuentos porcentuales.
SaaS_Nuevos_Planes_Personalizados Personalice los precios, las cantidades de medidores y los límites de usuario para la oferta de SaaS: use esta opción para crear una oferta privada para un plan SaaS personalizando el precio absoluto del socio, los parámetros de medición de las cantidades y los límites de usuario.
vmSoftwareReservations Personalice los precios y las cantidades específicas para las ofertas de reserva de software de máquina virtual: use esta opción para crear una oferta privada de varias partes para vender reservas de software de máquina virtual (1 o 3 años) y personalizar el precio absoluto del asociado, el tamaño de vCPU, las cantidades, la duración y la programación de pago.

Para las tres opciones de tipo de precios anteriores, los requisitos de recursos específicos del plan pueden variar. Para obtener más información, consulte la tabla siguiente:

Nombre del recurso editarSoloElPrecioDeUnaOfertaExistente SaaS_Nuevos_Planes_Personalizados vmSoftwareReservations
Plan de Precios Establézcalo en el identificador de plan del plan público que se va a configurar en el cuerpo de la solicitud. No aplicable No aplicable
precios.basePlan No aplicable Establézcalo en el identificador de plan del plan público que se va a configurar en el cuerpo de la solicitud. Establézcalo en el identificador de plan del plan público que se va a configurar en el cuerpo de la solicitud.
pricing.newPlanDetails.name No aplicable Establézcalo en el nombre del nuevo plan que se mostrará al cliente en el cuerpo de la solicitud. No aplica al cuerpo de la solicitud, será generado por el sistema y estará disponible en la respuesta del trabajo cuando se complete.
Descripción del nuevo plan de precios No aplicable Configúralo en la descripción que se mostrará al cliente para el nuevo plan en el cuerpo del pedido. No es aplicable al cuerpo de la solicitud, será generado por el sistema y estará disponible en la respuesta del trabajo cuando se complete.
valor renovaciónContratoCliente Descripción
cierto La oferta privada es una renovación de un contrato de cliente existente. Se aplica una tarifa de agencia con descuento del 50 % a su oferta privada para las renovaciones de clientes
falso La oferta privada no es una renovación de un contrato de cliente existente. Se aplica la tarifa estándar de la agencia.

El cuerpo de la solicitud varía en función del rol del solicitante. Use privateOfferType para distinguir al originador de la llamada MPO del originador de llamada del asociado de canal.

Rol del llamante valor de privateOfferType
Empresa de software (Originor) multipartyPromotionOriginator
Asociado de canal multipartyPromotionChannelPartner

Muestras del cuerpo de la solicitud

Cuerpo de solicitud de ejemplo de una empresa de software para crear una oferta privada aplicando precios con descuento exclusivamente para el plan público existente

La empresa de software (o el originador de MPO) está obligada a proporcionar todos los detalles fundamentales de la oferta privada para múltiples partes. Debe incluir un nombre.

{
 "$schema": "https://schema.mp.microsoft.com/schema/configure/2022-07-01",
  "resources": [ 
    {
       "$schema": "https://schema.mp.microsoft.com/schema/private-offer/2026-02-01", 
"resourceName": "privateOffer",
       "name": "privateOffercustomer1705",
       "state": "live",
       "privateOfferType": "multipartyPromotionOriginator",
       "offerPricingType": "editExistingOfferPricingOnly",
       "customerContractRenewal": false, 
       "variableStartDate": true,
       "end": "2022-01-31",
       "acceptBy": "2022-02-28",
"termsAndConditionsDocs": [
                {
                    "sasUrl": "https://promotionpmeprod.blob.core.windows.net/promotionsblobdata/44c2b38a-fa64-4861-806c-6c486ec19b6d-769f3960-45af-42db-ab3b-6391841683d6",
                    "fileName": "Test1.pdf",
                    "customerFacingDocumentName": "Test1 T&C"
                }            ],
       "notificationContacts": [ "[email protected]" ],
       "beneficiaries": [ 
          { "id": "xxxxxx-2163-5eea-ae4e-d6e88627c26b:6ea018a9-da9d-4eae-8610-22b51ebe260b_2019-05-31", "description": "Top First Customer"}
       ], 
"partners": [
                {
                    "id": "12345678",
                    "partnerName": "Market Place Test",
                    "location": "United States"
                }
            ],
       "pricing": [ 
          { "product": "product/34771906-9711-4196-9f60-4af380fd5042", "plan":"plan/123456","discountType": "percentage", "discountPercentage": 5 }
       ],
"notes": "sample 123"
    }
  ]
}

Cuerpo de solicitud de ejemplo con precios absolutos para personalizar los precios solo para el plan público existente

Si usa precios absolutos en lugar de descuento basado en porcentajes, puede crear un nuevo recurso encima del recurso de oferta privada de varias partes que define los precios absolutos, incluya ese recurso recién creado como otro objeto en la lista de recursos del esquema de configuración.

Use este método para obtener el recurso de precios del plan público existente, editar los precios y, a continuación, usar el recurso editado para la oferta.

GET https://graph.microsoft.com/rp/product-ingestion/price-and-availability-private-offer-plan/{productId}?plan={planId}&$version=2025-06-01

Ejemplo de recurso de precios absolutos

{
    "$schema": "https://schema.mp.microsoft.com/schema/price-and-availability-private-offer-plan/2025-06-01",
    "resourceName": "newSimpleAbsolutePricing",
    "product": "product/7ba807c8-386a-4efe-80f1-b97bf8a554f8",
    "plan": "plan/987654",
    "offerPricingType": "editExistingOfferPricingOnly",
    "pricing": {
        "recurrentPrice": {
            "priceInputOption": "usd",
            "prices": [
                {
                    "pricePerPaymentInUsd": 1,
                    "billingTerm": {
                        "type": "month",
                        "value": 1
                    }
                },
                {
                    "pricePerPaymentInUsd": 2,
                    "paymentOption": {
                        "type": "month",
                        "value": 1
                    },
                    "billingTerm": {
                        "type": "year",
                        "value": 1
                    }
                }
            ]
        },
        "customMeters": {
            "priceInputOption": "usd",
            "meters": {
                "meter1": {
                    "pricePerPaymentInUsd": 1
                }
            }
        }
    }
}

Incluir ese recurso como un objeto en el módulo de precios

[
    {
        "product": "product/34771906-9711-4196-9f60-4af380fd5042",
        "plan": "plan/123456",
        "discountType": "percentage",
        "discountPercentage": 5
    },
    {
        "product": "product/7ba807c8-386a-4efe-80f1-b97bf8a554f8",
        "plan": "plan/987654",
        "discountType": "absolute",
        "priceDetails": {
            "resourceName": "newSimpleAbsolutePricing"
        }
    }
]

Cuerpo de solicitud de ejemplo que utiliza precios absolutos para personalizar los precios, cuantificar cantidades y establecer límites de usuario para la oferta de SaaS.

Use el método siguiente para crear un recurso absoluto de precio y disponibilidad para la oferta privada.

GET https://graph.microsoft.com/rp/product-ingestion/price-and-availability-private-offer-plan/{productId}?plan={planId}&$version=2025-06-01

Ejemplo de recurso de precios absoluto para una oferta SaaS de tarifa plana que personaliza el precio y las cantidades de medidores.

{
    "$schema": "https://schema.mp.microsoft.com/schema/price-and-availability-private-offer-plan/2025-06-01",
    "product": "product/7ba807c8-386a-4efe-80f1-b97bf8a554f8",
    "resourceName": "newSaaSPlanAbsolutePricing",
    "plan": "plan/123456",
    "offerPricingType": "saasNewCustomizedPlans",
    "pricing": {
        "recurrentPrice": {
            "recurrentPriceMode": "flatRate",
            "priceInputOption": "usd",
            "prices": [
                {
                    "billingTerm": {
                        "type": "month",
                        "value": 1
                    },
                    "paymentOption": {
                        "type": "month",
                        "value": 1
                    },
                    "pricePerPaymentInUsd": 0.1
                },
                {
                    "billingTerm": {
                        "type": "year",
                        "value": 1
                    },
                    "paymentOption": {
                        "type": "month",
                        "value": 1
                    },
                    "pricePerPaymentInUsd": 0.12
                }
            ]
        },
        "customMeters": {
            "priceInputOption": "usd",
            "meters": {
                "meter1": {
                    "includedQuantities": [
                        {
                            "billingTerm": {
                                "type": "month",
                                "value": 1
                            },
               "quantity": 10.0,
                            "isInfinite": false
                        },
                        {
                            "billingTerm": {
                                "type": "year",
                                "value": 1
                            },
               "quantity": 15.0,
                            "isInfinite": false
                        }
                    ]
                },
                "meter2": {
                    "includedQuantities": [
                        {
                            "billingTerm": {
                                "type": "month",
                                "value": 1
                            },
                            "isInfinite": true
                        },
                        {
                            "billingTerm": {
                                "type": "year",
                                "value": 1
                            },
                            "isInfinite": true
                        }
                    ]
                }
            }
        }
    }
}

Recurso de precios absoluto de ejemplo para una oferta de SaaS por usuario que personaliza los límites de precios y usuarios

{
    "$schema": "https://schema.mp.microsoft.com/schema/price-and-availability-private-offer-plan/2025-06-01",
    "resourceName": "newSaaSPlanAbsolutePricing",
    "product": "product/7ba807c8-386a-4efe-80f1-b97bf8a554f8",
    "plan": "plan/123456",
    "offerPricingType": "saasNewCustomizedPlans",
    "pricing": {
        "recurrentPrice": {
            "recurrentPriceMode": "perUser",
            "priceInputOption": "usd",
            "userLimits": {
                "min": 20,
                "max": 100
            },
            "prices": [
                {
                    "billingTerm": {
                        "type": "month",
                        "value": 1
                    },
                    "paymentOption": {
                        "type": "month",
                        "value": 1
                    },
                    "pricePerPaymentInUsd": 0.01
                },
                {
                    "billingTerm": {
                        "type": "year",
                        "value": 1
                    },
                    "paymentOption": {
                        "type": "year",
                        "value": 1
                    },
                    "pricePerPaymentInUsd": 0.02
                }
            ]
        }
    }
}

Incluir ese recurso como un objeto en el módulo de precios


{
 "$schema": "https://schema.mp.microsoft.com/schema/configure/2022-07-01",
  "resources": [ 
    {
       "$schema": "https://schema.mp.microsoft.com/schema/private-offer/2026-02-01", 
       "name": "privateOffercustomer1705",
       "state": "live",
       "privateOfferType": "multipartyPromotionOriginator",
       "offerPricingType": "newSimpleAbsolutePricing",
       "customerContractRenewal": false,
       "variableStartDate": true,
       "end": "2022-01-31",
       "acceptBy": "2022-02-28",
       "partners": [
         {
            "id": "12345678",
            "partnerName": "Market Place Test",
            "location": "United States"
         }
        ],
       "termsAndConditionsDocs": [
        {
             "sasUrl": "https://promotionpmeprod.blob.core.windows.net/promotionsblobdata/44c2b38a-fa64-4861-806c-6c486ec19b6d-769f3960-45af-42db-ab3b-6391841683d6",
             "fileName": "Test1.pdf",
             "customerFacingDocumentName": "Test1 T&C"
        }            ],
       "notificationContacts": [ "[email protected]" ],
       "beneficiaries": [ 
          { "id": "xxxxxx-2163-5eea-ae4e-d6e88627c26b:6ea018a9-da9d-4eae-8610-22b51ebe260b_2019-05-31", "description": "Top First Customer"}
       ], 
       "pricing": [ 
          {
           "product": "product/7ba807c8-386a-4efe-80f1-b97bf8a554f8",
           "discountType": "absolute",
           "priceDetails": {
              "resourceName": "newSaaSPlanAbsolutePricing"
             }
           "basePlan": "plan/123456",
                "newPlanDetails": {
                "name": "newPlanName",
                "description": "newPlanDescription"
             }
        ],
 "notes": "sample 123"
     }
  ]
}

Cuerpo de solicitud de muestra usando precios absolutos para personalizar los precios y cantidades específicas para las ofertas de reserva de software de máquina virtual.

Use el método siguiente para crear un recurso absoluto de precio y disponibilidad para la oferta.

GET https://graph.microsoft.com/rp/product-ingestion/price-and-availability-private-offer-plan/{productId}?plan={planId}&$version=2025-06-01

Recurso de muestra de precios absolutos para una oferta de máquina virtual que permite personalizar el precio y las cantidades

{
    "$schema": "https://schema.mp.microsoft.com/schema/price-and-availability-private-offer-plan/2025-06-01",
    "resourceName": "newVMSRAbsolutePricing",
    "product": "product/7ba807c8-386a-4efe-80f1-b97bf8a554f8",
    "offerPricingType": "vmSoftwareReservations",
    "plan": "plan/987654",
    "softwareReservation": {
        "reservationDuration": {
            "type": "year",
            "value": 1
         },
        "paymentSchedule": {
            "type": "year",
            "value": 1
         },
        "vmPrices": {
            "36Core": {
                "quantity": 4.0,
                "unitPricePerPaymentPeriodInUsd": 0.04
            }
        }
    }       
}

Cuerpo de solicitud de ejemplo para personalizar reservas de software SaaS y VM con programaciones de facturación flexibles

Para crear una oferta privada de varias partes con una programación de facturación flexible, consulte el cuerpo de la solicitud de ejemplo para los siguientes escenarios aplicables:

Nota:

Los planes de servicios profesionales no son elegibles actualmente para vender a través de ofertas privadas de varias partes. Los proveedores de servicios pueden crear una oferta privada para vender servicios profesionales aptos directamente a su cliente. Consulte Ejemplo de cuerpo de solicitud para personalizar los precios del servicio profesional con un calendario de facturación flexible.

Incluir ese recurso como un objeto en el módulo de precios

{
 "$schema": "https://schema.mp.microsoft.com/schema/configure/2022-07-01",
  "resources": [ 
    {
       "$schema": "https://schema.mp.microsoft.com/schema/private-offer/2026-02-01", 
       "name": "privateOffercustomer1705",
       "state": "live",
       "privateOfferType": "multipartyPromotionOriginator",
       "offerPricingType": "vmSoftwareReservations",
       "customerContractRenewal": false,
       "variableStartDate": true,
       "end": "2022-01-31",
       "acceptBy": "2022-02-28",
       "partners": [
         {
            "id": "12345678",
            "partnerName": "Market Place Test",
            "location": "United States"
         }
        ],
       "termsAndConditionsDocs": [
        {
             "sasUrl": "https://promotionpmeprod.blob.core.windows.net/promotionsblobdata/44c2b38a-fa64-4861-806c-6c486ec19b6d-769f3960-45af-42db-ab3b-6391841683d6",
             "fileName": "Test1.pdf",
             "customerFacingDocumentName": "Test1 T&C"
        }            ],
       "notificationContacts": [ "[email protected]" ],
       "beneficiaries": [ 
          { "id": "xxxxxx-2163-5eea-ae4e-d6e88627c26b:6ea018a9-da9d-4eae-8610-22b51ebe260b_2019-05-31", "description": "Top First Customer"}
       ], 
       "pricing": [ 
          {
           "product": "product/7ba807c8-386a-4efe-80f1-b97bf8a554f8",
           "discountType": "absolute",
           "priceDetails": {
              "resourceName": "newVMSRAbsolutePricing"
             }
           "basePlan": "plan/987654"
        ],
 "notes": "sample 123"
     }
  ]
}

Solicitud de ejemplo por parte del asociado para completar la creación de la oferta

El asociado de canal debe usar el identificador de oferta privado de varias partes proporcionado por la empresa de software para configurar el porcentaje de ajuste del cliente (recargo, no margen), los acuerdos personalizados del asociado de canal, los cuales son preparados por, y los contactos del asociado de canal.

El ejemplo siguiente se basa en el contenido de la respuesta devuelto al recuperar los detalles de la oferta usando el ID de la oferta.

{
 "$schema": "https://schema.mp.microsoft.com/schema/configure/2022-07-01",
  "resources": [ 
    {
       "$schema": "https://schema.mp.microsoft.com/schema/private-offer/2026-02-01", 
"resourceName": "privateOffer",
       "name": "privateOffercustomer1705",
       "state": "live",
       "privateOfferType": "multipartyPromotionChannelPartner",
       "offerPricingType": "editExistingOfferPricingOnly",
       "variableStartDate": true,
       "end": "2022-01-31",
       "acceptBy": "2022-02-28",
       "preparedBy": "[email protected]",
"originatorTermsAndConditionsDocs": [
                {
                    "sasUrl": "https://promotionpmeprod.blob.core.windows.net/promotionsblobdata/44c2b38a-fa64-4861-806c-6c486ec19b6d-769f3960-45af-42db-ab3b-6391841683d6",
                    "fileName": "Test1.pdf",
                    "customerFacingDocumentName": "Test1 T&C"
                }            ],
"termsAndConditionsDocs": [
                {
                    "sasUrl": "https://promotionpmeprod.blob.core.windows.net/promotionsblobdata/44c2b38a-fa64-4861-806c-6c486ec19b6d-769f3960-45af-42db-ab3b-6391841683d6",
                    "fileName": "Test1.pdf",
                    "customerFacingDocumentName": "Test1 T&C"
                }            ],

       "notificationContacts": [ "[email protected]" ],
       "beneficiaries": [ 
          { "id": "xxxxxx-2163-5eea-ae4e-d6e88627c26b:6ea018a9-da9d-4eae-8610-22b51ebe260b_2019-05-31", "description": "Top First Customer"}
       ], 
"partners": [
                {
                    "id": "12345678",
                    "partnerName": "Market Place Test",
                    "location": "United States"
                }
            ],
       "originatorPricing": [ 
          { 
        "product": "product/34771906-9711-4196-9f60-4af380fd5042",
        "plan":"plan/123456",
        "discountType": "percentage", 
        "discountPercentage": 5 
        "markupPercentage": 1.0
        }
     ],
    "lastModified": "2023-01-19",
        "eTag": "\"7f020249-0000-0800-0000-63c9b4ca0000\"",
    }
  ]
}

Llamadas de clave en el ejemplo anterior

  • El asociado de canal debe proporcionar el atributo preparedBy .
  • Los términos y condiciones personalizados de la empresa de software son visibles, pero el asociado de canal no puede editarlos, están capturados en el recurso originatorTermsAndConditionsDocs.
  • El asociado de canal puede cargar sus propios términos y condiciones personalizados en el recurso termsAndConditionsDocs.
  • El asociado de canal puede agregar sus propios contactos para recibir una notificación de la oferta en el recurso notificationContacts .
  • Los atributos beneficiarios y asociados son visibles, pero el asociado del canal no puede editarlos.
  • El recurso de precios se muestra como originatorPricing, markupPercentage es necesario y debe ser proporcionado por el socio del canal al enviar, todos los demás atributos del recurso de precios son sólo de lectura.

Respuesta

La respuesta contiene el jobId que puede usar más adelante para sondear el estado:

{
    "$schema": "https://schema.mp.microsoft.com/schema/configure-status/2022-07-01",
    "jobId": "c32dd7e8-8619-462d-a96b-0ac1974bace5",
    "jobStatus": "notStarted",
    "jobResult": "pending",
    "jobStart": "2021-12-21T21:29:54.9702903Z",
    "jobEnd": "0001-01-01",
    "errors": []
}

Códigos de error

Código de estado HTTP Descripción
401 Error de autenticación: asegúrese de que usa un token de acceso de Microsoft Entra válido.
400 Validación de esquema. Asegúrese de que el cuerpo de la solicitud sigue el esquema correcto e incluye todos los campos obligatorios.

Contenido relacionado

  • Last updated on