Obter margens

Aplica-se a: Partner Center

Funções apropriadas: Agente administrativo

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

Pré-requisitos

Credenciais, conforme descrito em Autenticação do Partner Center. Esse cenário dá suporte à autenticação com credenciais autônomas de Aplicativo e Aplicativo+Usuário.

Solicitação REST

[GET] /v1/margens

Sintaxe da solicitação

Método	URI da solicitação
GET	{baseURL}/v1/margens HTTP/1.1

Cabeçalhos da solicitação

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

Corpo da solicitação

Nenhum

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 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 término. A margem da oferta privada só será aplicada em compras feitas dentro dessas duas datas. As compras feitas fora desse período não terão o benefício da margem da oferta privada.

Códigos de êxito e de erro de resposta

Cada resposta vem com um código de status HTTP que indica êxito 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, confira Códigos de Erro.

Exemplos de respostas

Margem de oferta privada baseada em porcentagem

Neste exemplo, o editor ISV configurou a margem da oferta privada como um desconto percentual fixo do preço original da oferta. O desconto é mostrado na propriedade "percentageMargin". Como essa oferta privada é estendida para um SKU específico, as informações de SKU, como nome e ID do SKU, são especificadas. Se o editor ISV optar por estender a oferta privada para todos os SKUs, essas informações não serão especificadas.

Resposta

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"
}
]
}

Margem de oferta privada de preço personalizado

Neste exemplo, o editor 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 do preço personalizado.

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

A matriz "purchase" contém os detalhes de preços para cada duração do prazo. O ISV neste exemplo configurou apenas uma duração de prazo "Mensal", mas a matriz "purchase" também pode conter uma duração de prazo "Anual". Na configuração de compra para um determinado prazo, includedMeterQuantities indica os valores de cada medidor personalizado incluídos no preço. Como o editor 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 emails por mês.

A matriz "consumption" 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ê observará que a matriz de consumo contém um item de linha para cada medidor personalizado listado em "includedMeterQuantities". Neste exemplo, se você consumir mais de 20 dispositivos por mês, pagará um adicional de 0,44729 GBP por 1 dispositivo adicional por mês. Se você consumir mais de 30.000 e-mails, pagará 0,38765 libras esterlinas por 100 e-mails adicionais por mês.

Resposta

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.