Creación de una referencia
En este artículo se explica cómo crear una referencia. Existen dos tipos de recursos ReferralType:
Independiente: donde una referencia es visible para un asociado.
Compartido: donde una referencia es visible para dos partes que trabajan juntos. Por ejemplo, si Microsoft y un asociado trabajan juntos en una oferta de venta conjunta, se puede compartir una referencia entre ambas partes. Para obtener más información, consulte la sección Creación de una referencia compartida.
Nota:
La idoneidad de MACC y las características de coincidencia de clientes no están disponibles con el uso de la integración de API.
Tipos de oferta
Hay tres tipos de oportunidades de venta conjunta (o ofertas o referencias) que se pueden crear desde el Centro de partners: ofertas privadas, dirigidas por partners y venta conjunta. Normalmente, desde la interfaz de usuario del Centro de partners, estas opciones se presentan al usuario, pero al crearlas desde la API, hay otros pasos que se deben seguir. En la interfaz de usuario de referencias del Centro de partners, al crear una nueva oferta, hay una ayuda necesaria en la sección Microsoft , donde se presentan estas opciones al usuario.
- Oferta privada: decide no compartir la oferta con Microsoft, seleccionar "No se necesita ayuda" y responder "no" a la pregunta"¿ ¿Desea compartir el trato con los vendedores de Microsoft?"
- Asociado dirigido: elige "No necesita ayuda", pero responde "sí" a la pregunta: "¿Desea compartir el trato con los vendedores de Microsoft?"
- Venta conjunta: elige obtener ayuda de Microsoft y también responder "sí" a la pregunta: "¿Desea compartir el trato con los vendedores de Microsoft?"
Requisitos previos
- Credenciales tal como se describe en el artículo Autenticación de la API de partners. 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 la 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 | Obligatorio solo para las referencias de venta conjunta de servicios | Puede ser uno de los siguientes valores: aprovisionamiento de preventas, diseño de soluciones, prueba de concepto, estrategia empresarial, servicios de implementación, adopción y administración de cambios, transacción, servicios administrados |
| Área de solución | Obligatorio solo para las referencias de venta conjunta de servicios | El área solución de la necesidad del cliente en la oportunidad. Consulte la tabla siguiente para ver los valores. |
| Juego de soluciones | Obligatorio solo para las referencias de venta conjunta de servicios | El juego de solución de la necesidad del cliente en la oportunidad. Consulte la tabla siguiente para ver los valores. |
Valores del área de solución y de la reproducción de soluciones
En la tabla siguiente se muestran los valores de los campos Área de solución y Juego de soluciones para FY 24.
| Área de solución | Juego de soluciones |
|---|---|
| Aplicaciones empresariales | Aceleración de la innovación con código bajo |
| Aplicaciones empresariales | Aceleración de la generación de ingresos |
| Aplicaciones empresariales | Modernización del servicio |
| Aplicaciones empresariales | Optimización de las finanzas y la cadena de suministro |
| Aplicaciones empresariales | Operaciones empresariales de escalado de SMB |
| Datos e IA | Power Business Decisions with Cloud Scale Analytics |
| Datos e IA | Compilación y modernización de aplicaciones de IA |
| Innovación digital y de aplicaciones | Migración de aplicaciones empresariales |
| Innovación digital y de aplicaciones | Compilación y modernización de aplicaciones de IA |
| Innovación digital y de aplicaciones | Acelerar la productividad de los desarrolladores |
| Innovación digital y de aplicaciones | Aceleración de la innovación con Integration Services |
| Infraestructura | Migración y protección de Windows Server y SQL Server |
| Infraestructura | Migración de SAP |
| Infraestructura | Innovación con HPC, ai Infrastructure |
| Infraestructura | Migración del patrimonio de Linux |
| Infraestructura | Migración de Oracle |
| Trabajo moderno | Trabajadores de primera línea |
| Trabajo moderno | Experiencia del empleado |
| Trabajo moderno | Productividad segura |
| Trabajo moderno | Comunicaciones convergentes |
| Trabajo moderno | Puntos de conexión de nube |
| Trabajo moderno | Modernización con Surface |
| Seguridad | Protección contra amenazas con XDR y SIEM |
| Seguridad | Seguridad en varias nubes |
| Seguridad | Seguridad de los datos |
| Seguridad | Gobernanza de datos |
| Seguridad | Operaciones de segundo modernas |
| Seguridad | Identidad segura y aceptar Okta y Ping |
| Soporte unificado | Creación de una base fuerte con Unified |
| Soporte unificado | Impulsar el éxito en la nube con soluciones mejoradas |
Estados de transición de estado y subestado
| Estado | Transición de estado permitida | Subestado permitido |
|---|---|---|
| Nuevo | New, Active, Closed | Pending, Received |
| Activas | Active, Closed | Aceptado |
| Cerrada | Closed | Won, Lost, Declined, Expired |
Ejemplo de solicitud
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": "Test Cosell Invite_20",
"status": "New",
"substatus": "Pending",
"statusReason": "Customer engagement was a success!",
"qualification": "SalesQualified",
"type": "Shared",
"target": [
{
"type": "SolutionProfile",
"id": "SOL-34104-EBB"
}
],
"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@contoso.com"
},
{
"contactPreference": {
"locale": "en-us",
"disableNotifications": false
},
"firstName": "Joe",
"lastName": "Hansen",
"phoneNumber": "4035698759",
"email": "joe.hansen@contoso.com"
}
],
"ids": []
},
"consent": {
"consentToToShareInfoWithOthers": true,
"consentToContact": 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": "2018-11-14T00:00:00Z",
"requirements": {
"industries": [
{
"id": "Manufacturing"
}
],
"products": [
{
"id": "Dynamics365Enterprise"
}
],
"services": [
{
"id": "DeploymentOrMigration"
}
],
"solutions": [
{
"name": "Dynamics 365 for Field Service",
"type": "Category",
"id": "Dynamics365forFieldService"
}
]
}
},
"team": [
{
"contactPreference": {
"locale": "en-us",
"disableNotifications": false
},
"firstName": "John",
"lastName": "Doe",
"phoneNumber": "1231231234",
"email": "john.doe@microsoft.com"
}
],
"inviteContext": {
"notes": "Hi ABC Partner, hoping you can help this customer. Thanks, John @ Microsoft",
"invitedBy": {
"organizationId": "msft"
}
}
}
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": "4111fffc-f9ee-4d53-bba6-569135228642",
"engagementId": "37ef26aa-1d15-4533-9f93-a69bd33ab1e5",
"organizationId": "7d23e5ca-19dc-4eaa-aac8-5e6b559f0d1d",
"organizationName": "Contoso Company",
"name": "Test Cosell Invite_20",
"externalReferenceId": null,
"createdDateTime": "2019-02-23T02:05:23.2931817Z",
"updatedDateTime": "2019-02-23T02:05:23.2931817Z",
"expirationDateTime": null,
"status": "Active",
"substatus": "Accepted",
"statusReason": "Customer engagement was a success!",
"qualification": "SalesQualified",
"type": "Shared",
"eTag": "\"00006d10-0000-0000-0000-5c70aa630000\"",
"target": [
{
"type": "SolutionProfile",
"id": "SOL-34104-EBB"
}
],
"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@contoso.com"
},
{
"contactPreference": {
"locale": "en-us",
"disableNotifications": false
},
"firstName": "Joe",
"lastName": "Hansen",
"phoneNumber": "4035698759",
"email": "joe.hansen@contoso.com"
}
],
"ids": []
},
"consent": {
"consentToToShareInfoWithOthers": true,
"consentToContact": true
},
"details": {
"notes": "Customer is looking to leverage Dynamics 365 to manage their supply chain. There is also a need to leverage a set of custom apps to enable their business processes.",
"dealValue": 50000,
"currency": "USD",
"requirements": {
"industries": [
{
"id": "Manufacturing"
}
],
"products": [
{
"id": "Dynamics365Enterprise"
}
],
"services": [
{
"id": "DeploymentOrMigration"
}
],
"solutions": [
{
"name": "Dynamics 365 for Field Service",
"type": "Category",
"id": "Dynamics365forFieldService"
}
]
}
},
"team": [
{
"contactPreference": {
"locale": "en-us",
"disableNotifications": false
},
"firstName": "John",
"lastName": "Doe",
"phoneNumber": "1231231234",
"email": "john.doe@microsoft.com"
}
],
"inviteContext": {
"notes": "Hi ABC Partner, hoping you can help this customer. Thanks, John @ Microsoft",
"invitedBy": {
"organizationId": "msft"
}
},
"links": {
"relatedReferrals": {
"uri": "https://api.partner.microsoft.com/v1.0/engagments/referrals?$filter=engagementId eq '37ef26aa-1d15-4533-9f93-a69bd33ab1e5'",
"method": "GET"
},
"self": {
"uri": "https://api.partner.microsoft.com/v1.0/engagments/referrals/4111fffc-f9ee-4d53-bba6-569135228642",
"method": "GET"
}
}
}
Actualización de la oferta de venta conjunta dirigida por partners o privados
Para crear una oferta de venta conjunta a través de la API, primero debe crear una oferta dirigida por partners o privados y, a continuación, crear la segunda referencia y conectarla con la primera. Los pasos se describen en la sección siguiente.
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.
POST https://api.partner.microsoft.com/v1.0/engagements/referrals
{
"name": "TEST Contoso Cosell Deal",
"externalReferenceId": "",
"campaignId": "",
"customerProfile": {
"isMatchingComplete": true,
"name": "Contoso Test Test",
"address": {
"addressLine1": "One Microsoft Way",
"addressLine2": "",
"city": "Redmond",
"state": "",
"region": "",
"country": "US"
},
"size": "",
"team": [
{
"firstName": "John",
"lastName": "Doe",
"phoneNumber": "123345667",
"email": "john@doe.com",
"title": "",
"phoneValidationStatus": "None",
"emailValidationStatus": "None",
"contactPreference": {
"disableNotifications": true
}
}
],
"ids": [
{
"profileType": "external",
"id": "9-XIPFFGUQI"
}
],
"type": ""
},
"consent": {
"ConsentToToShareInfoWithOthers": true,
"ConsentToContact": true,
"ConsentToMicrosoftToContactSpecificPartners": true,
"consentToShareReferralWithMicrosoftSellers": true
},
"details": {
"dealValue": 100000,
"currency": "USD",
"closingDateTime": "2024-11-23T18:30:00.000Z",
"notes": "",
"requirements": {
"solutions": [
{
"type": "Name",
"id": "SOL-8163-XCJ",
"name": "Contoso Solution",
"publisherName": "Contoso-ISV",
"price": null,
"currency": null,
"quantity": null,
"solutionType": "3P"
}
],
"additionalRequirements": {
"iot": {},
"attributes": [
{
"id": "HaveNotDecided",
"type": "CustomerMarketplaceIntent"
}
]
}
}
},
"team": [
{
"firstName": "John",
"lastName": "Doe",
"phoneNumber": "12345667",
"email": "john@doe.com",
"title": "",
"phoneValidationStatus": "None",
"emailValidationStatus": "None"
}
],
"type": "Shared",
"qualification": "SalesQualified",
"attributes": {
"objectType": "Referral"
},
"target": [],
"mpnId": "<ENTER PARTNER_MPN_ID>",
"trackingInfo": {}
}
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
{
"engagementId": "<ENTER_ENGAGEMENT_ID_OF_PARTNER_REFERRAL>",
"organizationId": "msft",
"organizationName": "Microsoft",
"name": "TEST Contoso Cosell Deal",
"customerProfile": {
"name": "Contoso Test Test",
"size": "",
"isMatchingComplete": true,
"isMaccEligible": null,
"address": {
"addressLine1": "One Microsoft Way",
"addressLine2": "",
"city": "Redmond",
"state": "",
"postalCode": null,
"country": "US",
"region": ""
},
"team": [
{
"firstName": "John",
"lastName": "Doe",
"phoneNumber": "123345667",
"email": "john@doe.com",
"title": "",
"emailValidationStatus": "None",
"phoneValidationStatus": "None",
"linkedInProfileUrl": null,
"contactPreference": {
"disableNotifications": true
}
}
],
"ids": [
{
"profileType": "External",
"id": "9-XIPFFGUQI"
}
],
"activities": null
},
"consent": {
"consentToToShareInfoWithOthers": true,
"consentToContact": true,
"consentToShareReferralWithMicrosoftSellers": true
},
"details": {
"notes": "Test notes to Microsoft.",
"dealValue": 100000,
"currency": "USD",
"closingDateTime": "2024-11-23T18:30:00Z",
"requirements": {
"solutions": [],
"additionalRequirements": {
"iot": {},
"attributes": []
}
}
},
"team": [],
"inviteContext": {
"notes": "Proof of concept / Demo , Test notes to Microsoft.",
"invitedBy": {
"organizationId": "<PARTNER_ORGANIZATION_ID (ACCOUNT_ID GUID)>",
"organizationName": "<INVITING_PARTNERS_ORGANIZATION_NAME>"
},
"assistanceRequestCode": "ProofOfConceptOrDemo"
},
"type": "Shared",
"qualification": "SalesQualified",
"attributes": {
"objectType": "Referral"
},
"target": [],
"dealSensitivity": "None",
"trackingInfo": {}
}
Creación de una referencia compartida
Hay dos pasos para crear una referencia del tipo de referencia compartido:
En el diagrama de flujo siguiente se muestran estos dos pasos para crear una referencia compartida.
Creación de la referencia
- Cree una referencia con el valor ReferralType establecido en "Shared".
- Copie el valor engagementID de la respuesta de devolución.
Ejemplo de ReferralTarget para la referencia
"target": [
{
"type": "SolutionProfile",
"id": "SOL-ABC-DEF"
}
]
Creación de una referencia conectada
- Cree otra referencia para Microsoft.
- Incluya el valor de enagementID de la referencia para que se vinculen.
Ejemplo de ReferralTarget para la referencia de Microsoft
"target": [
{
"type": "BusinessProfileLocation",
"id": "msft"
}
]
Pasos siguientes
Comentarios
Próximamente: A lo largo de 2024 iremos eliminando gradualmente GitHub Issues como mecanismo de comentarios sobre el contenido y lo sustituiremos por un nuevo sistema de comentarios. Para más información, vea: https://aka.ms/ContentUserFeedback.
Enviar y ver comentarios de