Ottenere l'elenco di lead e opportunità

Articolo
03/05/2024

Questo articolo illustra come ottenere l'elenco dei lead ricevuti dalla pagina del provider di soluzioni Microsoft e le opportunità di co-selling ricevute dai venditori Microsoft o da altri partner. Questo processo recupera anche l'elenco di opportunità di co-selling o offerte di pipeline create dall'organizzazione.

Nota

I lead ricevuti dal marketplace commerciale Microsoft (Azure Marketplace e AppSource) non sono supportati.

Prerequisiti

Credenziali descritte in Autenticazione per l'API Partner. Questo scenario supporta l'autenticazione con le credenziali dell'app e dell'utente.
Questa API supporta attualmente solo l'accesso utente in cui i partner devono trovarsi in uno dei ruoli seguenti: Global Amministrazione, Referral Amministrazione o Referral User.

Richiesta REST

Sintassi della richiesta

metodo	URI della richiesta
GET	`https://api.partner.microsoft.com/v1.0/engagements/referrals`

Operazioni OData supportate

Nome	Descrizione	Richiesto	Esempio
$select	Seleziona i campi	No	`/referrals?$select=id,status,customerProfile`
$filter	Filtri risultati	Consigliato	`/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	Ordina i risultati	Consigliato	`/referrals?$orderby=createdDateTime desc`

Parametri di orderby supportati

Usare i parametri di $orderby seguenti per ordinare l'elenco di lead e opportunità

Nome	Tipo	Descrizione
createdDateTime	Data/Ora	Data e ora di creazione del lead o dell'opportunità
updatedDateTime	Data/Ora	Aggiornare la data e l'ora del lead o dell'opportunità

Intestazioni delle richieste

Per altre informazioni, vedi Intestazioni dell'API REST Partner.

Corpo della richiesta

Nessuno.

Esempio di richiesta

GET https://api.partner.microsoft.com/v1.0/engagements/referrals?$orderby=createdDateTime desc HTTP/1.1
Authorization: Bearer <token>
Content-Type: application/json

Risposta REST

In caso di esito positivo, il corpo della risposta contiene una raccolta di lead e/o opportunità.

Codici di errore e di esito della risposta

Ogni risposta viene fornita con un codice di stato HTTP che indica l'esito positivo o negativo e altre informazioni di debug. Usare uno strumento di traccia di rete per leggere questo codice, il tipo di errore e altri parametri.

Risposta di esempio

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 Usare per ottenere la pagina successiva dei risultati.

Nota

I campi in questo esempio non sono esaustivi. La risposta api effettiva contiene più campi, ad esempio i team dei clienti e dei partner. Per l'elenco completo dei campi supportati, vedere risorse di riferimento.

Richieste di esempio

L'esempio seguente ottiene le prime 10 opportunità di co-selling in ingresso più recenti. La richiesta recupera le opportunità avviate da un rappresentante microsoft o da un altro partner, invitando l'organizzazione a partecipare a un'attività di co-selling.

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

L'esempio seguente ottiene i lead in ingresso e le opportunità più recenti a cui non è stata risposta.

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

Se non rispondi a un lead o a un'opportunità entro il tempo assegnato (attualmente 14 giorni), lo archivieremo come Scaduto e informeremo Microsoft o il partner che ti ha inviato questa opportunità.

L'esempio seguente ottiene le opportunità di co-selling attive più recenti avviate dall'organizzazione e lavorate da un venditore specifico.

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

Passaggi successivi

Creare una segnalazione

Share via