建立轉介

發行項
03/07/2025

本文說明如何建立轉介。

必要條件

在轉介 API 驗證中所述的憑證。此案例支援使用應用程式加上使用者的認證來進行驗證。

REST 要求

要求語法

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

要求標頭

如需詳細資訊，請參閱合作夥伴 API REST 標頭。

請求正文

下表描述了全新品牌轉介的請求主體中的轉介屬性。

屬性	類型	描述
Name	字串	轉介的名稱。
外部參考編號	字串	轉介的外部識別碼。例如，您自己的 Dynamics 365 潛在客戶或商機識別碼。
狀態	推薦狀態	具有可指示轉介狀態的值的Enum列舉。
子狀態	Referral子狀態（ReferralSubstatus）	一個有值的列舉型別，用於指示轉介子狀態。
狀態原因	字串	有關狀態的描述性訊息。例如，說明為什麼失去了轉介。
推薦類型	推薦類型	代表轉介類型。必須。
資格	推薦資格	代表轉介的品質。
CustomerProfile	CustomerProfile	客戶的連絡資訊。必要
同意	同意	關於是否與其他組織共用資訊並允許這些組織聯絡使用者的同意標記。必要。
詳細資料	轉介詳情	客戶的詳細資料、注意事項、交易價值、貨幣結算日。必要
球隊	成員	涉及合作夥伴參與的組織中代表的使用者。
InviteContext	邀請內容	使用者在邀請另一個組織加入夥伴關係時提供的更多資訊。
Target	推薦目標	代表使用者在邀請另一個組織參與合作關係時可以提供的更多資訊。
合作夥伴角色	合作夥伴角色	僅適用於服務共同銷售轉介的必要條件
解決方案區域	解決方案區	商機中客戶所需的解決方案區域。僅限於服務共同銷售推薦的必需項目
解決方案運行	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 呼叫建立微軟轉介，並使用步驟 1 傳回的「參與標識符」欄位將其連結到合作夥伴轉介。

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

轉介資源

共用方式為

建立轉介

必要條件

REST 要求

要求語法

要求標頭

請求正文

要求範例

REST 回應

回應成功和錯誤碼

回應範例

建立聯合銷售方案或共享推薦

步驟 1：建立由合作夥伴主導的交易，讓 Microsoft 的銷售人員可見

步驟 2：使用合作夥伴推薦詳細數據建立Microsoft轉介

建立服務聯合銷售機會

意見反應

其他資源

共用方式為

建立轉介

必要條件

REST 要求

要求語法

要求標頭

請求正文

要求範例

REST 回應

回應成功和錯誤碼

回應範例

建立聯合銷售方案或共享推薦

步驟 1：建立由合作夥伴主導的交易，讓 Microsoft 的銷售人員可見

步驟 2：使用合作夥伴推薦詳細數據建立Microsoft轉介

建立服務聯合銷售機會

相關內容

意見反應

其他資源