Criar uma referência

Artigo
08/12/2024

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 do parceiro.

Corpo do pedido

Esta tabela descreve as propriedades de referência no corpo da solicitação de uma nova referência.

Propriedade	Type	Description
Name	string	O nome da referência.
ExternalReferenceID	string	Um identificador externo para a referência. Por exemplo, seu próprio Dynamics 365 ID de lead ou oportunidade.
Status	ReferralStatus	Um Enum com valores que indicam o status de referência.
Subestatuto	Substatus de referência	Um Enum com valores que indicam o substatus de referência.
StatusReason	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	ReferênciaQualificação	Representa a qualidade da referência.
CustomerProfile	CustomerProfile	Informações de contato do cliente. Necessário.
Consentimento	Consentimento	Sinalizadores de consentimento em torno do compartilhamento de informações com outras organizações e permitindo que elas entrem em contato com os usuários.Necessário.
Detalhes	ReferralDetails	Detalhes do cliente, notas, valor do negócio, data de fechamento da moeda. Necessário.
Equipa	Membro	Representa os usuários nas organizações envolvidas no envolvimento do parceiro.
InviteContext	InviteContext	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	ParceiroRole	Necessário apenas para referências de venda conjunta de Serviços
Área de Solução	Área de Solução	A área de Solução do Cliente precisa na oportunidade. Necessário apenas para referências de venda conjunta de Serviços
Reprodução da solução	SoluçãoPlay	A solução joga da 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 o mínimo de informações necessárias. Observe que o parâmetro chave para tornar essa referência um 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, esse método retornará o recurso de referência 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 covenda ou uma referência compartilhada

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 os vendedores da Microsoft
Criar uma referência 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.

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 por parceiro visível para os vendedores da Microsoft usando a seguinte carga útil 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 pelo parceiro apenas atualizando a referência para este 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 compromisso. Para especificar 'target' em uma referência para o tipo SolutionProfile, aqui está um valor de exemplo para referência:

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

Nota

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

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

Em seguida, crie a referência da Microsoft por meio de outra chamada de API e vincule-a à referência de parceiro usando o campo ID do compromisso retornado da Etapa 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, PartnerRole, SolutionArea e SolutionPlay devem ser fornecidos em detalhes > requisitos > adicionaisRequirements.
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 covenda ou uma referência compartilhada

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 covenda ou uma referência compartilhada

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