Obter a lista de oportunidades potenciais e oportunidades
Este artigo explica como obter a lista de leads e oportunidades de co-venda. Esses leads são recebidos da página Provedor de Soluções da Microsoft, enquanto as oportunidades de covenda são recebidas de vendedores da Microsoft ou de outros parceiros. Esse processo também busca a lista de oportunidades de covenda ou negócios de pipeline criados pela sua organização.
Nota
Não há suporte para leads recebidos do mercado comercial da Microsoft (Azure Marketplace e AppSource).
Pré-requisitos
- Credenciais conforme descrito em Autenticação da API de referências. Este cenário oferece suporte à autenticação com credenciais App+User.
- Atualmente, essa API suporta apenas o acesso de usuários em que os parceiros devem estar em uma das seguintes funções: Administrador de referência ou Usuário de referência.
Pedido REST
Sintaxe da solicitação
| Método | URI do pedido |
|---|---|
| GET | https://api.partner.microsoft.com/v1.0/engagements/referrals |
Operações OData suportadas
| Nome | Descrição | Obrigatório | Exemplo |
|---|---|---|---|
| $select | Seleciona campos | Não | /referrals?$select=id,status,customerProfile |
| $filter | Filtra os 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 | Resultados das encomendas | Recomendado | /referrals?$orderby=createdDateTime desc |
Orderby parâmetros suportados
Use os seguintes parâmetros de $orderby para classificar a lista de leads e oportunidades
| Nome | Tipo | Description |
|---|---|---|
| createdDateTime | DateTime | Data e hora de criação do lead ou oportunidade |
| atualizadoDateTime | DateTime | Data e hora de atualização do lead ou oportunidade |
Cabeçalhos do pedido
Para obter mais informações, consulte Cabeçalhos REST de parceiros.
Corpo do pedido
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 do REST
Se for bem-sucedido, o corpo da resposta contém uma coleção de leads e/ou oportunidades.
Códigos de sucesso e 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
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.
Nota
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 suportados, consulte Recursos de referência.
Pedidos de amostra
O exemplo a seguir recupera 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 recupera os leads de entrada mais recentes e as oportunidades às quais 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 pela 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