Criar uma referência

Artigo
03/07/2025

Este artigo explica como criar uma referência.

Pré-requisitos

Credenciais conforme descrito em Autenticação da API de Referências. Este cenário oferece suporte à autenticação com credenciais App+User.

Pedido REST

Sintaxe da solicitação

Método	URI do pedido
POST	`https://api.partner.microsoft.com/v1.0/engagements/referrals`

Cabeçalhos do pedido

Para obter mais informações, consulte Cabeçalhos REST da API de Parceiros.

Corpo do pedido

Esta tabela descreve as propriedades de referência no corpo do pedido para uma referência completamente nova.

Propriedade	Tipo	Descrição
Name	string	O nome da referência.
ID de Referência Externa	cadeia de caracteres	Um identificador externo para a referência. Por exemplo, sua própria ID de cliente potencial ou oportunidade do Dynamics 365.
Estado	ReferralStatus	Um Enum com valores que indicam o estado de referência.
Subestatuto	Substatus de referência	Um Enum com valores que indicam o substatus de referência.
Motivo do Estado	string	Uma mensagem descritiva sobre o status. Por exemplo, explique por que o encaminhamento foi perdido.
Tipo de referência	Tipo de referência	Representa o tipo de referência. Necessário.
Qualificação	Qualificação de Referência	Representa a qualidade da referência.
CustomerProfile	PerfilDoCliente	Informações de contato do cliente. Necessário.
Consentimento	Consentimento	Sinalizadores de consentimento relacionados ao partilhar informações com outras organizações e permitir que elas contactem os utilizadores. Necessário.
Detalhes	Detalhes de Referência	Detalhes do cliente, notas, valor do negócio, data de fechamento da moeda. Necessário.
Equipa	Membro	Representa os utilizadores nas organizações envolvidas na interação com os parceiros.
InviteContext	Contexto de Convite	Representa mais informações que um usuário pode fornecer ao convidar outra organização para o contrato de parceiro.
Destino	ReferralTarget	Representa mais informações que um usuário pode fornecer ao convidar outra organização para o contrato de parceiro.
Papel do parceiro	Função de Parceiro	Necessário apenas para referências de venda conjunta de Serviços
Área de Solução	Área de Soluções	A área da solução da necessidade do cliente na oportunidade. Necessário apenas para referências de co-venda de serviços
Implementação da Solução	SoluçãoPlay	A solução atende à necessidade do cliente na oportunidade. Necessário apenas para referências de venda conjunta de serviços

Exemplo de solicitação

Importante

Esta solicitação de exemplo descreve como criar uma referência privada com a mínima informação necessária. Observe que o parâmetro chave para transformar esta recomendação num negócio privado é 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>"
}

Resposta REST

Se for bem-sucedido, este método retorna o recurso Referral preenchido no corpo da resposta.

Códigos de sucesso e erro de resposta

Cada resposta vem com um código de status HTTP que indica sucesso ou falha e mais informações de depuração. Use uma ferramenta de rastreamento de rede para ler esse código, tipo de erro e outros parâmetros. Para obter a lista completa, consulte Códigos de erro.

Exemplo de resposta

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

Criar um acordo de venda conjunta ou uma referência partilhada

Há duas etapas para criar um acordo de covenda ou referência do tipo de referência compartilhada:

Criar um negócio liderado por um parceiro visível para a equipa de vendas da Microsoft
Criar uma recomendação da Microsoft usando detalhes de referência de parceiro

O fluxograma a seguir ilustra essas duas etapas na criação de uma referência compartilhada.

Flow chart showing a shared referral with two referrals connected through the API. Fluxograma mostrando uma referência compartilhada com duas referências conectadas por meio da API.

Etapa 1: Criar um negócio liderado por um parceiro visível para os vendedores da Microsoft

Primeiro, crie um negócio liderado pelo parceiro visível para os vendedores da Microsoft usando a seguinte carga de solicitação.

Importante

Observe que, para fazer uma referência liderada pelo parceiro, consentToShareReferralWithMicrosoftSellers é fornecido como true. Uma referência Privada ativa pode ser convertida em liderada por parceiro apenas atualizando a referência neste 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 representa informações adicionais que um parceiro pode fornecer ao convidar outras organizações para o envolvimento. Para especificar «destino» numa remissão para o tipo SolutionProfile, aqui está um valor de exemplo para referência:

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

Nota

O campo tipo fornecido como Independente ou Partilhado na entrada da solicitação é apenas um valor indicativo e não afeta o tipo de negócio. O valor real é atribuído na API com base noutros parâmetros, como consentimento e contexto de convite.

Etapa 2: criar uma referência da Microsoft usando detalhes de referência de parceiro

Em seguida, crie a referência da Microsoft através de outra chamada de API e vincule-a à referência de parceiro usando o campo ID de Engajamento retornado do Passo 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": []
}

Para especificar ReferralTarget para uma referência da Microsoft, aqui está um valor de exemplo para referência:

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

Criar oportunidade de Co-venda de Serviços

Para criar uma oportunidade de Covenda de Serviços, é necessário fornecer PartnerRole, SolutionAreae SolutionPlay nos detalhes , nos requisitos >, e nos requisitos adicionais >.
Os detalhes da solução são opcionais em oportunidades de covenda de serviços.

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

Recursos de referência

Partilhar via

Criar uma referência

Pré-requisitos

Pedido REST

Sintaxe da solicitação

Cabeçalhos do pedido

Corpo do pedido

Exemplo de solicitação

Resposta REST

Códigos de sucesso e erro de resposta

Exemplo de resposta

Criar um acordo de venda conjunta ou uma referência partilhada

Etapa 1: Criar um negócio liderado por um parceiro visível para os vendedores da Microsoft

Etapa 2: criar uma referência da Microsoft usando detalhes de referência de parceiro

Criar oportunidade de Co-venda de Serviços

Comentários

Recursos adicionais

Partilhar via

Criar uma referência

Pré-requisitos

Pedido REST

Sintaxe da solicitação

Cabeçalhos do pedido

Corpo do pedido

Exemplo de solicitação

Resposta REST

Códigos de sucesso e erro de resposta

Exemplo de resposta

Criar um acordo de venda conjunta ou uma referência partilhada

Etapa 1: Criar um negócio liderado por um parceiro visível para os vendedores da Microsoft

Etapa 2: criar uma referência da Microsoft usando detalhes de referência de parceiro

Criar oportunidade de Co-venda de Serviços

Conteúdos relacionados

Comentários

Recursos adicionais