Obtener la lista de clientes potenciales y oportunidades
En este artículo se explica cómo obtener la lista de clientes potenciales y oportunidades de venta conjunta. Estos clientes potenciales se reciben de la página Proveedor de soluciones de Microsoft, mientras que las oportunidades de venta conjunta se reciben de vendedores de Microsoft u otros asociados. Este proceso también captura la lista de oportunidades de venta conjunta o ofertas de canalización creadas por su organización.
Nota:
No se admiten clientes potenciales recibidos del marketplace comercial de Microsoft (Azure Marketplace y AppSource).
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.
- Actualmente, esta API solo admite el acceso de usuario donde los asociados deben estar en uno de los roles siguientes: Administrador de referencias o Usuario de referencia.
Solicitud REST
Sintaxis de la solicitud
| Método | URI de solicitud |
|---|---|
| GET | https://api.partner.microsoft.com/v1.0/engagements/referrals |
Operaciones de OData admitidas
| Nombre | Descripción | Obligatorio | Ejemplo |
|---|---|---|---|
| $select | Selecciona campos. | No | /referrals?$select=id,status,customerProfile |
| $filter | Filtra los resultados | Recomendado | /referrals?$filter=engagementId eq '65edc0b5-3485-41b7-a17e-dfa9ef4706e2' /referrals?$filter=status eq 'New' and qualification eq 'SalesQualified' /referrals?$filter=customerProfile/address/country eq 'US' and direction eq 'Incoming' |
| $orderby | Organiza los resultados. | Recomendado | /referrals?$orderby=createdDateTime desc |
Parámetros orderby admitidos
Use los siguientes parámetros de $orderby para ordenar la lista de clientes potenciales y oportunidades.
| Nombre | Escribir | Descripción |
|---|---|---|
| createdDateTime | DateTime | Fecha y hora de creación del cliente potencial o la oportunidad |
| updatedDateTime | DateTime | Actualizar la fecha y hora del cliente potencial o la oportunidad |
Encabezados de solicitud
Para obtener más información, consulte Encabezados REST de asociados.
Cuerpo de la solicitud
Ninguno.
Ejemplo de solicitud
GET https://api.partner.microsoft.com/v1.0/engagements/referrals?$orderby=createdDateTime desc HTTP/1.1
Authorization: Bearer <token>
Content-Type: application/json
Respuesta REST
Si se ejecuta correctamente, el cuerpo de la respuesta contiene una colección de clientes potenciales o oportunidades.
Códigos de error y de respuesta correctos
Cada respuesta incluye un código de estado HTTP que indica éxito o error y otra información de depuración. Use una herramienta de seguimiento de red para leer este código, el tipo de error y más parámetros.
Ejemplo de respuesta
HTTP/1.1 200 OK
Request-ID: 9f8bed52-e4df-4d0c-9ca6-929a187b0731
Content-Type: application/json
{
"@odata.context": "http://api.partner.microsoft.com/v1.0/$metadata#Referrals",
"@odata.count": 1,
"value": [
{
"id": "c5fbb3b6-be74-4795-9fb5-4324c73fed37",
"engagementId": "65edc0b5-3485-41b7-a17e-dfa9ef4706e2",
"organizationId": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
"organizationName": "Contoso Company",
"createdDateTime": "2020-10-30T21:03:00.0000000Z",
"updatedDateTime": "2020-10-30T21:03:00.0000000Z",
"status": "New",
"substatus": "Pending",
"qualification": "Direct",
"type": "Independent",
"direction": "Incoming",
"customerProfile": {
"name": "Fabrikam Customer Inc",
"address": {
"addressLine1": "One Microsoft Way",
"addressLine2": "",
"city": "Redmond",
"state": "WA",
"postalCode": "98052",
"country": "US"
}
},
"details": {
"notes": "We are interested in deploying Microsoft 365 and are looking for support in training our employees. Can you help?",
"dealValue": 10000,
"currency": "USD",
"closingDateTime": "2020-12-01T00:00:00Z",
"requirements": {
"industries": [ { "id": "Education" } ],
"products": [ { "id": "Microsoft365" } ],
"services": [ { "id": "LearningAndCertification" } ],
"solutions": [ { "id": "SOL-Microsoft365", "name": "Microsoft365" }
]
}
},
"links": {
"relatedReferrals": {
"uri": "https://api.partner.microsoft.com/v1.0/engagements/referrals?$filter=engagementId eq '65edc0b5-3485-41b7-a17e-dfa9ef4706e2'",
"method": "GET"
},
"self": {
"uri": "https://api.partner.microsoft.com/v1.0/engagements/referrals/c5fbb3b6-be74-4795-9fb5-4324c73fed37",
"method": "GET"
}
}
}
],
"@odata.nextLink": "http://api.partner.microsoft.com/v1.0/referrals?$skiptoken=k181pEdP0ykypkieJfcxX"
}
@odata.nextLink Use para obtener la siguiente página de resultados.
Nota:
Los campos de este ejemplo no son exhaustivos. La respuesta de API real contiene más campos, como el cliente y los equipos asociados. Para obtener la lista completa de campos admitidos, consulte recursos de referencia.
Solicitudes de ejemplo
En el ejemplo siguiente se recuperan las 10 oportunidades de venta conjunta de entrada más recientes. La solicitud captura las oportunidades iniciadas por un representante de ventas de Microsoft u otro asociado, invitando a su organización a participar en una actividad de venta conjunta.
GET https://api.partner.microsoft.com/v1.0/engagements/referrals?$top=10&$filter=(type eq 'Shared' and direction eq 'Incoming')&$orderby=createdDateTime desc HTTP/1.1
Authorization: Bearer <token>
Content-Type: application/json
En el ejemplo siguiente se recuperan los clientes potenciales entrantes y las oportunidades más recientes a los que no se responde.
GET https://api.partner.microsoft.com/v1.0/engagements/referrals?$top=10&$filter=(direction eq 'Incoming' and substatus eq 'Pending')&$orderby=createdDateTime desc HTTP/1.1
Authorization: Bearer <token>
Content-Type: application/json
Importante
Si no responde a un cliente potencial o a una oportunidad dentro del tiempo asignado (actualmente 14 días), lo archivaremos como Expirado y notificaremos a Microsoft o al partner que le envió esta oportunidad.
En el ejemplo siguiente se obtienen las oportunidades de venta conjunta activas más recientes iniciadas por su organización y trabajadas por un vendedor específico.
GET https://api.partner.microsoft.com/v1.0/engagements/referrals?$filter=status eq 'Active' and direction eq 'Outgoing' and type eq 'Shared' and team/any(t:t/email eq 'r2d2@contoso.com')&$orderby=createdDateTime desc HTTP/1.1
Authorization: Bearer <token>
Content-Type: application/json