Erstellen einer Empfehlung
Gilt für:
- Partner-API
In diesem Thema erfährst du, wie du eine Empfehlung erstellst. Es gibt zwei Arten von Empfehlungstypen (ReferralType):
- Unabhängig: Die Empfehlung ist nur für einen einzelnen Partner sichtbar.
- Gemeinsam genutzt: Die Empfehlung ist für zwei Parteien sichtbar, die zusammenarbeiten. Wenn also beispielsweise Microsoft und ein Partner bei einem Co-Selling-Angebot zusammenarbeiten, kann eine Empfehlung von beiden Parteien genutzt werden. Weitere Informationen findest du im Abschnitt Erstellen einer gemeinsam genutzten Empfehlung.
Voraussetzungen
- Anmeldeinformationen, wie unter Partner-API-Authentifizierung beschrieben. In diesem Szenario wird die Authentifizierung mit App- und Benutzeranmeldeinformationen unterstützt.
REST-Anforderung
Anforderungssyntax
| Methode | Anforderungs-URI |
|---|---|
| POST | https://api.partner.microsoft.com/v1.0/engagements/referrals |
Anforderungsheader
- Weitere Informationen findest du unter Partner-API: REST-Header.
Anforderungstext
In der folgenden Tabelle werden die Eigenschaften von Empfehlungsressourcen im Anforderungstext für eine neue Empfehlung beschrieben:
| Eigenschaft | Type | Beschreibung |
|---|---|---|
| Name | string | Der Name der Empfehlung. |
| ExternalReferenceId | string | Ein externer Bezeichner für die Empfehlung. Beispielsweise deine eigene Dynamics 365-Lead- oder -Verkaufschancen-ID. |
| Status | ReferralStatus | Eine Enumeration mit Werten, die den Status der Empfehlung angeben. |
| Substatus | ReferralSubstatus | Eine Enumeration mit Werten, die den Substatus der Empfehlung angeben. |
| StatusReason | string | Eine beschreibende Statusmeldung. Erläutere beispielsweise, warum die Empfehlung nicht erfolgreich war. |
| ReferralType | ReferralType | Stellt die Art der Empfehlung dar. Erforderlich. |
| Qualification | ReferralQualification | Stellt die Qualität der Empfehlung dar. |
| CustomerProfile | CustomerProfile | Die Kontaktinformationen des Kunden. Erforderlich. |
| Consent | Consent | Zustimmungsflags hinsichtlich der Weitergabe von Informationen an andere Organisationen und der Erlaubnis, Kontakt mit Benutzern aufzunehmen. Erforderlich. |
| Details | ReferralDetails | Kundendetails, Hinweise, Wert des Geschäfts, Währung und Enddatum. Erforderlich. |
| Team | Member | Stellt Benutzer in den Organisationen dar, die an dem Partner-Engagement beteiligt sind. |
| InviteContext | InviteContext | Stellt zusätzliche Informationen dar, die ein Benutzer angeben kann, wenn er eine weitere Organisation zum Partner-Engagement einlädt. |
| Ziel | ReferralTarget | Stellt zusätzliche Informationen dar, die ein Benutzer angeben kann, wenn er eine weitere Organisation zum Partner-Engagement einlädt. |
Übergangszustände für Status und Substatus
| Status | Zulässiger Statusübergang | Zulässiger Substatus |
|---|---|---|
| „Neu“, | New, Active, Closed | Pending, Received |
| Aktiv | Active, Closed | Accepted |
| Geschlossen | Geschlossen | Gewonnen, verloren, abgelehnt, abgelaufen |
Anforderungsbeispiel
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": "Test Cosell Invite_20",
"status": "New",
"substatus": "Pending",
"statusReason": "Customer engagement was a success!",
"qualification": "SalesQualified",
"type": "Shared",
"target": [
{
"type": "SolutionProfile",
"id": "SOL-34104-EBB"
}
],
"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@contoso.com"
},
{
"contactPreference": {
"locale": "en-us",
"disableNotifications": false
},
"firstName": "Joe",
"lastName": "Hansen",
"phoneNumber": "4035698759",
"email": "joe.hansen@contoso.com"
}
],
"ids": []
},
"consent": {
"consentToToShareInfoWithOthers": true,
"consentToContact": true
},
"details": {
"notes": "Customer is looking to leverage Dynamics 365 to manage their supply chain. There is also a need to leverage a set of custom apps to enable their business processes.",
"dealValue": 50000,
"currency": "USD",
"closingDateTime": "2018-11-14T00:00:00Z",
"requirements": {
"industries": [
{
"id": "Manufacturing"
}
],
"products": [
{
"id": "Dynamics365Enterprise"
}
],
"services": [
{
"id": "DeploymentOrMigration"
}
],
"solutions": [
{
"name": "Dynamics 365 for Field Service",
"type": "Category",
"id": "Dynamics365forFieldService"
}
]
}
},
"team": [
{
"contactPreference": {
"locale": "en-us",
"disableNotifications": false
},
"firstName": "John",
"lastName": "Doe",
"phoneNumber": "1231231234",
"email": "john.doe@microsoft.com"
}
],
"inviteContext": {
"notes": "Hi ABC Partner, hoping you can help this customer. Thanks, John @ Microsoft",
"invitedBy": {
"organizationId": "msft"
}
}
}
REST-Antwort
Bei erfolgreicher Ausführung gibt diese Methode die aufgefüllte Empfehlungsressource im Antworttext zurück.
Erfolgs- und Fehlercodes der Antwort
Jede Antwort enthält einen HTTP-Statuscode, der Aufschluss darüber gibt, ob der Vorgang erfolgreich war, sowie ggf. zusätzliche Debuginformationen. Verwende ein Tool für die Netzwerkablaufverfolgung, um diesen Code, den Fehlertyp und zusätzliche Parameter zu lesen. Die vollständige Liste findest du unter Partner-API: REST-Fehlercodes.
Antwortbeispiel
{
"id": "4111fffc-f9ee-4d53-bba6-569135228642",
"engagementId": "37ef26aa-1d15-4533-9f93-a69bd33ab1e5",
"organizationId": "7d23e5ca-19dc-4eaa-aac8-5e6b559f0d1d",
"organizationName": "Contoso Company",
"name": "Test Cosell Invite_20",
"externalReferenceId": null,
"createdDateTime": "2019-02-23T02:05:23.2931817Z",
"updatedDateTime": "2019-02-23T02:05:23.2931817Z",
"expirationDateTime": null,
"status": "Active",
"substatus": "Accepted",
"statusReason": "Customer engagement was a success!",
"qualification": "SalesQualified",
"type": "Shared",
"eTag": "\"00006d10-0000-0000-0000-5c70aa630000\"",
"target": [
{
"type": "SolutionProfile",
"id": "SOL-34104-EBB"
}
],
"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@contoso.com"
},
{
"contactPreference": {
"locale": "en-us",
"disableNotifications": false
},
"firstName": "Joe",
"lastName": "Hansen",
"phoneNumber": "4035698759",
"email": "joe.hansen@contoso.com"
}
],
"ids": []
},
"consent": {
"consentToToShareInfoWithOthers": true,
"consentToContact": true
},
"details": {
"notes": "Customer is looking to leverage Dynamics 365 to manage their supply chain. There is also a need to leverage a set of custom apps to enable their business processes.",
"dealValue": 50000,
"currency": "USD",
"requirements": {
"industries": [
{
"id": "Manufacturing"
}
],
"products": [
{
"id": "Dynamics365Enterprise"
}
],
"services": [
{
"id": "DeploymentOrMigration"
}
],
"solutions": [
{
"name": "Dynamics 365 for Field Service",
"type": "Category",
"id": "Dynamics365forFieldService"
}
]
}
},
"team": [
{
"contactPreference": {
"locale": "en-us",
"disableNotifications": false
},
"firstName": "John",
"lastName": "Doe",
"phoneNumber": "1231231234",
"email": "john.doe@microsoft.com"
}
],
"inviteContext": {
"notes": "Hi ABC Partner, hoping you can help this customer. Thanks, John @ Microsoft",
"invitedBy": {
"organizationId": "msft"
}
},
"links": {
"relatedReferrals": {
"uri": "https://api.partner.microsoft.com/v1.0/engagments/referrals?$filter=engagementId eq '37ef26aa-1d15-4533-9f93-a69bd33ab1e5'",
"method": "GET"
},
"self": {
"uri": "https://api.partner.microsoft.com/v1.0/engagments/referrals/4111fffc-f9ee-4d53-bba6-569135228642",
"method": "GET"
}
}
}
Erstellen einer gemeinsam genutzten Empfehlung
Die Erstellung einer Empfehlung mit dem EmpfehlungstypGemeinsam genutzt umfasst zwei Schritte:
- Erstellen deiner gemeinsam genutzten Empfehlung
- Erstellen einer verbundenen Empfehlung für die zweite Partei
Diese beiden Schritte für die Erstellung einer gemeinsam genutzten Empfehlung werden im folgenden Flussdiagramm veranschaulicht:

Erstellen deiner Empfehlung
- Erstelle eine Empfehlung, und lege dabei ReferralType auf die Option für eine gemeinsam genutzte Empfehlung fest.
- Kopiere die Engagement-ID (engagementId) aus der zurückgegebenen Antwort.
Exemplarisches Empfehlungsziel (ReferralTarget)
"target": [
{
"type": "SolutionProfile",
"id": "SOL-ABC-DEF"
}
]
Erstellen einer verbundenen Empfehlung
- Erstelle eine weitere Empfehlung für Microsoft.
- Schließe die Engagement-ID (enagementId) aus deiner Empfehlung ein, um die beiden Empfehlungen miteinander zu verknüpfen.
Exemplarisches Empfehlungsziel (ReferralTarget) für Microsoft
"target": [
{
"type": "BusinessProfileLocation",
"id": "msft"
}
]