紹介を作成する

[アーティクル]
08/12/2024

この記事では、紹介を作成する方法について説明します。

前提条件

Referrals API 認証で説明されている資格情報。このシナリオでは、アプリとユーザーの資格情報を使用した認証がサポートされます。

REST 要求

要求の構文

認証方法	要求 URI
投稿	`https://api.partner.microsoft.com/v1.0/engagements/referrals`

要求ヘッダー

詳細については、「パートナー API REST ヘッダー」を参照してください。

要求本文

次の表では、新しい紹介の要求本文の Referral プロパティについて説明しています。

プロパティ	タイプ	説明
氏名	string	紹介の名前。
ExternalReferenceID	string	紹介の外部識別子。たとえば、独自の Dynamics 365 潜在顧客または営業案件 ID。
状態	ReferralStatus	紹介の状態を示す値を含む Enum。
サブ状態	ReferralSubstatus	紹介のサブ状態を示す値を含む Enum。
StatusReason	string	状態に関する説明メッセージ。たとえば、紹介が失われた理由を説明します。
ReferralType	ReferralType	紹介の種類を表します。必須。
認定	ReferralQualification	紹介の質を表します。
CustomerProfile	CustomerProfile	顧客の連絡先情報。必須。
承認	同意	他の組織との情報共有や、ユーザーと連絡を取ることを他の組織に許可することに関連した同意フラグ。必須。
詳細	ReferralDetails	顧客の詳細、備考、取引金額、通貨の締め日など。必須。
Team	Member	パートナーエンゲージメントに関係している組織内のユーザーを表します。
InviteContext	InviteContext	別の組織をパートナーエンゲージメントに招待するときにユーザーが提供できる詳細情報を表します。
ターゲット	ReferralTarget	別の組織をパートナーエンゲージメントに招待するときにユーザーが提供できる詳細情報を表します。
パートナーロール	PartnerRole	サービス共同販売の紹介にのみ必要
ソリューション分野	SolutionArea	営業案件における顧客ニーズのソリューション領域。サービス共同販売の紹介にのみ必要
ソリューションプレイ	SolutionPlay	お客様のニーズのソリューションプレイを機会に提供します。サービス共同販売の紹介にのみ必要

要求の例

重要

このサンプル要求では、最小限の情報で Private 紹介を作成する方法について説明します。この紹介をプライベート取引にするキーパラメーターは 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"
		}
	}
}

共同販売取引または共有紹介を作成する

Shared referral 型の共同販売取引または紹介を作成するには、次の 2 つの手順があります

Microsoft 販売者に表示されるパートナー主導の取引を作成する
パートナー紹介の詳細を使用して Microsoft 紹介を作成する

次のフローチャートは、共有紹介を作成する場合のこれら 2 つの手順を示しています。

API を介して接続された 2 つの紹介を含む共有紹介を示すフローチャート。

手順 1: Microsoft 販売者に表示されるパートナー主導の取引を作成する

まず、次の要求ペイロードを使用して、Microsoft 販売者に表示されるパートナー主導の取引を作成します。

重要

紹介パートナー主導にするには、 consentToShareReferralWithMicrosoftSellers が true として提供されることに注意してください。アクティブなPrivate紹介は、このフィールドの紹介をPartner 主導に変換できます。

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

Note

要求入力のフィールド type Independent または Shared は単なる指示値であり、取引の種類には影響しません。 consentやinviteContextなどの他のパラメーターに基づいて、API 内で割り当てられた実際の値。

手順 2: パートナー紹介の詳細を使用して Microsoft 紹介を作成する

次に、別の API 呼び出しを使用して Microsoft 紹介を作成し、手順 1 から返された Engagement 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を追加のRequirements>details >要件で提供する必要があります。
ソリューションの詳細は、サービス共同販売の機会では省略可能です。

"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 紹介を作成する

サービス共同販売機会の作成

関連するコンテンツ

フィードバック

その他のリソース