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):

  1. Unabhängig: Die Empfehlung ist nur für einen einzelnen Partner sichtbar.
  2. 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

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:

  1. Erstellen deiner gemeinsam genutzten Empfehlung
  2. 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:

Flow chart showing a shared referral with 2 referrals connected through the Microsoft Partner API

Erstellen deiner Empfehlung

  1. Erstelle eine Empfehlung, und lege dabei ReferralType auf die Option für eine gemeinsam genutzte Empfehlung fest.
  2. Kopiere die Engagement-ID (engagementId) aus der zurückgegebenen Antwort.

Exemplarisches Empfehlungsziel (ReferralTarget)

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

Erstellen einer verbundenen Empfehlung

  1. Erstelle eine weitere Empfehlung für Microsoft.
  2. 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"
        }
    ]