Atualizar um lead ou oportunidade

Este artigo explica como atualizar os detalhes do lead ou da oportunidade, como o valor do negócio, a data de fechamento estimada ou gerenciar as etapas de vendas, entre outros detalhes.

Pré-requisitos

  • Credenciais conforme descrito em Autenticação da API de recomendações. 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
PATCH https://api.partner.microsoft.com/v1.0/engagements/referrals/{ID}

Parâmetro URI

Nome Tipo Obrigatório Descrição
ID cadeia (de caracteres) Sim O identificador único para uma oportunidade de lead ou de co-venda

Cabeçalhos da requisição

Para mais informações, consulte Cabeçalhos REST de Parceiros.

Corpo do pedido

O corpo da solicitação segue o formato JSON Patch. Um documento de patch JSON tem uma matriz de operações. Cada operação identifica um tipo específico de alteração. Exemplos de tais alterações incluem a adição de um elemento de matriz ou a substituição de um valor de propriedade.

Importante

Atualmente, a API suporta apenas as operações replace e add.

Exemplo de solicitação

PATCH https://api.partner.microsoft.com/v1.0/engagements/referrals/{ID} HTTP/1.1
Authorization: Bearer <token>
Prefer: return=representation
Content-Type: application/json

[
    {
        "op": "replace",
        "path": "/details/dealValue",
        "value": "10000"
    },
    {
        "op": "add",
        "path": "/team/-",
        "value": {
            "email": "jane.doe@contoso.com",
            "firstName": "Jane",
            "lastName": "Doe",
            "phoneNumber": "0000000001"
        }
    }
]

Nota

Se o cabeçalho If-Match for passado, ele será usado para controlo de concorrência.

Resposta REST

Se bem-sucedida, o corpo da resposta contém o lead ou oportunidade atualizado.

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 para depuração. Use uma ferramenta de rastreamento de rede para ler esse código, o tipo de erro e outros parâmetros.

Exemplo de resposta

HTTP/1.1 204 No Content
Content-Length: 0
Request-ID: 9f8bed52-e4df-4d0c-9ca6-929a187b0731

Gorjeta

O corpo da resposta depende do cabeçalho Prefer. Se o valor do cabeçalho for omitido no pedido, o corpo da resposta fica vazio com o código HTTP Status 204. Adicione Prefer: return=representation ao cabeçalho para obter o lead ou a oportunidade atualizada.

Pedidos de amostra

  1. Atualiza o valor do negócio para a oportunidade para 10000 e atualiza as notas. Não há verificações de concorrência devido à ausência do cabeçalho If-Match.

    PATCH https://api.partner.microsoft.com/v1.0/engagements/referrals/{ID}
Authorization: Bearer <token>
Content-Type: application/json

[
    {"op":"replace","path":"/details/dealValue","value":"10000"},
    {"op":"replace","path":"/details/notes","value":"Lorem ipsum dolor sit amet."}
]

  2. Atualiza o estado de um lead ou oportunidade para Vencido.

    PATCH https://api.partner.microsoft.com/v1.0/engagements/referrals/{ID}
Authorization: Bearer <token>
Content-Type: application/json

[
    {"op":"replace", "path":"/status", "value":"Closed"},
    {"op":"replace", "path":"/substatus", "value":"Won"}
]

    Importante

    Os status e substatus campos devem estar em conformidade com o conjunto permitido de valores de transição.

  3. Adiciona um novo membro da sua organização à equipe principal ou de oportunidade. A resposta contém o lead ou a oportunidade atualizado por causa da presença do cabeçalho Prefer: return=representation.

    PATCH https://api.partner.microsoft.com/v1.0/engagements/referrals/{ID} HTTP/1.1
Authorization: Bearer <token>
Prefer: return=representation
Content-Type: application/json

[
    {
        "op": "add",
        "path": "/team/-",
        "value": {
            "email": "jane.doe@contoso.com",
            "firstName": "Jane",
            "lastName": "Doe",
            "phoneNumber": "0000000001"
        }
    }
]

Criar Registos de Negócios

Use a API de Registo de Negócios para criar um registo de negócio no Centro de Parceiros quando tanto o parceiro como a referência forem elegíveis. Para mais informações sobre conceitos e fluxos de trabalho de registo de negócios, consulte registar acordos no Centro de Parceiros.

Requisitos de elegibilidade

  • O parceiro deve ser aprovado para registo de negócios com base nos critérios de elegibilidade da Microsoft.
  • A recomendação deve apoiar o registo de transações.

Como funciona a elegibilidade?

  • A elegibilidade dos parceiros é determinada pela Microsoft e não é gerida através do espaço de trabalho Referrals do Partner Center.
  • Pode validar programaticamente a elegibilidade dos parceiros ligando para a API de Elegibilidade para Registo de Negócios de Parceiros antes de criar um registo de negócio.
  • A resposta da API indica se o chamador pode prosseguir com a criação do registo do negócio.

Os requisitos de elegibilidade garantem que apenas parceiros elegíveis possam registar acordos e ajudam a prevenir submissões falhadas ou inválidas.

API de Elegibilidade para Registo de Negócios de Parceiros

Sintaxe da solicitação

Método URI do pedido
GET https://api.partner.microsoft.com/v1.0/engagements/partners/dealregistrationeligibility

Exemplo de solicitação

GET https://api.partner.microsoft.com/v1.0/engagements/partners/dealregistrationeligibility HTTP/1.1
Authorization: Bearer <token>
Prefer: return=representation

Resposta do REST

Se for bem-sucedido, o órgão de resposta contém o estatuto de elegibilidade.

Códigos de sucesso e erro de resposta

Cada resposta vem com um código de status HTTP que indica sucesso ou falha, bem como informações de depuração. Use uma ferramenta de rastreamento de rede para ler esse código, o tipo de erro e quaisquer parâmetros.

Exemplo de resposta

HTTP/1.1 200 OK
Request-ID: 2d1bed51-2fd9-adfc-h4a7-019kk87c0627
Content-Type: application/json

{
  "isEligible": true,
  "policies": [
    {
      "isEligible": true
    }
  ]
}

Elegibilidade para Registo de Acordo de Referência

Uma referência é elegível para registo de negócio se todas as seguintes condições forem cumpridas:

  • O tipo de negócio é Co-sell.
  • O cliente é Microsoft Managed.
  • O valor total do negócio é superior a USD 25.000.
  • Pelo menos uma solução associada é elegível para co-venda do Azure IP.
  • O estado de referência da Microsoft é Aceite.

Também pode validar a elegibilidade de recomendações de forma programática chamando a API de Elegibilidade para Registo de Negócios. A resposta da API confirma se uma recomendação de co-venda é elegível para o registo de negócios.

API de Elegibilidade para Registo de Negócios

Sintaxe da solicitação

Método URI do pedido
POST https://api.partner.microsoft.com/v1.0/engagements/referrals/{ID}/dealregistrations/eligibility

Parâmetro URI

Nome Tipo Obrigatório Descrição
ID cadeia (de caracteres) Sim O identificador único para uma oportunidade de co-venda

Exemplo de solicitação

POST https://api.partner.microsoft.com/v1.0/engagements/referrals/{ID}/dealregistrations/eligibility HTTP/1.1
Authorization: Bearer <token>
Prefer: return=representation

Nota

Embora seja um pedido POST, não existe um payload a fornecer para este pedido http.

Resposta do REST

Se for bem-sucedido, o órgão de resposta contém o estado de elegibilidade e o conjunto de políticas de elegibilidade falhadas e aprovadas.

Códigos de sucesso e erro de resposta

Cada resposta vem com um código de estado HTTP que indica sucesso ou falha e informações de depuração. Use uma ferramenta de rastreamento de rede para ler esse código, o tipo de erro e quaisquer parâmetros.

Exemplo de resposta

HTTP/1.1 200 OK
Request-ID: 9f8bed52-e4df-4d0c-9ca6-929a187b0731
Content-Type: application/json

{
  "isEligible": true,
  "passedPolicies": [
    {
      "policyName": "isDealTypeCosellOrPartnerLed",
      "isEligible": true,
      "referralProperties": {
        "type": "Shared"
      }
    },
    {
      "policyName": "isMicrosoftReferralAcceptedOrWon",
      "isEligible": true,
      "referralProperties": {
        "status": "Active",
        "substatus": "Accepted"
      }
    },
    {
      "policyName": "isSolutionIncentiveEligible",
      "isEligible": true,
      "referralProperties": {
        "solutionId": "DEAL-123456-XYZ",
        "solutionName": "Contoso Experience Platform"
      },
      "additionalProperties": [
        "MSFT Internal Azure IP Co-Sell"
      ]
    },
    {
      "policyName": "isDealValueEligible",
      "isEligible": true,
      "referralProperties": {
        "currency": "USD",
        "dealValue": "30000"
      }
    },
    {
      "policyName": "isCustomerManaged",
      "isEligible": true,
      "referralProperties": {
        "isMatchingComplete": "true"
      },
      "additionalProperties": [
        "Managed"
      ]
    }
  ],
  "failedPolicies": []
}

API de Registo de Negócios

Usar a operação de atualização de acordos existente (API PATCH) para criar um registo de acordos.

Exemplo de solicitação

PATCH https://api.partner.microsoft.com/v1.0/engagements/referrals/{ID} HTTP/1.1
Authorization: Bearer <token>
Prefer: return=representation
Content-Type: application/json

[
    {
        "op":"add",
        "path":"/registrations/-",
        "value":{
            "type":"AzureIPCoSell",
            "contract":{
                "currency":"USD",
                "endDateTime":"2026-02-28T09:14:19.454Z",
                "signDateTime":"2026-02-12T09:14:10.783Z",
                "startDateTime":"2026-02-12T09:14:16.319Z",
                "term":"Finite",
                "value":250000
            },
            "solutionDetails":[
                {
                    "id":"DEAL-123456-XYZ",
                    "isDeployedOnAzure":true,
                    "marketplaceTransactionDetails":{
                        "isMarketplaceTransacted":true,
                        "marketplaceTransactionDateTime":"2026-02-11T09:13:52.105Z"
                    },
                    "primaryDeploymentOn":"Partner",
                    "pricingModel":"Other",
                    "value":250000,
                    "currency":"USD"
                }
            ]
        }
    }
]

Exemplo de resposta

HTTP/1.1 204 No Content
Content-Length: 0
Request-ID: 9f8bed52-e4df-4d0c-9ca6-929a187b0731

Nota

Depois de recebida a resposta de execução bem-sucedida, o parceiro pode buscar a referência de origem para ver o registo de negócios criado.

Conteúdos relacionados

  • Criar uma indicação
  • Last updated on