Obter a lista de clientes potenciais e oportunidades
Este artigo explica como obter a lista de leads e oportunidades de venda conjunta. Esses clientes potenciais são recebidos da página Provedor de Soluções da Microsoft, enquanto as oportunidades de venda conjunta são recebidas de vendedores da Microsoft ou de outros parceiros. Esse processo também busca a lista de oportunidades de venda conjunta ou negócios de pipeline criados por sua organização.
Observação
Não há suporte para clientes potenciais recebidos do marketplace comercial da Microsoft (Azure Marketplace e AppSource).
Pré-requisitos
- Credenciais, conforme descrito em Autenticação da API de referências. Este cenário dá suporte à autenticação com credenciais de aplicativo + usuário.
- No momento, essa API oferece suporte apenas ao acesso do usuário, onde os parceiros devem estar em uma das seguintes funções: Administrador de Referência ou Usuário de Referência.
Solicitação REST
Sintaxe da solicitação
| Método | URI da solicitação |
|---|---|
| GET | https://api.partner.microsoft.com/v1.0/engagements/referrals |
Operações OData compatíveis
| Nome | Descrição | Necessário | Exemplo |
|---|---|---|---|
| $select | Seleciona campos | Não | /referrals?$select=id,status,customerProfile |
| $filter | Resultados dos filtros | Recomendadas | /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 | Classifica os resultados | Recomendadas | /referrals?$orderby=createdDateTime desc |
Parâmetros orderby compatíveis
Use os seguintes parâmetros $orderby para classificar a lista de leads e oportunidades
| Nome | Tipo | Descrição |
|---|---|---|
| createdDateTime | Datetime | Data e hora de criação do lead ou oportunidade |
| updatedDateTime | Datetime | Atualizar data e hora do lead ou oportunidade |
Cabeçalhos da solicitação
Para obter mais informações, consulte Cabeçalhos REST do parceiro.
Corpo da solicitação
Nenhum.
Exemplo de solicitação
GET https://api.partner.microsoft.com/v1.0/engagements/referrals?$orderby=createdDateTime desc HTTP/1.1
Authorization: Bearer <token>
Content-Type: application/json
Resposta REST
Se for bem-sucedido, o corpo da resposta conterá uma coleção de clientes potenciais e/ou oportunidades.
Códigos de êxito e de erro de resposta
Cada resposta vem com um código de status HTTP que indica êxito ou falha e outras informações de depuração. Use uma ferramenta de rastreamento de rede para ler esse código, o tipo de erro e mais parâmetros.
Exemplo de resposta
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"
}
Use o @odata.nextLink para obter a próxima página de resultados.
Observação
Os campos neste exemplo não são exaustivos. A resposta real da API contém mais campos, como as equipes de clientes e parceiros. Para obter a lista completa de campos compatíveis, consulte recursos de referência.
Solicitações de exemplo
O exemplo a seguir recupera as 10 principais oportunidades de venda conjunta de entrada mais recentes. A solicitação busca oportunidades iniciadas por um representante de vendas da Microsoft ou outro parceiro, convidando sua organização a participar de uma atividade de venda 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
O exemplo a seguir recupera os clientes potenciais e as oportunidades de entrada mais recentes que não são respondidos.
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 você não responder a um cliente potencial ou oportunidade dentro do tempo alocado (atualmente 14 dias), nós o arquivaremos como Expirado e notificaremos a Microsoft ou o parceiro que lhe enviou essa oportunidade.
O exemplo a seguir obtém as oportunidades de venda conjunta ativas mais recentes iniciadas por sua organização e trabalhadas por um 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