API de oportunidad de ventas
Comenzando
La API de Oportunidades de Venta está relacionada con la gestión de clientes potenciales. La arquitectura de la API de Oportunidades de Venta es inusual porque llama a su CRM para enviar oportunidades de venta.
El objetivo de la API de Oportunidades de Venta es enviar rápidamente oportunidades de venta a los distribuidores, permitiendo un seguimiento rápido con los clientes y actualizaciones de estado fáciles de devolver a BRP.
La sección Comprendiendo la Oportunidad de Venta proporciona información sobre la gestión de clientes potenciales y el uso de la API de Oportunidades de Venta.
Terminología de BRP
Antes de comenzar, definamos algunos términos.
- Un cliente potencial: un cliente prospecto interesado en un producto de BRP. Se dispone de alguna información sobre este cliente prospecto, incluyendo su nombre, número de teléfono o correo electrónico, así como el producto en el que está interesado.
- Oportunidad de venta: Un cliente potencial validado y calificado ha sido asignado a un distribuidor.
- Disposición: Es el resultado de la oportunidad de ventas procesada por el concesionario. La oportunidad de ventas puede resultar en contactar al cliente, una venta de una unidad o abandono.
¿Dónde empezar? ¡Léeme primero!
Antes de empezar a trabajar en esta API, debe leer las siguientes secciones si aún no las ha revisado:
- Información Técnica para información técnica general sobre la API y los entornos.
- Autenticación y Credenciales para obtener detalles sobre autenticación y credenciales.
- Proceso de Certificación para obtener detalles sobre el proceso de certificación y Jira.
- Obteniendo Apoyo para obtener detalles sobre cómo recibir ayuda y Jira.
Resumen empresarial
Tema | Descripción |
|---|---|
Alcance | Liderazgo de ventas en todas las regiones |
Escenarios |
|
Funciones principales |
|
Procesos de negocio compatibles |
|
Beneficios para distribuidores |
|
Beneficios para BRP |
|
Información técnica
Características
Tipo de API | Tipo de DSP | Versión de DCP | Complejidad |
|---|---|---|---|
Obtener datos de BRP | DMS | V3 - Internacional | Baja |
Enviar datos a BRP | CRM | V4 - Norteamérica | Un poco más |
Transacción con BRP | | | Algo más |
Autenticación
La API utiliza Autenticación de Aplicaciones.
Necesitas un token de acceso válido antes de llamar a esta API, o tienes que llamar a la API de Autenticación de Aplicaciones para obtener uno.
¡El token de acceso es válido por 30 minutos! (1799 segundos)
URL base
Prueba | https://qa-cloud-api.brp.com/dcp/v4 |
|---|---|
Producción | https://cloud-api.brp.com/dcp/v4 |
Recurso: Oportunidad de Venta
El recurso de Oportunidad de Venta proporciona información básica sobre las oportunidades de venta de BRP. Incluye información sobre el consumidor, la unidad en la que está interesado y el estado del consumidor.
Representación JSON
{
"sales_opportunity_id": "00Q6s000001TQcaEAG",
"dealer_no": "0000695896",
"language": "en",
"consumer": {
"first_name": "Mike3",
"last_name": "Debrush",
"culture_code": "en-US",
"phone_no": "819 532-1234",
"mobile_no": "819 532-1278",
"email": "[email protected]",
"address": {
"street": "458 Main Street",
"city": "Orlando",
"state": "FL",
"country": "US",
"postal_code": "12562-12345"
}
},
"product_interest": {
"category": "Contest/Events/Demo",
"model": "SSV all track",
"brand": "canam_side_by_side"
},
"status": [
{
"code": "new",
"set_on": "2025-05-20T19:19:00Z"
}
],
"model_number": "0008HSB00",
"comments": "I want a tough SSV",
"assignment_date": "2025-05-20T15:19:00Z",
"start_date": "2025-05-20T19:19:00Z",
"byo_uri": "https://can-am.brp.com/off-road/ca/fr/configuration-et-prix/app.html?platform=SSV_SSP_2_MAX&package=4X4_X&unitid=0008HSB00",
"campaign_name": "",
"event_description": "SD054_FB_CONTEST___ECOMM-WIN-A-PFD-US-EN",
"intent_to_buy": "4-6 months",
"lead_score": "Medium",
"questions_answers" : [
{ "question": "What are you looking for in a SSV?",
"answer": "Sun and fun"
},
{ "question": "Who will use the SSV?",
"answer": "Me and my dog"
}
],
"ownership": {
"brand": "Polaris RZR Trail",
"trade_in": 1000.00
}
}
Propiedades
Propiedad | Tipo | Definición | Notas |
|---|---|---|---|
sales_opportunity_id | string | Identificador de oportunidad de venta | Longitud:18 |
dealer_no | string | El número de distribuidor BRP asignado a la oportunidad de venta. | Longitud:10 |
language | string | Idioma del cliente en código ISO (ISO-639-1) | Formato xx |
consumer | objeto | información del consumidor | |
Recurso: Actualización de Oportunidad de Venta
Un CRM usa el recurso de Actualización de Oportunidad de Venta para enviar actualizaciones de estado para oportunidades de venta.
Representación JSON
{
"sales_opportunity_id": "00Q6s000001WNwGEAW",
"status": [
{
"code": "contacted",
"set_on": "2020-06-13T14:48:12Z"
}
]
}Propiedades
Propiedad | Tipo | Definición | Notas |
|---|---|---|---|
sales_opportunity_id | cadena | Identificador de oportunidad de venta | Longitud:18 |
status* | lista de objetos | La lista de estados asociados a la oportunidad de venta | |
status.code* | cadena | Código de estado del consumidor
| |
status.set_on* | fecha y hora | Fecha y hora en la que se estableció el estado, en formato ISO 8601. | Formato: AAAA-MM-DDTHH:MM:SSZ |
Limitaciones y Restricciones
Métodos de Autenticación del CRM
La API de Oportunidades de Venta soporta dos métodos de autenticación:
- Autenticación OAuth 2.0 usando credenciales de cliente, como se usa en la API de Autenticación de Aplicaciones.
- Firma de Webhook usando SHA256.
❗ La API de Oportunidades de Venta no soporta y no soportará otros métodos de autenticación ❗
Consulta la sección Información Técnica de los Métodos de Autenticación para más información.
Requisitos de Seguridad
- Toda comunicación debe realizarse a través de HTTPS.
- Los endpoints de tokens OAuth y los endpoints de callback deben usar HTTPS.
- Se debe admitir TLS 1.2 o superior.
- Los certificados SSL deben ser válidos y emitidos por una Autoridad Certificadora (CA) de confianza.
- No se permiten certificados autofirmados en entornos de producción.
Comprender la oportunidad de ventas
Vista del proceso a alto nivel
El proceso de oportunidades y clientes potenciales de ventas a alto nivel se muestra a continuación.
El procesamiento de clientes potenciales de ventas es gestionado por el Sistema de Gestión de Leads (LMS) de BRP.
El prospecto de venta se envía al Sistema de Gestión de Prospectos (LMS) de BRP.
LMS valida el prospecto de venta. Si el prospecto es válido, LMS intenta encontrar el concesionario más cercano que ofrezca la línea de productos solicitada por el cliente potencial.
Si no se encuentra ninguno, el prospecto de venta se descarta.
Si se encuentra un concesionario, el prospecto de venta se convierte en una oportunidad de venta.
Si se encuentra un concesionario, la oportunidad de venta se envía a BOSSWeb.
Si el concesionario tiene un CRM certificado por DCP y ha activado la integración LMS (ver la sección Configuración del CRM en BOSSWeb a continuación), la oportunidad de venta se envía al CRM del concesionario.
Si el concesionario no tiene un CRM certificado por DCP o la integración LMS no está activa, no se realiza ninguna acción.
Si la oportunidad de venta se envía correctamente al CRM del concesionario, LMS envía un SMS y un correo electrónico al concesionario con la información de la oportunidad de venta.
El concesionario contacta al cliente potencial para discutir la solicitud.
El concesionario actualiza el estado de la oportunidad de venta en su CRM.
Si la integración LMS está activa, el CRM envía el estado de la oportunidad de venta a LMS. El estado de la oportunidad de venta se envía a BOSSWeb.
De lo contrario, el concesionario actualiza el estado de la oportunidad de venta en BOSSWeb.
Configuración de CRM en BOSSWeb
Para que LMS envíe oportunidades de venta al CRM del concesionario, este debe primero habilitar la integración con LMS.
👉Puedes compartir este documento con tus concesionarios.
La integración del LMS se gestiona en BOSSWeb bajo Administración -> Concesionario, como se muestra a continuación.
El concesionario hace clic en el enlace Términos y Condiciones indicado por la flecha verde en la imagen, y se muestra la página que aparece a continuación.
El concesionario marca la casilla y selecciona una de las herramientas CRM listadas.
❗❗ El concesionario debe seleccionar el CRM que esté en operación en su concesionario ❗❗
Si el concesionario selecciona un CRM aleatorio porque no tiene un CRM certificado por DCP (como suele ocurrir), la integración del LMS no funcionará❗
El distribuidor hace clic en Guardar para habilitar la integración LMS, y el CRM del distribuidor comienza a recibir oportunidades de ventas.
👉 En cualquier momento, el distribuidor puede volver a la página de Términos y Condiciones y desmarcar la casilla para deshabilitar la integración LMS.
En este caso, el CRM deja de recibir oportunidades de ventas.
Configuración del Endpoint del CRM
El proceso para enviar una oportunidad de venta a un CRM se muestra a continuación.
Tu CRM debe proporcionar un endpoint para que la API de Oportunidades de Venta envíe oportunidades de venta.
LMS encuentra un distribuidor al cual enviar la oportunidad de venta y recupera el CRM configurado por el distribuidor para la integración con LMS.
La oportunidad de venta se envía a la API de Oportunidades de Venta, incluyendo el nombre del CRM en la consulta.
La API de Oportunidades de Venta busca en su configuración el CRM al cual debe enviarse la oportunidad de venta.
Si no se encuentra el CRM, se devuelve un error a LMS.
Si se encuentra el CRM, se recupera su configuración.
La API de Oportunidades de Venta determina si el CRM usa Autenticación de Aplicación o una firma de webhook.
Si el CRM usa Autenticación de Aplicación, la API de Oportunidades de Venta llama al endpoint de autenticación del CRM para obtener un token Bearer.
Si el CRM usa una firma de webhook, la API de Oportunidades de Venta calcula la firma y la añade al payload.
La API de Oportunidades de Venta llama al endpoint del CRM usando las credenciales configuradas para enviar la oportunidad de venta.
El CRM confirma la recepción de la oportunidad de venta. Si ocurre un error, se devuelve a LMS.
El distribuidor actualiza el estado de la oportunidad de venta en su CRM. El CRM envía el estado a la API de Oportunidades de Venta.
La API de Oportunidades de Venta envía el estado a LMS.
Para cada CRM certificado por DCP, la API de Oportunidades de Venta requiere los siguientes parámetros:
- El endpoint que se debe llamar para enviar la oportunidad de venta.
- Un nombre de usuario (ID de cliente).
- Una contraseña (secreto de cliente).
- El endpoint que se debe llamar para obtener un token de acceso OAuth 2.0 Bearer, si el CRM utiliza autenticación OAuth 2.0.
❗❗ La API de Oportunidades de Venta requiere que se utilice autenticación basada en tokens OAuth 2.0 o una firma de webhook por parte del CRM para el endpoint proporcionado ❗❗
Gestión de Errores
Si su CRM detecta un error mientras procesa la oportunidad de venta, debe devolver un rango de códigos de estado estándar RFC 9110 y una carga útil JSON que describa el error.
Puede consultar la sección Código de estado de la respuesta para obtener pautas.
La carga útil JSON de error debe basarse en la carga útil descrita en la sección Carga útil de respuesta Su carga útil debe contener como mínimo un campo de texto que describa el error.
Resumen de lo que debe proporcionar
Cuando empiece a trabajar con la API de Oportunidades de Venta, debe proporcionar la información que se indica a continuación.
Para proporcionar la información:
- Descargue el archivo de Excel.
- Complete la hoja correspondiente al método de autenticación que utiliza su CRM.
- Envíe el archivo por correo electrónico a [email protected] o adjúntelo a su ticket de certificación de Jira de la API de Oportunidades de Ventas.
Entorno | Método de Autenticación | Información |
|---|---|---|
Prueba | Todos | La URL utilizada para enviar las oportunidades de venta a su CRM en su entorno de prueba. |
Prueba | OAuth | ID de Cliente |
Prueba | OAuth | Secreto de Cliente |
Prueba | OAuth | URL utilizada para obtener un token Bearer. |
Prueba | Firma | Secreto de la aplicación para firmar la carga útil. |
Prueba | Todos | Uno o más números de distribuidor BRP válidos para enviar oportunidades de venta. |
Producción | Todos | La URL utilizada para enviar las oportunidades de venta a su CRM en su entorno de prueba. |
Producción | OAuth | ID de Cliente |
Producción | OAuth | Secreto de Cliente |
Producción | OAuth | URL utilizada para obtener un token Bearer. |
Producción | Firma | Secreto de la aplicación para firmar la carga útil. |
Información Técnica sobre Métodos de Autenticación
La API de Oportunidades de Venta admite dos métodos de autenticación:
- Autenticación OAuth 2.0 usando credenciales de cliente, como se usa en DCP API de Autenticación de Aplicaciones.
- Firma de webhook usando SHA256.
❗ La API de Oportunidades de Ventas no admite y no admitirá otros métodos de autenticación ❗
Autenticación de Aplicaciones (OAuth 2.0)
Supongamos que su CRM utiliza un método de Autenticación de Aplicaciones (OAuth 2.0) para autorizar solicitudes desde la API de Oportunidades de Ventas a su CRM. En ese caso, su plataforma CRM debe exponer un endpoint de tokens OAuth 2.0 compatible con el Client Credentials Grant (concesión de credenciales de cliente).
La API de Oportunidades de Ventas utilizará este endpoint para obtener un token Bearer, que se usará en el encabezado Authorization de las llamadas API posteriores a su sistema CRM.
Requisitos
Debe proporcionar:
- URL de Token OAuth2 (HTTPS) Un endpoint HTTPS públicamente accesible que admita la concesión de credenciales de cliente, uno para los entornos de prueba y producción.
- Credenciales de Cliente para los entornos de prueba y producción.
- Un ID de cliente
- Un secreto de cliente seguro
- Formato de respuesta del token La respuesta debe devolver un access_token válido y expires_in en formato JSON.
curl --request POST 'https:{Your OAuth2 Token Endpoint}' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id=REPLACE_ME_CLIENT_ID' \
--data-urlencode 'client_secret=REPLACE_ME_CLIENT_SECRET'Mejores prácticas de seguridad
- El endpoint de token debe usar HTTPS
- Los tokens deben tener un tiempo de validez limitado (expires_in) y no ser de larga duración
- Evite exponer credenciales sensibles en registros o mensajes de error
Especificación del Endpoint de Payload
Su sistema debe exponer un endpoint HTTP(S) que acepte payloads JSON enviados por la API de Oportunidades de Ventas. Todas las solicitudes a este endpoint serán autenticadas usando un token Bearer previamente obtenido a través de su servicio de tokens OAuth2.
Autenticación
- Todas las solicitudes incluirán el token Bearer en el encabezado Authorization:
Authorization: Bearer {access_token}- Su sistema debe validar el token antes de procesar el payload.
Requisitos del Endpoint
- URL: [tu_url_de_endpoint] (p. ej., https://api.external-system.com/data/receive)
- Método: POST
- Content-Type: application/json
- Autenticación: Token Bearer (Flujo de Credenciales de Cliente OAuth2)
Carga Útil de Respuesta
Tu endpoint de CRM debe usar el rango estándar de códigos de estado RFC 9110:
- 2xx (Éxito): La solicitud fue recibida, entendida y aceptada correctamente
- 4xx (Error del Cliente): La solicitud contiene sintaxis incorrecta o no puede ser procesada
- 5xx (Error del servidor): El servidor no pudo cumplir una solicitud aparentemente válida
Su endpoint debe devolver al menos los siguientes códigos de estado de respuesta.
Código de estado | Descripción |
|---|---|
200 OK | Indica que la solicitud se ha completado correctamente y la oportunidad de venta está siendo procesada. No se devuelve ningún contenido. |
400 Solicitud Incorrecta | Indica que el servidor no puede o no procesará la solicitud debido a un error del cliente (por ejemplo, sintaxis de solicitud mal formada, estructura inválida del mensaje de solicitud, o enrutamiento engañoso). IMPORTANTE: La respuesta debe indicar los campos del cuerpo de la solicitud o los parámetros de consulta que están en error. |
401 No Autorizado | Indica que la solicitud no se ha aplicado porque carece de credenciales de autenticación válidas. |
404 No Encontrado | Indica que el servidor no pudo encontrar los objetos solicitados; por ejemplo, que no se encontró el concesionario. |
500 Error Interno del Servidor | Indica que el servidor es consciente de que ha cometido un error o que no puede ejecutar el método solicitado. |
504 Tiempo de Espera de la Puerta de Enlace | Indica que la API no recibió una respuesta oportuna de un servidor ascendente al que necesitaba acceder para completar la solicitud. |
Para los códigos de estado de error 4xx y 5xx, se debe devolver una carga útil de respuesta para proporcionar información sobre el error. La carga útil de la respuesta utiliza la estructura que se muestra en la tabla a continuación.
Propiedad | Tipo | Definición |
|---|---|---|
título | cadena | Código que identifica el error o la frase de motivo Uno de
|
mensaje | cadena | Una descripción del error. |
Por ejemplo, si la oportunidad de venta corresponde a un distribuidor que no se encuentra en su CRM, devolvería la siguiente carga útil de respuesta y el código de estado 404.
{
"title": "not_found",
"message": "Dealer 0000690006 not found"
}Seguridad
- El endpoint debe usar HTTPS
- El token Bearer debe validarse de forma segura
- Todos los payloads deben registrarse de forma segura y gestionarse de acuerdo con su política de gobernanza de datos.
Firma del Webhook
El enfoque de firma del webhook es sencillo.
Para garantizar la autenticidad e integridad de los payloads enviados desde la API de Oportunidades de Venta a su aplicación CRM, los firmamos con un HMAC utilizando su clave de aplicación única.
La clave de aplicación que usted proporciona se utiliza para calcular una firma sobre todo el payload usando el algoritmo SHA-256.
La firma luego se agrega al encabezado en el campo X-Hub-Signature-256 antes de que el payload sea enviado a su CRM.
Cuando reciba la carga útil, use la misma clave de aplicación y el algoritmo SHA-256 para calcular la firma y compárela con la que se encuentra en el X-Hub-Signature-256 campo de encabezado.
Si la firma coincide, puede proceder con el procesamiento de la oportunidad de venta. Si no coinciden, rechace la carga útil y devuelva un error 401 Unauthorized.
Definición de la clave de aplicación
La clave de aplicación (también llamada “secreto de firma”) es una cadena aleatoria generada de forma segura asociada con su CRM.
Formato | Cadena hexadecimal de 64 caracteres. Al menos 32 bytes (256 bits), más largo es mejor. Ejemplo: f7d9a47e143a4b298b819f48b3b77e4b24ae746f55c7c35b2c09c1ec3adbe7c2 |
|---|---|
Seguridad | Trata tu clave de aplicación como una contraseña. Guárdala de forma segura en tu servidor. Nunca la expongas a código del lado del cliente o a terceros. Aleatorio criptográficamente seguro. NO debe ser una contraseña o frase legible por humanos. NO debe ser una clave corta o una cadena fácil de adivinar. |
La clave de la aplicación puede generarse usando las bibliotecas disponibles.
import secrets
key = secrets.token_hex(32) # 64-char hex string (32 bytes) )Firmado del Contenido
Calculamos el HMAC del cuerpo bruto de la solicitud usando SHA-256 y la clave de tu aplicación como secreto.
La firma resultante se envía en el encabezado X-Hub-Signature-256.
X-Hub-Signature-256: sha256=<firma>
<firma> es la representación hexadecimal en minúsculas del resultado HMAC.
A continuación se muestra un ejemplo del cálculo de la firma con una carga útil de oportunidad de ventas de muestra y una clave de aplicación aleatoria.
const crypto = require('crypto');
// Application key (hexadecimal string, must match the receiver's expectation)
const appKeyHex = 'f7d9a47e143a4b298b819f48b3b77e4b24ae746f55c7c35b2c09c1ec3adbe7c2';
// Sales Opportunity payload
const payloadObj = { "sales_opportunity_id": "yVg0i5ULZnCJ5IKi8k", "language": "en", "consumer": { "first_name": "John", "last_name": "Doe", "culture_code": "en-US", "phone_no": "555 555-1234", "mobile_no": "555 555-1278", "email": "[email protected]", "address": { "street": "123 Random Street", "city": "Orlando", "state": "FL", "country": "US", "postal_code": "12562-12345" } }, "product_interest": { "category": "Contest/Events/Demo", "model": "SSV all track", "brand": "canam_side_by_side" }, "status": [{ "code": "new", "set_on": "2025-05-20T19:19:00Z" }], "model_number": "0008HSB00", "comments": "I want a tough SSV", "assignment_date": "2025-05-20T15:19:00Z", "start_date": "2025-05-20T19:19:00Z", "byo_uri": "https://can-am.brp.com/off-road/ca/fr/configuration-et-prix/app.html?platform=SSV_SSP_2_MAX&package=4X4_X&unitid=0008HSB00", "campaign_name": "", "event_description": "SD054_FB_CONTEST___ECOMM-WIN-A-PFD-US-EN", "intent_to_buy": "4-6 months", "lead_score": "Medium", "questions_answers": [{ "question": "What are you looking for in a SSV?", "answer": "Sun and fun" }, { "question": "Who will use the SSV?", "answer": "Me and my dog" }], "ownership": { "brand": "Polaris RZR Trail", "trade_in": 1000 }, "customer_no": "0000691232" };
const rawBody = Buffer.from(JSON.stringify(payloadObj), 'utf8');
// Compute the HMAC SHA256 signature (hex digest)
const signature = crypto
.createHmac('sha256', appKeyHex)
.update(rawBody)
.digest('hex');
// Prepare the signature header
const headers = {
'Content-Type': 'application/json',
'X-Hub-Signature-256': `sha256=${signature}`
};
// signature = "1f91bc0b914dd833968daff615988dae63ea177b9a52fb7f5268df20f9e6a824"
console.log(signature);Validación de Payload
Para validar la firma del payload recibido, su CRM debe ejecutar estos pasos:
- Recupere su clave de aplicación (como un arreglo de bytes).
- Lea el cuerpo sin procesar enviado por nuestro CRM.
- Calcule el resumen HMAC-SHA256 del cuerpo utilizando su clave de aplicación.
- Compare su resumen calculado con el valor en el encabezado X-Hub-Signature-256 (después de eliminar el prefijo sha256=).
A continuación se muestra un ejemplo de verificación de firma, acompañado de una carga útil de oportunidad de ventas de muestra y una clave de aplicación generada aleatoriamente.
const crypto = require('crypto');
// --- Payload and key (same as signature creation) ---
const payloadObj = { "sales_opportunity_id": "yVg0i5ULZnCJ5IKi8k", "language": "en", "consumer": { "first_name": "John", "last_name": "Doe", "culture_code": "en-US", "phone_no": "555 555-1234", "mobile_no": "555 555-1278", "email": "[email protected]", "address": { "street": "123 Random Street", "city": "Orlando", "state": "FL", "country": "US", "postal_code": "12562-12345" } }, "product_interest": { "category": "Contest/Events/Demo", "model": "SSV all track", "brand": "canam_side_by_side" }, "status": [{ "code": "new", "set_on": "2025-05-20T19:19:00Z" }], "model_number": "0008HSB00", "comments": "I want a tough SSV", "assignment_date": "2025-05-20T15:19:00Z", "start_date": "2025-05-20T19:19:00Z", "byo_uri": "https://can-am.brp.com/off-road/ca/fr/configuration-et-prix/app.html?platform=SSV_SSP_2_MAX&package=4X4_X&unitid=0008HSB00", "campaign_name": "", "event_description": "SD054_FB_CONTEST___ECOMM-WIN-A-PFD-US-EN", "intent_to_buy": "4-6 months", "lead_score": "Medium", "questions_answers": [{ "question": "What are you looking for in a SSV?", "answer": "Sun and fun" }, { "question": "Who will use the SSV?", "answer": "Me and my dog" }], "ownership": { "brand": "Polaris RZR Trail", "trade_in": 1000 }, "customer_no": "0000691232" };
// Convert to compact JSON as sent (matches JSON.stringify in Node.js and compact Python)
const rawBody = Buffer.from(JSON.stringify(payloadObj), 'utf8');
// Secret key
const appKeyHex = 'f7d9a47e143a4b298b819f48b3b77e4b24ae746f55c7c35b2c09c1ec3adbe7c2';
// Calculate expected signature
const expectedSig = crypto.createHmac('sha256', appKeyHex).update(rawBody).digest('hex');
// What would be in the X-Hub-Signature-256 header (from the siganture example)
const headerSignature = 'sha256=1f91bc0b914dd833968daff615988dae63ea177b9a52fb7f5268df20f9e6a824';
// --- Simulate receiver: extract signature from header and verify ---
const receivedHeader = headerSignature; // From header in real request
const providedSig = receivedHeader.split('=')[1];
const expectedBuf = Buffer.from(expectedSig, 'hex');
const providedBuf = Buffer.from(providedSig, 'hex');
const isValid = expectedBuf.length === providedBuf.length &&
crypto.timingSafeEqual(expectedBuf, providedBuf);
if (isValid) {
console.log('Signature is valid!');
} else {
console.log('Signature is INVALID!');
}❗ Si la firma calculada no coincide con la firma recibida, devuelve un estado 401 Unauthorized y registra el error para ayudar con el diagnóstico ❗
Referencia de API
curl --request POST 'https://cloud-api.brp.com/dcp/v4/dealer/0000690885/opportunity/update' \
--header 'Authorization: Bearer REPLACE_ME'
--data '
{
"sales_opportunity_id": "00Q4R00001dBg21",
"status": [
{
"code": "contacted",
"set_on": "2024-07-25T14:48:12Z"
}
]
}'Manejo de errores
Esta sección presenta diversos escenarios de llamadas incorrectas que resultan en mensajes de error y resultados inexactos.
400 Solicitud Incorrecta
El código de estado 400 suele encontrarse durante el desarrollo y la integración, y no debería aparecer durante las operaciones normales. La respuesta devuelta contiene la información necesaria para corregir el problema.
Muchos problemas pueden causar un código de estado 400, y los más comunes se enumeran en la tabla a continuación.
Respuesta | Solución |
|---|---|
Se devuelve si falta una propiedad. {
"status": 400,
"errors": [
{
"code": "schema_error",
"title": "El contenido proporcionado no cumple con el esquema JSON esperado",
"meta": [
{
"keyword": "enum",
"dataPath": ".status[0].code",
"schemaPath": "#/properties/status/items/properties/code/enum",
"params": {
"allowedValues": [
"contacted",
"unit_sold",
"abandoned"
]
},
"message": "debe ser igual a uno de los valores permitidos"
}
]
}
]
} | Agregue la propiedad faltante al contenido enviado. |
Se devuelve si una fecha tiene un formato no válido. {
"status": "400",
"id": "rrt-0eb1275f0947eeef3-d-ea-3040725-18600050-2",
"title": "solicitud_incorrecta",
"meta": {
"service": "01",
"detail": "falló la validación de la solicitud",
"payload": {
"details": [
{
"message": "[Path '.status[0].set_on'] La cadena \"25-11-2023T15:18:58Z\" no es válida según los formatos requeridos [yyyy-MM-dd'T'HH:mm:ssZ, yyyy-MM-dd'T'HH:mm:ss.[0-9]{1,12}Z]: []"
}
]
}
}
} | Cambie el formato de la cadena de fecha para que coincida con el formato requerido. |
401 No autorizado
El código de estado de error 401 Unauthorized se devuelve cuando intentas llamar a la API con un token_de_acceso.
Tienes que obtener un nuevo token_de_acceso con una llamada a la API de Autenticación de Aplicaciones.
El código de estado de error 401 Unauthorized también se devuelve si no solicitaste acceso a la API creando un ticket en el DCP Jira.
Cuando estés listo para comenzar a trabajar en una API, debes crear un ticket de certificación en Jira, como se describe en la sección Actividades de Certificación con Jira.
Si ya comenzaste a trabajar en una API y perdiste acceso, crea un ticket de soporte como se describe en la sección Abrir un Ticket de Soporte.
404 No Encontrado
Se devuelve cuando el ID de oportunidad de ventas recibido en la Disposición de Oportunidad de Ventas carga útil es desconocido.
Pruebas de Certificación
Fases
Las pruebas se realizan en tres fases.
- Fase 1: El objetivo de la primera fase es validar tu CRM realizando llamadas directas, es decir, sin pasar por la API de Oportunidades de Venta. En esta fase, la disposición no se verifica. Se realizan llamadas para verificar el manejo de errores de tu CRM.
- Fase 2: Durante esta fase, las oportunidades de venta se envían a tu CRM mediante la API de Oportunidades de Venta, y tu CRM envía disposiciones llamando a Enviar Estado de Oportunidad.
- Fase 3: La última fase consiste en enviar oportunidades de venta a tu CRM utilizando el flujo completo, desde un lead de ventas a Salesforce hasta tu CRM. Tu CRM envía disposiciones que se verifican en Salesforce.
👉 Los pasos específicos de las pruebas se encuentran en la sección ValidacionesValidaciones a continuación.
Arquitectura de Pruebas
Esta sección presenta la arquitectura de pruebas para cada fase.
👉 Para realizar pruebas, debes identificar, para cada fase, un distribuidor BRP válido en tu entorno de prueba que será utilizado para enviar la oportunidad de venta.
Fase 1
Durante la fase 1, se utilizan consultas de Postman para llamar a tu CRM y enviar oportunidades de venta, pero también para enviar cargas útiles inválidas con el fin de validar el manejo de errores de tu CRM.
Se utilizan consultas de Postman para validar el método de autenticación de tu CRM.
Si tu CRM utiliza la Autenticación de Aplicación (OAuth 2.0)aplicación, se realizarán llamadas para recuperar un token Bearer, y otras llamadas se harán para crear errores.
Si tu CRM utiliza el Firma de Webhookaaa método, las llamadas se realizarán con una firma no válida.
Las consultas se utilizan para enviar una oportunidad de ventas, y otras llamadas se utilizan para enviar cargas útiles no válidas.
Fase 2
En la fase 2, las oportunidades de ventas se envían mediante consultas de Postman a tu CRM a través de la API de Oportunidades de Ventas.
Tu CRM también puede enviar una actualización del estado de la oportunidad de ventas (disposición) a la API de Oportunidades de Ventas, que luego se reenvía a un servidor simulado en Postman.
Fase 3
En la fase 3, los prospectos de ventas se envían a Salesforce mediante consultas de Postman. Salesforce luego envía la oportunidad de ventas a tu CRM y recibe una actualización de estado.
Requisitos de DSP
Requisitos funcionales
ID | Tipo | Requisito |
|---|---|---|
1 | Obligatorio | Su CRM debe proporcionar uno de los métodos de autenticación descritos en laInformación Técnica de Métodos de Autenticación sección. |
2 | Obligatorio | Su CRM debe mostrar todas las propiedades de la oportunidad de venta en la interfaz de usuario. 👉 Si su CRM no tiene algunas de las propiedades, estas pueden agruparse y mostrarse en un campo de texto. |
3 | Obligatorio | Al enviar la actualización del estado de la oportunidad de venta, asocie el estado de su CRM con uno de los estados listados en laRecurso: Actualización de Oportunidad de Venta sección. |
Actividades de certificación
Esta sección describe todas las actividades de certificación y validaciones necesarias para certificar la API.
Pruebas de la Fase 1
Las pruebas enumeradas en la tabla a continuación deben completarse en el entorno de prueba antes de que pueda comenzar las pruebas de la fase 2.
Autenticación de Aplicaciones (OAuth 2.0)
ID | Prueba | Resultado Esperado |
|---|---|---|
1 | Solicitar un token Bearer. | El CRM devuelve un token Bearer válido. |
2 | Solicitar un token Bearer sin client_id. | El CRM devuelve un estado de respuesta 401. |
3 | Solicitar un token Bearer con un client_id no válido. | El CRM devuelve un estado de respuesta 401. |
4 | Enviar una oportunidad de venta con un token Bearer válido. | El CRM devuelve un estado 200. |
5 | Enviar una oportunidad de venta con un token Bearer no válido. | El CRM devuelve un estado de respuesta 401. |
6 | Enviar una oportunidad de venta con un número de distribuidor no válido. | El CRM devuelve un estado de respuesta 404. |
7 | Enviar una oportunidad de venta con un payload no válido. | El CRM devuelve un estado de respuesta 400. |
Firma de Webhook
ID | Prueba | Resultado esperado |
|---|---|---|
1 | Enviar una oportunidad de venta con una firma válida. | El CRM devuelve un estado 200. |
2 | Enviar una oportunidad de venta con una firma inválida. | El CRM devuelve un estado de respuesta 401. |
3 | Enviar una oportunidad de venta con un número de distribuidor inválido. | El CRM devuelve un estado de respuesta 404. |
4 | Enviar una oportunidad de venta con un payload inválido. | El CRM devuelve un estado de respuesta 400. |
Pruebas de la Fase 2
Las pruebas enumeradas en la tabla a continuación deben completarse en el entorno de prueba antes de que pueda comenzar las pruebas de la fase 3.
ID | Prueba | Resultado esperado |
|---|---|---|
1 | Se recibió una oportunidad de ventas. | Mostrar la oportunidad de ventas recibida en su CRM. Proporcione una captura de la interfaz de usuario que muestre toda la información disponible de la oportunidad de ventas. |
2 | Enviar actualización del estado de la oportunidad. | Actualizar el estado de la oportunidad de ventas en el CRM y verificar que el cambio se envíe a la API. |
Pruebas de la Fase 3
Las pruebas enumeradas en la tabla a continuación deben completarse en el entorno de pruebas antes de que pueda comenzar la fase piloto del concesionario.
ID | Prueba | Resultado esperado |
|---|---|---|
1 | Se recibió una oportunidad de venta. | Mostrar la oportunidad de venta recibida en su CRM. Proporcione una captura de la interfaz de usuario que muestre toda la información disponible de la oportunidad de venta. |
2 | Enviar actualización del estado de la oportunidad. | Actualizar el estado de la oportunidad de venta en el CRM y verificar que el cambio se envía a la API. |
Piloto de Concesionarios
La siguiente tabla describe los parámetros del piloto de concesionarios y sus validaciones correspondientes.
Parámetro | Valor |
|---|---|
Entorno | Producción |
Número de concesionarios | 1 a 3 |
Duración | 2 semanas |
Validación 1 | Verificar que las oportunidades de venta enviadas por BRP estén disponibles en el CRM. |
Validación 2 | Verificar que BRP haya recibido actualizaciones de estado sobre la oportunidad de venta. |
Postman
Esta sección describe lo que está disponible en Postman para explorar la API.
Entornos
Un entorno de Postman está disponible para probar la API de Oportunidades de Venta. Este entorno de Postman contiene variables utilizadas por las consultas y configuradas para conectarse al entorno de pruebas.
Colecciones
La colección CRM - Oportunidades de Venta contiene ejemplos de llamadas API para enviar una disposición de oportunidad de ventas.
También hay ejemplos de llamadas directas a tus endpoints CRM para ayudarte a probar la integración.
Hay un ejemplo para un CRM que utiliza la autenticación oAuth, y otro para el método de firma.
👉 Para usar las consultas, debes configurar las variables de la colección con la información del endpoint de tu CRM.