추천서 만들기

아티클
03/07/2025

이 문서에서는 추천을 만드는 방법을 설명합니다.

필수 조건

조회 API 인증에 설명된 자격 증명입니다. 이 시나리오는 앱+사용자 자격 증명을 통한 인증을 지원합니다.

REST 요청

요청 구문

메서드	요청 URI
POST	`https://api.partner.microsoft.com/v1.0/engagements/referrals`

요청 헤더

자세한 내용은 파트너 API REST 헤더를 참조하세요.

요청 본문

다음 표에서는 신규 추천에 대한 요청 본문의 추천 속성을 설명합니다.

속성	유형	설명
이름	스트링	추천의 이름입니다.
외부참조ID	string	추천에 대한 외부 식별자입니다. 예를 들어, 사용자 고유의 Dynamics 365 리드 또는 기회 ID입니다.
상태	ReferralStatus	참조 상태를 나타내는 값이 있는 열거형입니다.
하위 상태	추천 하위 상태	조회 하위 상태를 나타내는 값으로 구성된 열거형입니다.
상태 사유	string	상태에 대한 설명 메시지입니다. 예를 들어 추천이 실패한 이유를 설명하십시오.
추천 유형	ReferralType	추천 유형을 나타냅니다. 필수입니다.
자격	ReferralQualification	추천의 품질을 나타냅니다.
CustomerProfile	고객 프로필	고객 연락처 정보입니다. 필수입니다.
동의	동의	동의 사항은 다른 조직과 정보를 공유하고 사용자에게 연락할 수 있도록 허용합니다. 필수 사항입니다.
세부 정보	추천 상세 정보	고객 세부 정보, 메모, 거래 가격, 통화 마감일입니다. 필수입니다.
팀	Member	파트너 참여와 관련된 조직의 사용자를 나타냅니다.
InviteContext	InviteContext	다른 조직을 파트너 참여에 초대할 때 사용자가 제공할 수 있는 추가 정보를 나타냅니다.
대상	ReferralTarget	다른 조직을 파트너 참여에 초대할 때 사용자가 제공할 수 있는 추가 정보를 나타냅니다.
파트너 역할	파트너 역할	서비스 공동 판매 조회에만 필요
솔루션 영역	솔루션 영역	기회에서 고객이 필요로 하는 솔루션 영역입니다. 서비스 공동 판매 조회에만 필요
솔루션 플레이	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": [
        {
            "type": "SolutionProfile",
            "id": "SOL-ABC-DEF"
        }
    ]

참고

요청 입력에서 "Independent" 또는 "Shared"로 제공된 필드 유형은 단지 지시적인 값일 뿐이며, 거래 유형에 영향을 미치지 않습니다. API 내에서 다른 매개 변수인 consent 및 inviteContext를 기반으로 할당된 실제 값입니다.

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이(가) 세부 정보 > 요구 사항 > 추가 요건에 제공되어야 합니다.
솔루션 세부 정보는 서비스 공동 판매 기회에서 선택 사항입니다.

"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 추천 만들기

서비스 공동 판매 기회 만들기

관련 콘텐츠

피드백

추가 리소스