создание реферальной рекомендации;

В этой статье объясняется, как создать направление.

Предварительные требования

• Учетные данные, как описано в аутентификации API рефералов. Этот сценарий поддерживает проверку подлинности с использованием учетных данных приложений и пользователей.

Запрос REST

Синтаксис запроса

Способ	URI запроса
POST	https://api.partner.microsoft.com/v1.0/engagements/referrals

Заголовки запросов

• Дополнительные сведения см. в заголовках REST API для партнеров.

Текст запроса

В этой таблице описываются свойства объекта Referral в тексте запроса для новой реферальной рекомендации.

Свойство	Тип	Описание
Имя.	строка	Название реферала.
ВнешнийИдентификаторСсылки	строка	Внешний идентификатор для реферала. Например, это может быть идентификатор вашего потенциального клиента или возможной сделки в Dynamics 365.
Состояние	ReferralStatus	Enum со значениями, обозначающими состояние реферальной рекомендации.
Подсостояние	Подстатус направления	Enum со значениями, обозначающими субсостояние реферальной рекомендации.
Причина статуса	строка	Описательное сообщение о состоянии. Например, это может быть объяснение причины, по которой реферальная рекомендация не привела к сделке.
Тип направления	Тип направления	Представляет тип реферальной рекомендации. Обязательно.
Квалификация	КвалификацияДляРекомендации	Представляет качество реферальной рекомендации.
Профиль клиента	Профиль клиента	Контактные данные пользователя. Обязательно.
Согласие	Согласие	Флаги согласия для предоставления другим организациям доступа к данным и разрешения на связь с пользователями. Обязательный.
Сведения	ReferralDetails	Сведения о клиенте, примечания, сумма сделки, валюта, дата заключения сделки. Обязательно.
Группа	Член	Представляет пользователей в организациях, участвующих в партнерских отношениях.
Контекст Приглашения	Пригласительный контекст	Представляет дополнительную информацию, которую пользователь может предоставить при приглашении другой организации в участие партнера.
Цель	ReferralTarget	Представляет дополнительную информацию, которую пользователь может предоставить при приглашении другой организации в участие партнера.
Роль партнера	Роль партнера	Требуется только для рекомендаций по совместным продажам служб
Область решения	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"
			}
		],
		"ids":[
			{
				"profileType":"moodys",
				"id":"IN0011234567"
			}
		]
	},
	"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

В случае успешного выполнения этот метод возвращает заполненный ресурс Referral в теле ответа.

Коды успешности и ошибки ответа

Каждый ответ поставляется с кодом состояния 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": [
			{
				"profileType":"moodys",
				"id":"IN0011234567"
			}
		],
		"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"
		}
	}
}

Создайте сделку совместной продажи или общую рекомендацию

Для создания сделки по совместной продаже или реферала типа ОбщийТип Реферала необходимо выполнить два шага:

1. Создайте сделку под руководством партнера, видимую для продавцов Microsoft
2. Создайте реферал Microsoft, используя данные о партнёре

В следующей блок-схеме показаны эти два шага при создании общей ссылки.

Блок-схема, показывающая общее перенаправление с двумя перенаправлениями, связанными через API.

Шаг 1. Создание сделки под руководством партнера, видимой для продавцов Майкрософт

Сначала создайте сделку под руководством партнера, видимую продавцам Майкрософт, используя следующие полезные данные запроса.

Внимание

Обратите внимание, что для того, чтобы сделать реферальную рекомендацию, инициированную партнером, 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 - [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 представляет дополнительную информацию, которую партнер может предоставить при приглашении других организаций к сотрудничеству. Чтобы указать "target" в ссылке для типа SolutionProfile, вот пример значения для справки:

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

Примечание.

Тип поля, предоставленный как независимый или общий в входных данных запроса, является лишь показательным значением, и это не влияет на тип сделки. Фактическое значение назначается в API на основе других параметров, таких как согласие и контекст приглашения.

Шаг 2. Создание ссылки Майкрософт с помощью сведений о реферале партнера

Затем создайте реферал Microsoft с помощью другого вызова API и свяжите его с рефералом партнера, используя поле ID взаимодействия, возвращенное на шаге 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": []
}

Чтобы указать ReferenceTarget для ссылки Майкрософт, ниже приведен пример значения для справки:

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

Создание возможности совместной продажи сервисов

1. Чтобы создать возможность совместной продажи услуг, необходимо указать PartnerRole, SolutionAreaи SolutionPlay в подробных требованиях > и дополнительных > требованиях.
2. Сведения о решении являются необязательными в возможностях совместных продаж услуг.

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

Связанный контент

• Ресурсы по рефералам