创建引荐

项目
08/12/2024

本文介绍如何创建引荐。

先决条件

引荐 API 身份验证中所述的凭据。此方案支持使用应用凭据和用户凭据进行身份验证。

REST 请求

请求语法

方法	请求 URI
POST	`https://api.partner.microsoft.com/v1.0/engagements/referrals`

请求标头

有关详细信息，请参阅 Partner API REST headers（合作伙伴 API REST 标头）。

请求正文

下表说明了请求正文中适用于全新引荐的引荐属性。

properties	类型	说明
名称	string	引荐的名称。
ExternalReferenceID	string	引荐的外部标识符。例如，你自己的 Dynamics 365 潜在客户或机会 ID。
Status	ReferralStatus	一个 Enum，其值指示引荐状态。
子状态	ReferralSubstatus	一个 Enum，其值指示引荐子状态。
StatusReason	string	一条有关状态的说明性消息。例如，说明为什么丢失了引荐。
ReferralType	ReferralType	表示引荐类型。必需。
资格授予	ReferralQualification	表示引荐的质量。
CustomerProfile	CustomerProfile	客户联系人信息。必需。
同意	同意	如果要与其他组织共享信息并允许其联系用户，则使用许可标记。必填。
详细信息	ReferralDetails	客户详细信息、说明、交易值、货币结账日期。必需。
组	成员	表示涉及合作伙伴参与计划的组织中的用户。
InviteContext	InviteContext	表示用户在邀请另一个组织参与合作伙伴时可以提供的详细信息。
目标	ReferralTarget	表示用户在邀请另一个组织参与合作伙伴时可以提供的详细信息。
合作伙伴角色	PartnerRole	仅服务联合销售引荐所必需的
解决方案领域	SolutionArea	客户在机会中需要的解决方案区域。仅服务联合销售引荐所必需的
解决方案播放	SolutionPlay	客户在机会中需要的解决方案发挥。仅服务联合销售引荐所必需的

请求示例

重要

此示例请求介绍如何使用所需的最少信息创建专用引荐。请注意，使此引荐成为私人交易的关键参数是 consentToShareReferralWithMicrosoftSellers。

POST https://api.partner.microsoft.com/v1.0/engagements/referrals HTTP/1.1
Authorization: Bearer <token>
Host: api.partner.microsoft.com
Content-Type: application/json

 {
	"name": "Contoso Test Deal - [Private]",
	"qualification": "SalesQualified",
	"type": "Independent",
	"customerProfile": {
		"name": "Contoso Customer Inc",
		"address": {
			"addressLine1": "One Microsoft Way",
			"addressLine2": "34",
			"city": "Redmond",
			"state": "WA",
			"postalCode": "98052",
			"country": "US"
		},
		"size": "10to50employees",
		"team": [
			{
				"firstName": "Sue",
				"lastName": "Smith",
				"phoneNumber": "1234567890",
				"email": "sue.smith@contosocustomer.com"
			}
		]
	},
	"consent": {
		"ConsentToToShareInfoWithOthers": true,
		"ConsentToContact": true,
		"ConsentToMicrosoftToContactSpecificPartners": true,
		"consentToShareReferralWithMicrosoftSellers": false
	},
	"details": {
		"notes": "Customer is looking to leverage Dynamics 365 to manage their supply chain. There's also a need to leverage a set of custom apps to enable their business processes.",
		"dealValue": 50000,
		"currency": "USD",
		"closingDateTime": "2024-11-14T00:00:00Z",
		"requirements": {
			"solutions": [
				{
					"type": "Name",
					"id": "SOL-15974-MQF",
					"name": "Contoso-Ale_Test",
					"publisherName": "Contoso_Test",
					"solutionType": "3P"
				}
			],
			"additionalRequirements": {
				"iot": {},
				"attributes": [
					{
						"id": "HaveNotDecided",
						"type": "CustomerMarketplaceIntent"
					}
				]
			}
		}
	},
	"team": [
		{
			"firstName": "John",
			"lastName": "Doe",
			"phoneNumber": "1231231234",
			"email": "john.doe@contoso.com"
		}
	],
	"target": [],
	"mpnId": "<ENTER PARTNER_ID>"
}

REST 响应

如果成功，此方法会在响应正文中返回填充的引荐资源。

响应的成功和错误代码

每个响应都有一个 HTTP 状态代码，指示成功或失败以及更多的调试信息。使用网络跟踪工具读取此代码、错误类型和其他参数。有关完整列表，请参阅错误代码。

响应示例

{
	"id": "4eb82669-ccf8-4856-86fc-b9ffe116376b",
	"engagementId": "6d72b13d-8584-4bba-a642-6800b8e32330",
	"name": "Contoso Test Deal - [Private]",
	"organizationId": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
	"organizationName": "Contoso Pvt Ltd",
	"lastModifiedVia": "4990cffe-04e8-4e8b-808a-1175604b879f",
	"target": [],
	"createdDateTime": "2024-07-27T14:57:00.0952954Z",
	"updatedDateTime": "2024-07-27T14:57:00.0952954Z",
	"status": "Active",
	"substatus": "Accepted",
	"qualification": "SalesQualified",
	"type": "Independent",
	"customerProfile": {
		"name": "Contoso Customer Inc",
		"address": {
			"addressLine1": "One Microsoft Way",
			"addressLine2": "34",
			"city": "Redmond",
			"state": "WA",
			"postalCode": "98052",
			"country": "US"
		},
		"size": "10to50employees",
		"team": [
			{
				"contactPreference": {
					"locale": "en-us",
					"disableNotifications": false
				},
				"firstName": "Sue",
				"lastName": "Smith",
				"phoneNumber": "1234567890",
				"email": "sue.smith@contosocustomer.com",
				"emailValidationStatus": "None",
				"phoneValidationStatus": "None"
			}
		],
		"ids": [],
		"isMatchingComplete": false
	},
	"consent": {
		"consentToToShareInfoWithOthers": true,
		"consentToContact": true,
		"ConsentToMicrosoftToContactSpecificPartners": true,
		"consentToShareReferralWithMicrosoftSellers": false
	},
	"details": {
		"notes": "Customer is looking to leverage Dynamics 365 to manage their supply chain. There's also a need to leverage a set of custom apps to enable their business processes.",
		"dealValue": 50000.0,
		"currency": "USD",
		"closingDateTime": "2024-11-14T00:00:00Z",
		"requirements": {
			"industries": [],
			"products": [],
			"services": [],
			"solutions": [
				{
					"name": "Contoso-Ale_Test",
					"type": "Name",
					"publisherName": "Contoso_Test",
					"solutionType": "3P",
					"id": "SOL-15974-MQF"
				}
			],
			"additionalRequirements": {
				"iot": {
					"azureCertifiedDevice": false,
					"attachServices": false
				},
				"attributes": [
					{
						"type": "CustomerMarketplaceIntent",
						"id": "HaveNotDecided"
					}
				]
			}
		}
	},
	"team": [
		{
			"contactPreference": {
				"locale": "en-us",
				"disableNotifications": false
			},
			"firstName": "John",
			"lastName": "Doe",
			"phoneNumber": "1231231234",
			"email": "john.doe@contoso.com",
			"emailValidationStatus": "None",
			"phoneValidationStatus": "None"
		}
	],
	"inviteContext": {
		"invitedBy": {
			"organizationId": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
			"organizationName": "Contoso Pvt Ltd"
		},
		"assistanceRequestCode": "Unknown",
		"invitedMpnId": "<PARTNER_ID>"
	},
	"favorite": false,
	"trackingInfo": {},
	"direction": "Outgoing",
	"mpnId": "<PARTNER_ID>",
	"dealSensitivity": "None",
	"createdVia": "4990cffe-04e8-4e8b-808a-1175604b879f",
	"acceptedDateTime": "2024-07-27T14:56:59.2938209Z",
	"registrationStatus": "None",
	"links": {
		"relatedReferrals": {
			"uri": "https://api.partner.microsoft.com/v1.0/engagments/referrals?$filter=engagementId eq '6d72b13d-8584-4bba-a642-6800b8e32330'",
			"method": "GET"
		},
		"self": {
			"uri": "https://api.partner.microsoft.com/v1.0/engagments/referrals/4eb82669-ccf8-4856-86fc-b9ffe116376b",
			"method": "GET"
		}
	}
}

创建联合销售交易或共享引荐

创建共享引荐类型的联合销售交易或引荐有两个步骤：

创建对Microsoft卖家可见的合作伙伴主导的交易
使用合作伙伴引荐详细信息创建Microsoft引荐

以程图演示了创建共享引荐的这两个步骤。

显示通过 API 连接的两个引荐的共享引荐的流程图。

步骤 1：创建对Microsoft卖家可见的合作伙伴主导的交易

首先，使用以下请求有效负载创建对Microsoft卖家可见的合作伙伴主导的交易。

重要

请注意，若要使引荐合作伙伴主导， consentToShareReferralWithMicrosoftSellers 提供为 true。只需更新此字段的引荐即可将活动的专用引荐转换为合作伙伴主导的引荐。

POST https://api.partner.microsoft.com/v1.0/engagements/referrals HTTP/1.1
Authorization: Bearer <token>
Host: api.partner.microsoft.com
Content-Type: application/json

 {
	"name": "Contoso Test Deal - [PartnerLed]",
	"qualification": "SalesQualified",
	"type": "Shared",
	"customerProfile": {
		"name": "Contoso Customer Inc",
		"address": {
			"addressLine1": "One Microsoft Way",
			"addressLine2": "34",
			"city": "Redmond",
			"state": "WA",
			"postalCode": "98052",
			"country": "US"
		},
		"size": "10to50employees",
		"team": [
			{
				"firstName": "Sue",
				"lastName": "Smith",
				"phoneNumber": "1234567890",
				"email": "sue.smith@contosocustomer.com"
			}
		]
	},
	"consent": {
		"ConsentToToShareInfoWithOthers": true,
		"ConsentToContact": true,
		"ConsentToMicrosoftToContactSpecificPartners": true,
		"consentToShareReferralWithMicrosoftSellers": true
	},
	"details": {
		"notes": "Customer is looking to leverage Dynamics 365 to manage their supply chain. There's also a need to leverage a set of custom apps to enable their business processes.",
		"dealValue": 50000,
		"currency": "USD",
		"closingDateTime": "2024-11-14T00:00:00Z",
		"requirements": {
			"solutions": [
				{
					"type": "Name",
					"id": "SOL-15974-MQF",
					"name": "Contoso-Ale_Test",
					"publisherName": "Contoso_Test",
					"solutionType": "3P"
				}
			],
			"additionalRequirements": {
				"iot": {},
				"attributes": [
					{
						"id": "HaveNotDecided",
						"type": "CustomerMarketplaceIntent"
					}
				]
			}
		}
	},
	"team": [
		{
			"firstName": "John",
			"lastName": "Doe",
			"phoneNumber": "1231231234",
			"email": "john.doe@contoso.com"
		}
	],
	"target": [],
	"mpnId": "<ENTER PARTNER_ID>"
}

ReferralTarget 表示合作伙伴在邀请其他组织参与时可以提供的其他信息。若要在 SolutionProfile 类型的引荐中指定“target”，下面是一个参考示例值：

"target": [
        {
            "type": "SolutionProfile",
            "id": "SOL-ABC-DEF"
        }
    ]

注意

在请求输入中作为独立或共享提供的字段类型只是一个指示性值，并且不会影响交易类型。基于同意和 inviteContext 等其他参数在 API 中分配的实际值。

步骤 2：使用合作伙伴引荐详细信息创建Microsoft引荐

然后，通过另一个 API 调用创建Microsoft引荐，并使用步骤 1 返回的 参与 ID 字段将其链接到合作伙伴引荐。

POST https://api.partner.microsoft.com/v1.0/engagements/referrals HTTP/1.1
Authorization: Bearer <token>
Host: api.partner.microsoft.com
Content-Type: application/json

{
    "engagementId": "<ENGAGEMENT_ID (FROM PARTNER REFERRAL)>",
    "organizationId": "msft",
    "organizationName": "Microsoft",
    "name": "Contoso Test Deal",
    "type": "Shared",
    "qualification": "SalesQualified",
    "customerProfile": {
		"name": "Contoso Customer Inc",
		"address": {
			"addressLine1": "One Microsoft Way",
			"addressLine2": "34",
			"city": "Redmond",
			"state": "WA",
			"postalCode": "98052",
			"country": "US"
		},
		"size": "10to50employees",
		"team": [
			{
				"firstName": "Sue",
				"lastName": "Smith",
				"phoneNumber": "1234567890",
				"email": "sue.smith@contosocustomer.com",
				"emailValidationStatus": "None",
				"phoneValidationStatus": "None"
			}
		],
		"isMatchingComplete": false
	},
    "consent": {
        "consentToToShareInfoWithOthers": true,
        "consentToContact": true,
        "ConsentToMicrosoftToContactSpecificPartners": true,
        "consentToShareReferralWithMicrosoftSellers": true
    },
    "details": {
        "notes": "Test notes to Microsoft.",
        "dealValue": 50000.0,
	"currency": "USD",
        "closingDateTime": "2024-11-14T00:00:00Z"
    },
    "team": [],
    "inviteContext": {
        "notes": "Proof of concept / Demo , Test notes to Microsoft.",
        "invitedBy": {
            "organizationId": "<ORGANIZATION_ID (FROM PARTNER REFERRAL)>",
            "organizationName": "<ORGANIZATION_NAME (FROM PARTNER REFERRAL)>"
        },
        "assistanceRequestCode": "ProofOfConceptOrDemo"
    },
    "target": []
}

若要为Microsoft引用指定 ReferralTarget ，下面是一个参考示例值：

"target": [
        {
            "type": "BusinessProfileLocation",
            "id": "msft"
        }
    ]

创建服务联合销售机会

若要创建服务联合销售机会，必须在详细信息>要求>中提供 PartnerRole、SolutionArea 和 SolutionPlay。
解决方案详细信息在服务联合销售机会中是可选的。

"details": {
		"dealValue": 123456,
		"currency": "USD",
		"closingDateTime": "2025-01-21T18:30:00.000Z",
		"notes": "Test Notes",
		"requirements": {
			"solutions": [],
			"additionalRequirements": {
				"attributes": [
					{
						"id": "Adoption and change management",
						"type": "PartnerRole"
					},
					{
						"id": "Data and AI",
						"type": "SolutionArea"
					},
					{
						"id": "Enable Unified Data Governance",
						"type": "SolutionPlay"
					}
				]
			}
		}
	}

Referral resources（引荐资源）

通过

创建引荐

先决条件

REST 请求

请求语法

请求标头

请求正文

请求示例

REST 响应

响应的成功和错误代码

响应示例

创建联合销售交易或共享引荐

步骤 1：创建对Microsoft卖家可见的合作伙伴主导的交易

步骤 2：使用合作伙伴引荐详细信息创建Microsoft引荐

创建服务联合销售机会

反馈

其他资源

通过

创建引荐

先决条件

REST 请求

请求语法

请求标头

请求正文

请求示例

REST 响应

响应的成功和错误代码

响应示例

创建联合销售交易或共享引荐

步骤 1：创建对Microsoft卖家可见的合作伙伴主导的交易

步骤 2：使用合作伙伴引荐详细信息创建Microsoft引荐

创建服务联合销售机会

相关内容

反馈

其他资源