Tarjetas CRM

Para crear tarjetas CRM personalizadas, tu aplicación debe solicitar los alcances de OAuth necesarios para modificar los registros de CRM donde aparecerá tu tarjeta. Por ejemplo, para que una tarjeta CRM aparezca en los registros de contactos, la aplicación debe tener los alcances crm.objects.contacts.read y crm.objects.contacts.write. Si más tarde necesitas eliminar los alcances de objetos de CRM de tu aplicación, primero deberás eliminar todas las tarjetas existentes para esos tipos de objetos.

Consulta la documentación de OAuth para obtener más detalles sobre los alcances y la configuración de la URL de autorización para tu aplicación.

Puedes crear tarjetas CRM para tu aplicación a través de la API o editando tu aplicación en tu cuenta de desarrollador. Para obtener más información sobre la configuración de una tarjeta a través de la API, consulta la pestaña Puntos de terminación en la parte superior del artículo.

Para crear una tarjeta CRM utilizando la interfaz de usuario de HubSpot:

• En tu cuenta de desarrollador de HubSpot, navega a Aplicaciones en la barra de navegación principal.
• Selecciona la aplicación en la que quieres agregar una tarjeta.
• En el menú de la barra lateral izquierda, selecciona Tarjetas CRM.
• En la parte superior derecha, haz clic en Crear tarjeta CRM.
  

A continuación, obtén más información sobre las opciones de configuración en cada pestaña.

Cuando un usuario de HubSpot ve un registro de CRM en el que está activada la tarjeta de CRM, HubSpot realizará una solicitud de recuperación de datos a la integración. Esta solicitud se realiza a la URL de destino especificada, que incluye un conjunto de parámetros de consulta predeterminados, junto con parámetros adicionales que contienen datos de propiedades como se especifica en la configuración de la tarjeta. 

• En el campo URL de obtención de datos, introduce la URL de la que obtendrás los datos. En la API, esta URL se agrega al campo targetUrl. 

• En la sección Tipos de registros de destino, haz clic para activar los interruptores para seleccionar en qué registros de CRM aparecerá la tarjeta. A continuación, utiliza las propiedades enviadas desde los menús desplegables de HubSpot para seleccionar las propiedades de HubSpot que se incluirán como parámetros de consulta en la URL de la solicitud. En la API, cada tipo de registro y sus propiedades correspondientes se agregan como objetos en la matriz objectTypes.

La configuración anterior daría como resultado que HubSpot enviara tu solicitud GET de la siguiente manera.

A continuación se muestra un ejemplo de respuesta que el integrador podría proporcionar a la solicitud anterior.

Para garantizar que las solicitudes provienen realmente de HubSpot, se incluye el siguiente título de solicitud. Este título contendrá un hash del secreto de la aplicación para tu aplicación y los detalles de la solicitud. 

X-HubSpot-Signature: <some base64 string>

Para verificar esta firma, realiza los siguientes pasos:

1. Crea una cadena que concatene lo siguiente: <app secret> + <HTTP method> + <URL> + <request body> (if present).
2. Crea un hash SHA-256 de la cadena resultante.
3. Compara el valor del hash a la firma. Si son iguales, la solicitud ha pasado la validación. Si los valores no coinciden, la solicitud puede haber sido manipulada en tránsito o alguien puede estar falsificando solicitudes en tu punto de terminación.

En la pestaña Propiedades de la tarjeta, define las propiedades personalizadas que deseas que HubSpot muestre en la tarjeta CRM. Una vez definida, la integración puede rellenar estas propiedades incluyéndolas en su respuesta.

• • Haz clic en Agregar propiedad para agregar una nueva propiedad para que la tarjeta se muestre. La carga que proporciones en respuesta a la llamada de recuperación de datos debe contener valores para todas estas propiedades.
  • En el panel derecho, establece el nombre único, la etiqueta de presentación y el tipo de datos de la propiedad. Puedes seleccionar entre los siguientes tipos: Moneda, Fecha, Fecha y hora, Correo electrónico, Enlace, Numérico, Estado y Cadena. Más información sobre el uso de los tipos de propiedades de extensión.
  • Haz clic en Agregar para guardar la propiedad.
    

Cuando HubSpot envía su solicitud de datos, la integración puede proporcionar valores para estas propiedades en su respuesta junto con otros valores en cada objeto en los resultados. Además de las propiedades configuradas en esta pestaña, la integración también puede incluir sus propias propiedades personalizadas sin necesidad de definirlas en la configuración de la tarjeta.

Por ejemplo, en la respuesta a continuación, creado y prioridad se definen en la pestaña Propiedades de la tarjeta, mientras que la matriz de propiedades envía sus propias definiciones y valores de propiedad. Estas propiedades específicas del objeto deben definirse por objeto.

Al enviar propiedades personalizadas, el campo dataType para cada propiedad se puede establecer en uno de: CURRENCY, DATE, DATETIME, EMAIL, LINK, NUMERIC, STATUS, STRING. Dependiendo del tipo de propiedad, es posible que la integración deba proporcionar campos adicionales. A continuación, más información sobre cada tipo de propiedad.

Las propiedades de la CURRENCY deben incluir un currencyCode, que debe ser un código ISO 4217 válido. Esto asegurará que el usuario vea el símbolo de moneda y el formato de número correctos.

Las propiedades de DATE deben estar en el formato aaaa-mm-dd. Estas propiedades se mostrarán en un formato adecuado a la configuración regional del usuario. Si necesitas incluir una marca de tiempo, deberías usar una propiedad DATETIME.

Se accede a las URL de las acciones en el campo uri de una acción. De manera similar a la solicitud de búsqueda de datos, los ganchos de acción incluirán un conjunto predeterminado de parámetros de consulta. Puedes incluir otros parámetros de consulta incluyendo un campo associatedObjectProperties en la acción.

La respuesta variará según el tipo de acción. A continuación, obtén más información sobre los tipos de acción.

Las acciones de CONFIRMATION_ACTION_HOOK se comportan igual que las acciones ACTION_HOOK, excepto que se muestra un cuadro de diálogo de confirmación al usuario antes de ejecutar la solicitud del servidor.

El httpMethod se puede configurar para  GET, POST, PUT, DELETE o PATCH.  Si se utiliza GET o DELETE, los valores associatedObjectProperties se adjuntarán a la URL de la solicitud como parámetros de consulta. De lo contrario, las propiedades se enviarán en el cuerpo de la solicitud.