建立轉介

發行項
08/12/2024

本文說明如何建立轉介。

必要條件

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

REST 要求

要求語法

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

要求標頭

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

要求本文

下表描述在全新轉介的要求主體中所具有的轉介屬性。

屬性	類型	Description
Name	字串	轉介的名稱。
ExternalReferenceID	字串	轉介的外部識別碼。例如，您自己的 Dynamics 365 潛在客戶或商機識別碼。
狀態	ReferralStatus	有值會指出轉介狀態的列舉。
子狀態	ReferralSubstatus	有值會指出轉介子狀態的列舉。
StatusReason	字串	有關狀態的描述性訊息。例如，說明為什麼未能拿下轉介。
ReferralType	ReferralType	代表轉介類型。必要。
資格	ReferralQualification	代表轉介的品質。
CustomerProfile	CustomerProfile	客戶的連絡資訊。必要。
同意	同意	關於是否與其他組織共用資訊和允許這些組織連絡使用者的同意旗標。必要。
詳細資料	ReferralDetails	客戶的詳細資料、注意事項、交易價值、貨幣結算日。必要。
球隊	成員	代表涉及合作夥伴參與的組織中所具有的使用者。
InviteContext	InviteContext	代表使用者可以在邀請另一個組織參與合作夥伴時提供的詳細資訊。
Target	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 傳回的 [參與標識符 ] 字段將其連結至合作夥伴轉介。

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轉介

建立服務共同銷售商機

相關內容

意見反應

其他資源