Actualiza un cliente potencial o una oportunidad

En este artículo se explica cómo actualizar los detalles del cliente potencial o de la oportunidad, como el valor de la oferta, la fecha de cierre estimada o administrar las fases de ventas entre otros detalles.

Requisitos previos

• Credenciales tal como se describe en Autenticación de la API de Referencias. Este escenario admite la autenticación con credenciales de aplicación y usuario.
• Actualmente, esta API solo admite el acceso de usuario donde los asociados deben estar en uno de los roles siguientes: Administrador de referencias o Usuario de referencia.

Solicitud REST

Sintaxis de la solicitud

Método	URI de solicitud
PATCH	https://api.partner.microsoft.com/v1.0/engagements/referrals/{ID}

Parámetro de URI

Nombre	Tipo	Obligatorio	Descripción
Identificación	string	Sí	Identificador único de cliente potencial o de oportunidad de venta conjunta

Encabezados de solicitud

Para obtener más información, consulte Encabezados REST de Partner.

Cuerpo de la solicitud

El cuerpo de la solicitud sigue el formato Json Patch. Un documento JSON Patch tiene una matriz de operaciones. Cada operación identifica un tipo determinado de cambio. Algunos ejemplos de estos cambios incluyen agregar un elemento de matriz o reemplazar un valor de propiedad.

Importante

Actualmente, la API solo admite las operaciones replace y add.

Ejemplo de solicitud

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:

Si se pasa el encabezado If-Match, se usará para el control de concurrencia.

Respuesta REST

Si tiene éxito, el cuerpo de la respuesta contiene el cliente potencial o la oportunidad actualizados.

Códigos de respuesta exitosos y de error

Cada respuesta incluye un código de estado HTTP que indica éxito o fallo y otra información de depuración. Use una herramienta de seguimiento de red para leer este código, el tipo de error y otros parámetros.

Ejemplo de respuesta

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

Sugerencia

El cuerpo de la respuesta depende del Prefer header. Si se omite el valor del encabezado en la solicitud, el cuerpo de la respuesta está vacío con un código de estado HTTP 204. Agregue Prefer: return=representation al encabezado para obtener el cliente potencial o la oportunidad actualizados.

Solicitudes de ejemplo

1. Actualiza el valor del acuerdo para la oportunidad a 10000 y actualiza las notas. No hay comprobaciones de simultaneidad debido a la ausencia del If-Match encabezado.

   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. Actualiza el estado de un cliente potencial o una oportunidad para Won.

   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

   Los campos status y substatus deben ajustarse al conjunto permitido de valores de transición.

3. Agrega un nuevo miembro de su organización al equipo de lead o de oportunidad. La respuesta contiene el lead o la oportunidad actualizados debido a la presencia del Prefer: return=representation encabezado.

   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"
           }
       }
   ]
   

Crear registros de ofertas

Utiliza la API de registro de ofertas para crear un registro de ofertas en el Centro de colaboradores cuando el asociado y la referencia sean aptos. Para obtener más información sobre los conceptos y flujos de trabajo de registro de ofertas, consulte Registrar ofertas en Partner Center.

Requisitos de idoneidad

• El asociado debe aprobarse para el registro de ofertas en función de los criterios de idoneidad de Microsoft.
• La referencia debe soportar el registro de ofertas.

¿Cómo funciona la idoneidad?

• Microsoft determina la idoneidad de los partners y no se gestiona a través del área de trabajo de Referencias del Centro de Partners.
• Puede validar mediante programación la idoneidad de los partners llamando a la API de elegibilidad de registro de ofertas de partners antes de crear un registro de ofertas.
• La respuesta de la API indica si el autor de la llamada puede continuar con la creación del registro de ofertas.

Los requisitos de idoneidad garantizan que solo los partners elegibles puedan registrar ofertas y ayudan a evitar envíos erróneos o no válidos.

API de elegibilidad para el registro de ofertas de socios

Sintaxis de la solicitud

Método	URI de solicitud
OBTÉN	https://api.partner.microsoft.com/v1.0/engagements/partners/dealregistrationeligibility

Ejemplo de solicitud

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

Respuesta REST

Si se ejecuta correctamente, el cuerpo de la respuesta contiene el estado de elegibilidad.

Códigos de éxito y de error de respuesta

Cada respuesta incluye un código de estado HTTP que indica éxito o fracaso, así como información para depuración. Use una herramienta de seguimiento de red para leer este código, el tipo de error y los parámetros.

Ejemplo de respuesta

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

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

Elegibilidad para el registro de acuerdos de referencia

Una referencia es apta para el registro de ofertas si se cumplen todas las condiciones siguientes:

• El tipo de oferta es Venta conjunta.
• El cliente es administrado por Microsoft.
• El valor total de la oferta es mayor que 25 000 USD.
• Al menos una solución asociada es válida para la venta conjunta de IP de Azure.
• El estado de referencia de Microsoft es Aceptado.

También puede validar la elegibilidad de referencia usando una llamada programática a la API para la elegibilidad de registro de ofertas. La respuesta de la API confirma si una referencia de venta conjunta determinada califica para el registro de ofertas.

API de elegibilidad para el registro de acuerdos comerciales

Sintaxis de la solicitud

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

Parámetro de URI

Nombre	Tipo	Obligatorio	Descripción
ID (Identificación)	string	Sí	Identificador único de una oportunidad de venta conjunta

Ejemplo de solicitud

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

Nota:

Aun si se trata de una solicitud POST, no hay datos que deban proporcionarse para esta solicitud HTTP.

Respuesta REST

Si se ejecuta correctamente, el cuerpo de la respuesta contiene el estado de elegibilidad y el conjunto de políticas de elegibilidad fallidas y aprobadas.

Códigos de éxito y error de respuesta

Cada respuesta viene con un código de estado HTTP que indica éxito o fallo, así como datos para depuración. Use una herramienta de seguimiento de red para leer este código, el tipo de error y los parámetros.

Ejemplo de respuesta

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 ofertas

Use la operación de actualización de ofertas existente (PATCH API) para crear un registro de ofertas.

Ejemplo de solicitud

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"
                }
            ]
        }
    }
]

Ejemplo de respuesta

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

Nota:

Una vez recibida la respuesta de ejecución exitosa, el asociado puede obtener la referencia de origen para ver el registro de oportunidades creado.

Contenido relacionado

• Crear una referencia