Obtener la lista de clientes potenciales y oportunidades

  • Artículo

En este artículo se explica cómo obtener la lista de clientes potenciales recibidos de la página del proveedor de soluciones de Microsoft y las oportunidades de venta conjunta recibidas de vendedores de Microsoft u otros asociados. Este proceso también capturará 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 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.
  • Actualmente, esta API solo admite el acceso de usuario en el que los asociados deben estar en uno de los siguientes roles: global Administración, referencia Administración 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 Tipo 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

Consulte Encabezados REST de partners para obtener más información.

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
Content-Type: application/json
Request-ID: 9f8bed52-e4df-4d0c-9ca6-929a187b0731

{
  "@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": "7d23e5ca-19dc-4eaa-aac8-5e6b559f0d1d",
      "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 obtienen 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 obtienen los clientes potenciales entrantes y las oportunidades más recientes a las que no se han respondido.

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

Pasos siguientes