Creación de una referencia

Artículo
08/11/2024

En este artículo se explica cómo crear una referencia.

Requisitos previos

Credenciales como se describe en Autenticación de API de referencias. Este escenario admite la autenticación con credenciales de aplicación y usuario.

Solicitud REST

Sintaxis de la solicitud

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

Encabezados de solicitud

Para obtener más información, consulte Encabezados de la API REST de partners.

Cuerpo de solicitud

En esta tabla se describen las propiedades de referencia del cuerpo de la solicitud de una nueva referencia.

Propiedad	Tipo	Descripción
Nombre	string	Nombre de la referencia
ExternalReferenceID	string	Identificador externo de la referencia. Por ejemplo, su propio identificador de oportunidad o cliente potencial de Dynamics 365.
Estado	ReferralStatus	Clase Enum con valores que indican el estado de la referencia.
Subestado	ReferralSubstatus	Un elemento Enum con valores que indican el subestado de la referencia.
StatusReason	string	Mensaje descriptivo sobre el estado. Por ejemplo, para explicar por qué se perdió la referencia.
ReferralType	ReferralType	Representa el tipo de referencia. Necesario.
cualificación	ReferralQualification	Representa la calidad de la referencia.
CustomerProfile	CustomerProfile	Información de contacto del cliente. Necesario.
Consentir	Consentimiento	Marcas de consentimiento para compartir información con otras organizaciones y permitirles ponerse en contacto con los usuarios.Obligatorio.
Detalles	ReferralDetails	Detalles del cliente, notas, valor de la oferta, fecha de cierre de la moneda. Necesario.
Team	Member	Representa a los usuarios de las organizaciones que participan en la interacción con el asociado.
InviteContext	InviteContext	Representa más información que un usuario puede proporcionar al invitar a otra organización a la interacción de asociados.
Destino	ReferralTarget	Representa más información que un usuario puede proporcionar al invitar a otra organización a la interacción de asociados.
Rol de asociado	PartnerRole	Obligatorio solo para las referencias de venta conjunta de servicios
Área de solución	SolutionArea	El área solución de la necesidad del cliente en la oportunidad. Obligatorio solo para las referencias de venta conjunta de servicios
Juego de soluciones	SolutionPlay	El juego de solución de la necesidad del cliente en la oportunidad. Obligatorio solo para las referencias de venta conjunta de servicios

Ejemplo de solicitud

Importante

En esta solicitud de ejemplo se describe cómo crear una referencia privada con información mínima necesaria. Observe que el parámetro clave para convertir esta referencia en una oferta privada es 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>"
}

Respuesta REST

Si es correcta, este método devuelve el recurso de referencia rellenado en el cuerpo de la respuesta.

Códigos de error y de respuesta correctos

Cada respuesta incluye un código de estado HTTP que indica éxito o error y más información de depuración. Use una herramienta de seguimiento de red para leer este código, tipo de error y otros parámetros. Para obtener la lista completa, consulte Códigos de error.

Ejemplo de respuesta

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

Crear una oferta de venta conjunta o una referencia compartida

Hay dos pasos para crear una oferta de venta conjunta o una referencia del tipo de referencia compartido:

Creación de una oferta dirigida por partners visible para vendedores de Microsoft
Creación de una referencia de Microsoft mediante los detalles de referencia de asociados

En el diagrama de flujo siguiente se muestran estos dos pasos para crear una referencia compartida.

Diagrama de flujo que muestra una referencia compartida con dos referencias conectadas a través de la API.

Paso 1: Crear una oferta dirigida por partners visible para los vendedores de Microsoft

En primer lugar, cree una oferta dirigida por partners visible para los vendedores de Microsoft mediante la siguiente carga de solicitud.

Importante

Tenga en cuenta que para realizar una referencia dirigida por partner, consentToShareReferralWithMicrosoftSellers se proporciona como true. Una referencia privada activa se puede convertir en dirigida por partners simplemente actualizando la referencia 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 información adicional que un asociado puede proporcionar al invitar a otras organizaciones a la interacción. Para especificar "target" en una referencia para el tipo SolutionProfile, este es un valor de ejemplo para referencia:

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

Nota:

El tipo de campo proporcionado como Independiente o Compartido en la entrada de solicitud es simplemente un valor indicativo y no afecta al tipo de oferta. Valor real en asignado dentro de la API en función de otros parámetros, como consent e inviteContext.

Paso 2: Creación de una referencia de Microsoft mediante los detalles de referencia de asociados

A continuación, cree la referencia de Microsoft a través de otra llamada API y vincúlela a la referencia de partner mediante el campo Id. de engagement devuelto desde el paso 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 una referencia de Microsoft, este es un valor de ejemplo para referencia:

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

Creación de una oportunidad de venta conjunta de servicios

Para crear una oportunidad de venta conjunta de servicios, PartnerRole, SolutionArea y SolutionPlay deben proporcionarse en los requisitos de detalles > > adicionalesRequirements.
Los detalles de la solución son opcionales en las oportunidades de venta conjunta de servicios.

"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 referencia

Compartir a través de

Creación de una referencia

Requisitos previos

Solicitud REST

Sintaxis de la solicitud

Encabezados de solicitud

Cuerpo de solicitud

Ejemplo de solicitud

Respuesta REST

Códigos de error y de respuesta correctos

Ejemplo de respuesta

Crear una oferta de venta conjunta o una referencia compartida

Paso 1: Crear una oferta dirigida por partners visible para los vendedores de Microsoft

Paso 2: Creación de una referencia de Microsoft mediante los detalles de referencia de asociados

Creación de una oportunidad de venta conjunta de servicios

Comentarios

Recursos adicionales

Compartir a través de

Creación de una referencia

Requisitos previos

Solicitud REST

Sintaxis de la solicitud

Encabezados de solicitud

Cuerpo de solicitud

Ejemplo de solicitud

Respuesta REST

Códigos de error y de respuesta correctos

Ejemplo de respuesta

Crear una oferta de venta conjunta o una referencia compartida

Paso 1: Crear una oferta dirigida por partners visible para los vendedores de Microsoft

Paso 2: Creación de una referencia de Microsoft mediante los detalles de referencia de asociados

Creación de una oportunidad de venta conjunta de servicios

Contenido relacionado

Comentarios

Recursos adicionales