Obter a lista de clientes potenciais e oportunidades
Este artigo explica como obter a lista de leads recebidos da página do provedor de soluções da Microsoft e oportunidades de covenda recebidas de vendedores da Microsoft ou outros parceiros. Esse processo também buscará a lista de oportunidades de co-venda ou negócios de pipeline criados por sua organização.
Observação
Não há suporte para leads recebidos do mercado comercial da Microsoft (Azure Marketplace e AppSource).
Pré-requisitos
- Credenciais conforme descrito em Autenticação de API do Partner. Este cenário dá suporte à autenticação com credenciais de aplicativo + usuário.
- Atualmente, essa API oferece suporte apenas ao acesso de usuários em que os parceiros devem estar em uma das seguintes funções: Administrador Global, 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 | Filtra 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 | Classifica os resultados | Recomendado | /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 | Data e hora de atualização do lead ou oportunidade |
Cabeçalhos da solicitação
Consulte cabeçalhos REST de Parceiro para obter mais informações.
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 contém uma coleção de leads e/ou oportunidades.
Códigos de êxito e de erro de resposta
Cada resposta vem com um código de status HTTP que indica sucesso 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
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"
}
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 com suporte, consulte Recursos de referência.
Solicitações de exemplo
O exemplo a seguir obtém as 10 principais oportunidades de covenda 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 covenda.
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 obtém os leads de entrada mais recentes e as oportunidades que não foram respondidas.
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 lead ou oportunidade dentro do tempo alocado (atualmente 14 dias), arquivaremos como Expirado e notificaremos a Microsoft ou o parceiro que lhe enviou essa oportunidade.
O exemplo a seguir obtém as oportunidades de covenda ativas mais recentes iniciadas por sua organização e que estão sendo 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
Próximas etapas
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de