Obter margens

Aplica-se a: Partner Center

Funções apropriadas: Agente de administração

Como parceiro no programa CSP, você pode chamar a API GetMargins para obter uma lista de margens de oferta privadas estendidas a você por editores ISV.

Pré-requisitos

Credenciais conforme descrito na autenticação do Partner Center. Este cenário oferece suporte à autenticação com credenciais autônomas de Aplicativo e Aplicativo+Usuário.

Pedido REST

[GET] /v1/margens

Sintaxe da solicitação

Método	URI do pedido
GET	{baseURL}/v1/margens HTTP/1.1

Cabeçalhos do pedido

Para obter mais informações, consulte Cabeçalhos REST do Partner Center.

Corpo do pedido

Nenhuma

Exemplo de solicitação

GET https://api.partnercenter.microsoft.com/v1/margins HTTP/1.1
Authorization: Bearer <token>
Accept: application/json
MS-RequestId: 18752a69-1aa1-4ef7-8f9d-eb3681b2d70a
MS-CorrelationId: aaaa0000-bb11-2222-33cc-444444dddddd
X-Locale: en-US

Resposta do REST

Se for bem-sucedida, essa solicitação retornará uma lista de margens de oferta privada. O editor ISV pode configurar a margem da oferta privada como um desconto percentual fixo, que é aplicado ao preço original da oferta, ou como um preço personalizado que substitui o preço original da oferta. Ambos os tipos de margem são retornados na resposta da API GetMargins.

Cada item de linha na resposta contém datas de início e fim. A margem de oferta privada só será aplicada em compras realizadas dentro dessas duas datas. As compras feitas fora desse período de tempo não terão o benefício da margem de oferta privada.

Códigos de sucesso e erro de resposta

Cada resposta vem com um código de status HTTP que indica sucesso ou falha e mais informações de depuração. Use uma ferramenta de rastreamento de rede para ler esse código, tipo de erro e mais parâmetros. Para obter a lista completa, consulte Códigos de erro.

Exemplos de respostas

Margem de oferta privada baseada em percentagem

Neste exemplo, o editor ISV configurou a margem da oferta privada como um desconto percentual fixo em relação ao preço original da oferta. O desconto é mostrado na propriedade "percentageMargin". Como essa oferta privada é estendida para uma SKU específica, as informações da SKU, como o nome da SKU e a ID da SKU, são especificadas. Se o editor do ISV optasse por estender a oferta privada para todas as SKUs, essas informações não seriam especificadas.

Response

HTTP/1.1 200 OK
Content-Type: application/json
MS-CorrelationId: aaaa0000-bb11-2222-33cc-444444dddddd
MS-RequestId: 18752a69-1aa1-4ef7-8f9d-eb3681b2d70a
{
"pageSize": 1,
"totalSize": 1,
"results": [
{
      "id": "1aa125798b04_01a14813-f6d1-494a-ace1-b84525cf3db4",
      "type": "Percentage",
      "productId": "DZH318Z0HJ49",
      "publisherName": "Test Publisher Name",
      "productTitle": "Test Offer Beta",
      "skuTitle": "Test Offer Beta SKU 1",
      "skuId": "0001",
      "productType": "SaaS",
      "marginPercentage": 10.0,
      "startDate": "2022-02-24T18:38:02.8104364Z",
      "endDate": "2022-04-30T23:59:59Z",
      "status": "live",
      "statusDate": "2022-02-24T18:38:02.8104364Z"
}
]
}

Preço personalizado margem de oferta privada

Neste exemplo, o editor de ISV configurou a margem de oferta privada como um preço personalizado que substitui o preço original de sua solução SaaS por medidores personalizados. Em vez de uma propriedade marginPercentage como no exemplo anterior, esse item de linha contém uma propriedade priceConfiguration que contém os detalhes da definição de preço personalizada.

O pricingModel neste exemplo é listado como um modelo de "taxa fixa", o que significa que você paga um valor definido por termo. Se o ISV estiver cobrando um valor definido por usuário, o pricingModel diria "por usuário".

A matriz "compra" contém os detalhes de preços para cada duração do período. O ISV neste exemplo configurou apenas uma duração de termo "Mensal", mas a matriz "compra" também pode conter uma duração de termo "Anual". Dentro da configuração de compra para um determinado termo, includedMeterQuantities indica os valores para cada medidor personalizado que estão incluídos no preço. Como o editor de ISV pode configurar diferentes pontos de preço para diferentes mercados de clientes, a matriz marketSetPrices contém o preço personalizado para cada mercado e moeda em que a oferta privada está disponível. Neste exemplo, a taxa fixa de 448,75262 GPB para um cliente no mercado GB (Reino Unido) inclui 20 dispositivos e 30.000 e-mails por mês.

A matriz "consumo" contém as informações de preços excedentes para cada medidor personalizado. Se o produto do ISV não tiver medidores personalizados, essa matriz estará vazia. Você notará que a matriz de consumo contém um item de linha para cada medidor personalizado listado em "includedMeterQuantities". Neste exemplo, se consumir mais de 20 dispositivos por mês, pagará 0,44729 GBP adicional por 1 dispositivo adicional por mês. Se você consumir mais de 30.000 e-mails, você pagaria 0,38765 GBP por 100 e-mails adicionais por mês.

Response

HTTP/1.1 200 OK
Content-Type: application/json
MS-CorrelationId: aaaa0000-bb11-2222-33cc-444444dddddd
MS-RequestId: 18752a69-1aa1-4ef7-8f9d-eb3681b2d70a
{
"pageSize": 1,
"totalSize": 1,
"results": [
{
      "id": "15680381dbad_fe3f0bc2-6372-48af-bbec-2df83918dbf2",
      "type": "CustomPrice",
      "productId": "DZH318Z0BDGN",
      "publisherName": "Test Publisher Name",
      "productTitle": "Test Offer Gamma",
      "skuTitle": "Test Offer Gamma SKU 1",
      "skuId": "0001",
      "productType": "SaaS",
      "priceConfiguration": {
        "pricingModel": "Flat rate",
        "purchase": [
          {
            "termDuration": "Monthly",
            "includedMeterQuantities": [
              "20 device",
              "30000 email"
            ],
            "startDate": "2022-01-31T17:49:25.1346812Z",
            "endDate": "2028-08-31T23:59:59Z",
            "marketSetPrices": [
              {
                "markets": [
                  "GB"
                ],
                "currency": "GBP",
                "customPrice": 447.29387
              },
              {
                "markets": [
                  "BG",
                  "FI",
                  "IT",
                  "RO"
                ],
                "currency": "GBP",
                "customPrice": 448.75262
              }
            ]
          }
        ],
        "consumption": [
          {
            "meterType": "device",
            "unitofMeasure": "per 1 device",
            "startDate": "2022-01-01T00:00:00Z",
            "endDate": "2028-08-31T23:59:59Z",
            "marketSetPrices": [
              {
                "markets": [
                  "GB"
                ],
                "currency": "GBP",
                "customPrice": 0.44729
              },
              {
                "markets": [
                  "BG",
                  "FI",
                  "IT",
                  "RO"
                ],
                "currency": "GBP",
                "customPrice": 0.44875
              }
            ]
          },
          {
            "meterType": "email",
            "unitofMeasure": "per 100 emails",
            "startDate": "2022-01-01T00:00:00Z",
            "endDate": "2028-08-31T23:59:59Z",
            "marketSetPrices": [
              {
                "markets": [
                  "GB"
                ],
                "currency": "GBP",
                "customPrice": 0.38765
              },
              {
                "markets": [
                  "BG",
                  "FI",
                  "IT",
                  "RO"
                ],
                "currency": "GBP",
                "customPrice": 0.38892
              }
            ]
          }
        ]
      },
      "startDate": "2022-01-31T17:49:25.1346812Z",
      "endDate": "2028-08-31T23:59:59Z",
      "status": "live",
      "statusDate": "2022-01-31T17:49:25.1346812Z"
    }
  ]
}

O exemplo acima deve resultar no seguinte.