Atualizar um cliente potencial ou uma 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 Referrals API authentication. 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
PATCH https://api.partner.microsoft.com/v1.0/engagements/referrals/{ID}

Parâmetro do URI

Nome Tipo Obrigatória Descrição
ID cadeia Sim O identificador exclusivo para um lead ou uma oportunidade de venda conjunta

Cabeçalhos da solicitação

Para obter mais informações, consulte os Cabeçalhos REST do Parceiro.

Corpo da solicitação

O corpo da solicitação segue o formato Json Patch. Um documento de JSON Patch tem uma matriz de operações. Cada operação identifica um tipo específico de alteração. Exemplos dessas 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 de 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"
        }
    }
]

Observação

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

Resposta REST

Se for bem-sucedido, o corpo da resposta conterá o cliente potencial ou a oportunidade atualizada.

Códigos de êxito e de erro de resposta

Cada resposta vem com um código de status HTTP que indica êxito ou falha, além de outras informações de 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

Dica

O corpo da resposta depende do cabeçalho Prefer. Se o valor do cabeçalho for omitido na solicitação, o corpo da resposta estará vazio com um código de status HTTP 204. Adicione Prefer: return=representation ao cabeçalho para acessar o lead ou oportunidade atualizado.

Solicitações de exemplo

  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 status de um cliente potencial ou oportunidade para Ganho.

    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 campos status e substatus devem conformar-se ao conjunto permitido de valores de transição.

  3. Adiciona um novo membro da sua organização à equipe de liderança ou oportunidade. A resposta contém o lead ou oportunidade atualizado devido à 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 registros de negociação

Use a API de Registro de Oferta para criar um registro de oferta no Partner Center quando tanto o parceiro quanto a indicação estiverem qualificados. Para obter mais informações sobre os conceitos de registro de negócios e fluxos de trabalho, consulte registrar ofertas no Partner Center.

Requisitos de qualificação

  • O parceiro deve ser aprovado para registro de acordo com base nos critérios de qualificação da Microsoft.
  • A indicação deve dar suporte ao registro de negócios.

Como funciona a qualificação?

  • A qualificação do parceiro é determinada pela Microsoft e não é gerenciada por meio do espaço de trabalho de referências do Partner Center.
  • Você pode verificar programaticamente a qualificação do parceiro chamando a API de Qualificação de Partner Deal antes de criar um registro de transação.
  • A resposta da API indica se o chamador tem permissão para prosseguir com a criação do registro do negócio.

Os requisitos de qualificação garantem que somente parceiros qualificados possam registrar acordos e ajudar a evitar envios com falha ou inválidos.

API de elegibilidade de registro de negócio de parceiro

Sintaxe da solicitação

Método URI da solicitação
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 REST

Se bem-sucedido, o corpo da resposta contém o status de elegibilidade.

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 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 de registro de acordo de indicação

Uma indicação será qualificada para registro de acordo se todas as seguintes condições forem atendidas:

  • O tipo de negócio é co-venda.
  • O cliente está sob gestão de Microsoft Managed.
  • O valor total da oferta é maior que US$ 25.000.
  • Pelo menos uma solução associada é elegível para a venda conjunta de IP do Azure.
  • O status de indicação da Microsoft é Aceito.

Você também pode validar a elegibilidade de indicação programaticamente chamando a API de Elegibilidade de Registro de Ofertas. A resposta da API confirma se uma determinada indicação de venda conjunta se qualifica para o registro do negócio.

API de Elegibilidade de Registro de Proposta

Sintaxe da solicitação

Método URI da solicitação
POST https://api.partner.microsoft.com/v1.0/engagements/referrals/{ID}/dealregistrations/eligibility

Parâmetro do URI

Nome Tipo Obrigatória Descrição
ID cadeia Sim O identificador exclusivo para uma oportunidade de venda conjunta

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

Observação

Embora seja uma solicitação POST, no entanto, não há conteúdo a ser fornecido para essa solicitação http.

Resposta REST

Se bem-sucedido, o corpo da resposta contém o status de elegibilidade e o conjunto de políticas de elegibilidade que falharam e foram aprovadas.

Códigos de êxito e de erro de resposta

Cada resposta vem com um código de status HTTP que indica sucesso ou falha, além de 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 Registro de Transação

Use a operação de atualização de acordo existente (API PATCH) para criar um registro de acordo.

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

Observação

Depois que a resposta de execução bem-sucedida for recebida, o parceiro poderá buscar a referência de origem para ver o registro de acordo criado.

Conteúdo relacionado

  • Criar uma indicação
  • Last updated on