Creare una segnalazione

Articolo
08/12/2024

Questo articolo illustra come creare una segnalazione.

Prerequisiti

Credenziali descritte in Autenticazione dell'API Segnalazioni. Questo scenario supporta l'autenticazione con le credenziali dell'app e dell'utente.

Richiesta REST

Sintassi della richiesta

metodo	URI della richiesta
POST	`https://api.partner.microsoft.com/v1.0/engagements/referrals`

Intestazioni delle richieste

Per altre informazioni, vedi Intestazioni dell'API REST Partner.

Testo della richiesta

Questa tabella descrive le proprietà di una segnalazione nel corpo della richiesta per una nuova segnalazione.

Proprietà	Type	Descrizione
Nome	string	Nome della segnalazione.
ExternalReferenceID	string	Identificatore esterno della segnalazione. ad esempio il tuo ID opportunità o cliente potenziale di Dynamics 365.
Status	ReferralStatus	Enumerazione con valori che indicano lo stato della segnalazione.
Stato secondario	ReferralSubstatus	Enumerazione con valori che indicano lo stato secondario della segnalazione.
StatusReason	string	Messaggio descrittivo sullo stato, ad esempio una spiegazione del motivo per cui la segnalazione è andata persa.
ReferralType	ReferralType	Rappresenta il tipo di segnalazione. Obbligatorio.
Qualification	ReferralQualification	Rappresenta la qualità della segnalazione.
CustomerProfile	CustomerProfile	Informazioni sul contatto del cliente. Obbligatorio.
Consenso	Consenso	Flag di consenso sulla condivisione di informazioni con altre organizzazioni e che consentono loro di contattare gli utenti. Obbligatoria.
Dettagli	ReferralDetails	Dettagli del cliente, note, valore della trattativa, data di chiusura della valuta. Obbligatorio.
Team	Member	Rappresenta gli utenti nelle organizzazioni coinvolte nell'accordo di partner.
InviteContext	InviteContext	Rappresenta altre informazioni che un utente può fornire quando invita un'altra organizzazione nel coinvolgimento dei partner.
Destinazione	ReferralTarget	Rappresenta altre informazioni che un utente può fornire quando invita un'altra organizzazione nel coinvolgimento dei partner.
Ruolo partner	PartnerRole	Obbligatorio solo per le segnalazioni di co-selling dei servizi
Area soluzione	SolutionArea	L'area Soluzione del cliente deve avere l'opportunità. Obbligatorio solo per le segnalazioni di co-selling dei servizi
Riproduzione della soluzione	SolutionPlay	Il gioco della soluzione del cliente ha bisogno nell'opportunità. Obbligatorio solo per le segnalazioni di co-selling dei servizi

Esempio di richiesta

Importante

Questa richiesta di esempio descrive come creare una segnalazione privata con informazioni minime necessarie. Si noti che il parametro chiave per rendere questa segnalazione una trattativa privata è 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>"
}

Risposta REST

Se ha esito positivo, questo metodo restituisce la risorsa di segnalazione popolata nel corpo della risposta.

Codici di errore e di esito della risposta

Ogni risposta viene fornita con un codice di stato HTTP che indica l'esito positivo o negativo e altre informazioni di debug. Usare uno strumento di traccia di rete per leggere questo codice, il tipo di errore e altri parametri. Per l'elenco completo, vedi Codici di errore.

Risposta di esempio

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

Creare una trattativa di co-selling o una segnalazione condivisa

Esistono due passaggi per creare una trattativa di co-selling o una segnalazione del tipo di riferimento condiviso:

Creare un'offerta guidata dal partner visibile ai venditori Microsoft
Creare una segnalazione Microsoft usando i dettagli delle segnalazioni dei partner

Il diagramma di flusso seguente illustra questi due passaggi nella creazione di una segnalazione condivisa.

Diagramma di flusso che mostra una segnalazione condivisa con due segnalazioni connesse tramite l'API.

Passaggio 1: Creare un'offerta guidata dal partner visibile ai venditori Microsoft

Prima di tutto, creare un'offerta guidata dal partner visibile ai venditori Microsoft usando il payload della richiesta seguente.

Importante

Si noti che per fare riferimento partner-led, consentToShareReferralWithMicrosoftSellers viene fornito come true. Una segnalazione privata attiva può essere convertita in partner semplicemente aggiornando la segnalazione per questo campo.

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 rappresenta informazioni aggiuntive che un partner può fornire quando invita altre organizzazioni all'impegno. Per specificare "target" in una segnalazione per il tipo SolutionProfile, di seguito è riportato un valore di esempio per riferimento:

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

Nota

Il tipo di campo fornito come Indipendente o Condiviso nell'input della richiesta è solo un valore indicativo e non influisce sul tipo di trattativa. Valore effettivo assegnato all'interno dell'API in base ad altri parametri, ad esempio il consenso e inviteContext.

Passaggio 2: Creare una segnalazione Microsoft usando i dettagli delle segnalazioni dei partner

Creare quindi la segnalazione Microsoft tramite un'altra chiamata API e collegarla alla segnalazione del partner usando il campo ID engagement restituito dal passaggio 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": []
}

Per specificare ReferralTarget per una segnalazione Microsoft, ecco un valore di esempio per riferimento:

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

Creare un'opportunità di co-selling dei servizi

Per creare un'opportunità di co-selling dei servizi, è necessario fornire PartnerRole, SolutionArea e SolutionPlay nei dettagli > requisiti > aggiuntiviRequirements.
I dettagli della soluzione sono facoltativi nelle opportunità di co-selling dei servizi.

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

Risorse per le segnalazioni

Condividi tramite

Creare una segnalazione

Prerequisiti

Richiesta REST

Sintassi della richiesta

Intestazioni delle richieste

Testo della richiesta

Esempio di richiesta

Risposta REST

Codici di errore e di esito della risposta

Risposta di esempio

Creare una trattativa di co-selling o una segnalazione condivisa

Passaggio 1: Creare un'offerta guidata dal partner visibile ai venditori Microsoft

Passaggio 2: Creare una segnalazione Microsoft usando i dettagli delle segnalazioni dei partner

Creare un'opportunità di co-selling dei servizi

Commenti e suggerimenti

Risorse aggiuntive

Condividi tramite

Creare una segnalazione

Prerequisiti

Richiesta REST

Sintassi della richiesta

Intestazioni delle richieste

Testo della richiesta

Esempio di richiesta

Risposta REST

Codici di errore e di esito della risposta

Risposta di esempio

Creare una trattativa di co-selling o una segnalazione condivisa

Passaggio 1: Creare un'offerta guidata dal partner visibile ai venditori Microsoft

Passaggio 2: Creare una segnalazione Microsoft usando i dettagli delle segnalazioni dei partner

Creare un'opportunità di co-selling dei servizi

Contenuto correlato

Commenti e suggerimenti

Risorse aggiuntive