Creare una segnalazione

Articolo
03/07/2025

Questo articolo illustra come creare una segnalazione.

Prerequisiti

Credenziali come descritto in Autenticazione dell'API delle 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 ulteriori informazioni, consultare Intestazioni dell'API REST Partner.

Testo della richiesta

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

Proprietà	Tipo	Descrizione
Nome	string	Nome della segnalazione.
ExternalReferenceID	string	Identificatore esterno della segnalazione. ad esempio il tuo ID cliente potenziale o opportunità di Dynamics 365.
Status	ReferralStatus	Enum con valori che indicano lo stato della segnalazione.
Stato secondario	ReferralSubstatus	Enum con valori che indicano il sottostato della segnalazione.
Motivo dello Stato	string	Messaggio descrittivo sullo stato, ad esempio una spiegazione del motivo per cui la segnalazione è andata persa.
Tipo di Referenza	Tipo di Referral	Rappresenta il tipo di segnalazione. Obbligatorio.
Qualificazione	ReferralQualification	Rappresenta la qualità della segnalazione.
CustomerProfile	ProfiloCliente	Informazioni sul contatto del cliente. Obbligatorio.
Consenso	Consenso	Impostazioni di consenso sulla condivisione di informazioni con altre organizzazioni e che consentono loro di contattare gli utenti. Obbligatorie.
Dettagli	Dettagli di Riferimento	Dettagli del cliente, note, valore della trattativa, data di chiusura della valuta. Obbligatorio.
Squadra	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-sell dei servizi
Area delle soluzioni	Area di Soluzione	L'area Soluzione del cliente deve avere l'opportunità. Obbligatorio solo per le segnalazioni di co-vendita dei servizi
Esecuzione della soluzione	SolutionPlay	Il ruolo della soluzione nel soddisfare le esigenze del cliente 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 avuto successo, questo metodo restituisce la risorsa Referral 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

Ci sono due passaggi per creare una trattativa di Co-sell o una segnalazione di tipo condiviso referral:

Creare un'offerta guidata dal partner visibile ai commerciali 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.

Flow chart showing a shared referral with two referrals connected through the API. 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 rendere una referral guidata da partner, consentToShareReferralWithMicrosoftSellers viene fornito come vero. Una segnalazione Privata attiva può essere convertita in Gestita dal 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, ecco un valore di esempio come riferimento:

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

Nota

Il campo type fornito come Indipendente o Condiviso nell'input della richiesta è solo un valore indicativo e non determina il tipo di affare. 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 una segnalazione Microsoft tramite un'altra chiamata API e collegarla alla segnalazione del partner usando il campo Engagement ID 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-vendita di servizi

Per creare un'opportunità di co-selling per i servizi, PartnerRole, SolutionAreae SolutionPlay devono essere forniti nei dettagli , requisiti >, requisiti aggiuntivi >.
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 di referral

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-vendita di 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-vendita di servizi

Contenuto correlato

Commenti e suggerimenti

Risorse aggiuntive