Tarjetas CRM

ResumenPuntos finalesWebhooks

Las tarjetas CRM personalizadas permiten que la información de otros sistemas aparezca en registros de contacto, empresa, negocio o ticket. Usando esta característica, las aplicaciones pueden crear tarjetas personalizadas para mostrar esta información. Si quieres que tus datos estén activos directamente dentro de HubSpot, pero ninguno de los objetos nativos se ajusta a tus necesidades, es recomendable que veas si los objetos personalizados cumplen con tus necesidades.

Casos de uso de ejemplo: Tu equipo de ingeniería utiliza un servicio de software para hacer seguimiento de errores, pero los representantes de atención al cliente usan HubSpot. Tus representantes quieren ver información sobre los errores de sus clientes sin salir de HubSpot. Tu aplicación puede definir una tarjeta personalizada que muestra esta información directamente en el registro de contacto de HubSpot.

Cómo funciona

Las tarjetas se pueden definir como parte de la configuración de la característica de tu aplicación. Una vez que la aplicación esté instalada y un usuario vea los registros de CRM objetivo, HubSpot hace una solicitud saliente a la aplicación, recupera los datos relevantes y los muestra en una tarjeta en la página del registro. Las aplicaciones también pueden especificar acciones personalizadas que el usuario puede tomar en función de esta información. Un ejemplo de una acción personalizada sería abrir un modal y mostrar la propia interfaz de la aplicación en HubSpot.

Este es un ejemplo de una tarjeta CRM:

CRM_Card_1

Este es un ejemplo de cómo fluyen los datos para mostrar las propiedades de tarjetas en el CRM:

CRM_card_diagram

 

Configurar tarjetas CRM

Las tarjetas CRM pueden crearse y configurarse en tu cuenta de desarrollador. Los detalles individuales de la tarjeta están representados por propiedades de tarjetas y los títulos de estas propiedades pueden (opcionalmente) enlazarse al sistema externo del integrador. Ten en cuenta que la línea «Con el respaldo de» en la tarjeta utilizará el nombre de la aplicación de tu configuración de la aplicación.

En el panel Aplicaciones, elige la aplicación donde deseas agregar una tarjeta y luego ve a Tarjetas CRM. Haz clic en el botón «Crear tarjeta CRM» para comenzar.

Screen Shot 2020-01-14 at 7.36.35 PM

Requisitos de alcance

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. Esto significa que solicitas el alcance de los contactos para configurar una tarjeta para contactos, empresas o negocios, y el alcance de los tickets para hacer lo mismo para los tickets.

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.

Eliminar alcances

Si tu aplicación ya está usando tarjetas CRM, no podrás eliminar los alcances de los contactos o los tickets hasta que elimines todas las tarjetas existentes para los tipos de objetos asociados.

 

Crear nuevas tarjetas

Crear plantillas de tarjetas es el primer paso para usar las tarjetas CRM. Esto es lo que verá un usuario:

CRM_card_2

 

Configurar tarjetas a través de la API

Más información sobre cómo administrar tarjetas a través de la API en la pestaña de los puntos finales

Configurar tarjetas de la interfaz de configuración de la aplicación

También puedes crear y administrar tarjetas CRM en tu cuenta de desarrollador en la configuración de la característica de la aplicación. (Ver instrucciones anteriores)

Example_CRM_card_3

*Puedes crear hasta 25 tarjetas CRM por aplicación.

Documentos relacionados

Comprender el CRM

Eventos de cronología

Solicitudes de recuperación de datos

Como se mencionó en la pestaña Resumen, HubSpot hace una solicitud de recuperación de datos a tu aplicación cuando un usuario ve el registro de CRM asociado. Estas solicitudes se envían a la búsqueda especificada/targetUrl de la tarjeta con una carga que proporciona detalles para el registro de CRM asociado.

Las respuestas pueden contener hasta cinco propiedades de tarjetas. Si hay más propiedades de tarjetas disponibles para un objeto de CRM específico, tu aplicación puede enlazar a ellos.

Ten en cuenta que la solicitud se agotará en 5 segundos. Dentro de ese tiempo, se debe hacer una conexión con 3 segundos. 

Solicitud de datos de ejemplo:

GET: https://example.com/demo-tickets?userId=12345&userEmail=testuser@example.com&associatedObjectId=78912&associatedObjectType=COMPANY&portalId=9999999&domain=testcompany.com

 
Con encabezado:
X-HubSpot-Signature: <some base64 string>

El encabezado X-HubSpot-Signature proporciona verificación de que se produjo una solicitud de HubSpot. Consulta las firmas de la solicitud para conocer detalles.

Parámetros de la consulta:
  • userId: El ID de usuario numérico del cliente que solicita los datos.
  • userEmail: La dirección de HubSpot del usuario que solicita datos.
  • portalId: El ID de cuenta de HubSpot del cliente que solicita los datos. La cuenta y el portal se usan indistintamente. 
  • associatedObjectId: El ID del objeto actual, según el associatedObjectType. Este será  companyId, dealId, contact vID, o objectId para tickets.
  • associatedObjectType: El tipo de objeto sobre el cual el usuario solicita datos (contacto, empresa, negocio, o ticket). Este será uno de los tipos de associatedHubSpotObjectTypes que se proporcionan para este tipo de registro.
  • Y valores para cualquiera de las opciones de asociación solicitadas de associatedHubSpotObjectTypeProperties. Si una de las propiedades de solicitud no está definida para el objeto actual, no se incluirá en la cadena de consulta. En el ejemplo anterior, se incluye el dominio de propiedad de la empresa. Las propiedades de solicitud se pueden definir en la interfaz de configuración de la aplicación, como se puede ver en la captura de pantalla a continuación: 

Associated_Objects

Respuesta de ejemplo:
// example response { "results": [ { "objectId": 245, "title": "API-22: APIs working too fast", "link": "http://example.com/1", "created": "2016-09-15", "priority": "HIGH", "project": "API", "reported_by": "msmith@hubspot.com", "description": "Customer reported that the APIs are just running too fast. This is causing a problem in that they're so happy.", "reporter_type": "Account Manager", "status": "In Progress", "ticket_type": "Bug", "updated": "2016-09-28", "actions": [ { "type": "IFRAME", "width": 890, "height": 748, "uri": "https://example.com/edit-iframe-contents", "label": "Edit", "associatedObjectProperties": [] }, { "type": "IFRAME", "width": 890, "height": 748, "uri": "https://example.com/reassign-iframe-contents", "label": "Reassign", "associatedObjectProperties": [] }, { "type": "ACTION_HOOK", "httpMethod": "PUT", "associatedObjectProperties": [], "uri": "https://example.com/tickets/245/resolve", "label": "Resolve" }, { "type": "CONFIRMATION_ACTION_HOOK", "confirmationMessage": "Are you sure you want to delete this ticket?", "confirmButtonText": "Yes", "cancelButtonText": "No", "httpMethod": "DELETE", "associatedObjectProperties": [ "protected_account" ], "uri": "https://example.com/tickets/245", "label": "Delete" } ] }, { "objectId": 988, "title": "API-54: Question about bulk APIs", "link": "http://example.com/2", "created": "2016-08-04", "priority": "HIGH", "project": "API", "reported_by": "ksmith@hubspot.com", "description": "Customer is not able to find documentation about our bulk Contacts APIs.", "reporter_type": "Support Rep", "status": "Resolved", "ticket_type": "Bug", "updated": "2016-09-23", "properties": [ { "label": "Resolved by", "dataType": "EMAIL", "value": "ijones@hubspot.com" }, { "label": "Resolution type", "dataType": "STRING", "value": "Referred to documentation" }, { "label": "Resolution impact", "dataType": "CURRENCY", "value": "94.34", "currencyCode": "GBP" } ], "actions": [ { "type": "IFRAME", "width": 890, "height": 748, "uri": "https://example.com/edit-iframe-contents", "label": "Edit" }, { "type": "CONFIRMATION_ACTION_HOOK", "confirmationMessage": "Are you sure you want to delete this ticket?", "confirmButtonText": "Yes", "cancelButtonText": "No", "httpMethod": "DELETE", "associatedObjectProperties": [ "protected_account" ], "uri": "https://example.com/tickets/245", "label": "Delete" } ] } ], "settingsAction": { "type": "IFRAME", "width": 890, "height": 748, "uri": "https://example.com/settings-iframe-contents", "label": "Settings" }, "primaryAction": { "type": "IFRAME", "width": 890, "height": 748, "uri": "https://example.com/create-iframe-contents", "label": "Create Ticket" } }
Definiciones:
  • results: Una lista de hasta cinco propiedades de tarjetas válidas. 
  • results[].objectId: Un ID único para este objeto. Esta propiedad es obligatoria.
  • results[].title: El título de este objeto. Esta propiedad es obligatoria.
  • results[].link: La URI que el usuario puede seguir para obtener más detalles sobre este objeto. Esta propiedad es opcional, pero si todos los objetos no tienen un enlace, deberías proporcionar un valor de nulo.
  • results[].properties: Una lista de propiedades personalizadas que no se definen en la configuración de la tarjeta. Puedes usar esta lista para mostrar las propiedades únicas de un objeto específico. Estas propiedades se mostrarán en el orden que se proporcionan, pero después de las propiedades definidas en la configuración de tarjetas. Esta propiedad es opcional.
  • results[].actions: Una lista de acciones disponibles que un usuario puede tomar en este objeto. Consulta tipos de acciones para conocer detalles sobre acciones específicas. Esta propiedad es opcional.
  • totalCount: El número total de propiedades de tarjetas disponibles, si hay más de cinco relacionadas con el objeto de CRM solicitado. Esta propiedad es opcional.
  • allItemsLink: Una URI que muestra todas las propiedades de tarjeta asociadas con el objeto de CRM solicitado, si hay más de cinco. Esta propiedad es opcional.
  • itemLabel: La etiqueta que se usa en el enlace «Ver más», por ejemplo. «Ver más tickets». Esta propiedad es opcional y si no se proporciona, por opción predeterminada es el título de la tarjeta.
  • settingsAction: Una acción iframe que les permite a los usuarios actualizar la configuración de la aplicación. Consulta tipos de acciones para conocer detalles sobre acciones específicas. Esta propiedad es opcional.
  • primaryAction: La acción principal para un tipo de registro, normalmente una acción «creación». Consulta tipos de acciones para conocer detalles sobre acciones específicas. Esta propiedad es opcional.
  • secondaryActions: Una lista de acciones que se muestran en el nivel de tarjeta. Consulta tipos de acciones para conocer detalles sobre acciones específicas. Esta propiedad es opcional.

Además de las propiedades anteriores, el integrador puede proporcionar valores para las propiedades definidas en la configuración de la tarjeta. En el ejemplo anterior, la propiedad JSON creada:

"created":"2016-08-04"

Proporciona un valor para este objeto para la propiedad creada previamente.

CRM_card_5

Manejar ganchos de acción 

Cuando un usuario hace clic en una acción definida como un gancho de acción, HubSpot envía una solicitud usando el método URI y HTTP especificado en la definición de acción.

Ejemplo de solicitud:

DELETE https://example.com/tickets/245?userId=12345&userEmail=testuser@example.com&associatedObjectId=78912&associatedObjectType=COMPANY&portalId=9999999&domain=testcompany.com

Con encabezado:
X-HubSpot-Signature: <some base64 string>
Parámetros de la consulta:
  • userId: El ID de usuario numérico del cliente que solicita los datos.
  • userEmail: La dirección de usuario de HubSpot del cliente que solicita los datos.
  • associatedObjectId: El ID del objeto actual, según el associatedObjectType. Este será companyId, dealId, contact vid o objectId para tickets.
  • associatedObjectType: El tipo de objeto sobre el que solicita datos el usuario (contacto, empresa, negocio o ticket).
  • portalId: El ID de cuenta (también denominado ID de Hub) del cliente que solicita datos.
  • Y valores para cualquiera de las associatedObjectProperties solicitadas. Si una de las propiedades solicitadas es no definida para el objeto actual, no se incluirá en la cadena de consulta. En el ejemplo anterior, se incluye el dominio de propiedad de la empresa.

El encabezado X-HubSpot-Signature permite al integrador verificar que una solicitud proviene de HubSpot. Consulta las firmas de la solicitud para conocer detalles.

Respuesta de ejemplo:
{"message": "Successfully deleted object"}

HubSpot intentará analizar las respuestas a los ganchos de acción como JSON y buscar una propiedad de mensaje. El usuario recibirá un mensaje sobre éxito o fracaso.

El código de estado de respuesta de 2XX mostrará un mensaje de éxito y 4XX o 5XX que mostrarán mensajes de error.

 

Tipos de acciones

Las siguientes secciones proporcionan detalles sobre cada tipo de acción que se puede especificar.

Acciones iframe

Cuando un usuario haga clic en una acción iframe, se abrirá un cuadro de diálogo modal con un iframe que señale la URL proporcionada.

Ejemplo de acción iframe:
// { "type": "IFRAME", "width": 890, "height": 748, "uri": "https://example.com/iframe- contents", "label": "Edit", "associatedObjectProperties": [ "some_crm_property" ] }
Definiciones:
  • tipo: Debe ser IFRAME para indicar que es una acción iframe.
  • ancho, altura: Las dimensiones de iframe deseadas.
  • uri: La URI abierta en el iframe.
  • etiqueta: La etiqueta que aparece en el menú desplegable de acciones.
  • associatedObjectProperties: Una lista de propiedades en el contacto, empresa, negocio o ticket asociado. Los valores de propiedad para el objeto actual se agregarán a la URL como parámetros de consulta al abrir el iframe.

Firmar para que el modal cierre

Cuando el usuario complete una acción iframe, el cuadro de diálogo modal debe cerrarse y volver a la pantalla de CRM original. Para cerrar el modelo de diálogo, la aplicación puede usar un window.postMessage. Los siguientes mensajes son aceptados:

  • {"action": "DONE"} - El usuario ha completado correctamente la acción.
  • {"action": "CANCEL"} - El usuario canceló la acción.
Ejemplo: window.parent.postMessage(JSON.stringify({"action": "DONE"}), "*");

Nota: Los módulos iframe a los que se accede a través de una acción iframe tendrán un ancho adaptable. 

 

Acciones de gancho de acción

Las acciones de gancho de acción envían una solicitud del lado del servidor a una aplicación. La única interfaz de usuario que ve para esta acción es un mensaje de éxito o un error. Este tipo de acción es útil para operaciones simples que no requieren más entradas de usuario.

Ejemplo de acción de gancho de acción:
// { "type": "ACTION_HOOK", "httpMethod": "POST", "uri": "https://example.com/action-hook", "label": "Example action", "associatedObjectProperties": [ "some_crm_property" ] }
Definiciones:
  • tipo: Debe ser ACTION_HOOK para indicar que esta acción es un gancho de acción.
  • httpMethod: El método HTTP a usar al realizar la solicitud. Esto puede ser GET, POST, PUT, DELETE o PATCH.
  • uri: La URI de la solicitud que se hará.
  • etiqueta: La etiqueta para mostrar en el menú desplegable de acciones.
  • associatedObjectProperties: Una lista de propiedades en el contacto, empresa, negocio o ticket asociado. Si httpMethod es GET o DELETE, estos valores de propiedad se agregarán a la URI de la solicitud como parámetros de consulta. De lo contrario, se enviarán como un cuerpo de solicitud de JSON.

Consulta Manejar ganchos de acción para conocer más detalles sobre cómo implementar el punto final de la acción.

Acciones de confirmación

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

 

// { "type": "CONFIRMATION_ACTION_HOOK", "httpMethod": "POST", "uri": "https://example.com/action-hook", "label": "Example action", "associatedObjectProperties": [ "some_crm_property" ], "confirmationMessage": "Are you sure you want to run example action?", "confirmButtonText": "Yes", "cancelButtonText": "No" }
Definiciones:
  • tipo: Debe ser ACTION_HOOK para indicar que esta acción es un gancho de acción.
  • httpMethod: El método HTTP a usar al realizar la solicitud. Esto puede ser GET, POST, PUT, DELETE o PATCH.
  • uri: La URI de la solicitud que se hará.
  • etiqueta: La etiqueta para mostrar en el menú desplegable de acciones.
  • associatedObjectProperties: Una lista de propiedades en el contacto, empresa, negocio o ticket asociado. Si httpMethod es GET o DELETE, estos valores de propiedad se agregarán a la URI de la solicitud como parámetros de consulta. De lo contrario, se enviarán como un cuerpo de solicitud de JSON.

Consulta Manejar ganchos de acción para conocer más detalles sobre cómo implementar el punto final de la acción.

Acciones de confirmación

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

Definiciones:
  • tipo: Debe ser CONFIRMATION_ACTION_HOOK que es una acción de gancho de acción de confirmación.
  • httpMethod: El método HTTP a usar al realizar la solicitud. Esto puede ser GET, POST, PUT, DELETE o PATCH.
  • uri: La URI de la solicitud que se hará.
  • etiqueta: La etiqueta para mostrar en el menú desplegable de acciones.
  • associatedObjectProperties: Una lista de propiedades en el contacto, empresa, negocio o ticket asociado. Si httpMethod es GET o DELETE, estos valores de propiedad se agregarán a la URI de la solicitud como parámetros de consulta. De lo contrario, se enviarán como un cuerpo de solicitud de JSON.
  • confirmationMessage: El mensaje para mostrar al usuario en el cuadro de diálogo de confirmación.
  • confirmButtonText: El texto del botón «Aceptar». Este es opcional, ya que el texto del botón será por opción predeterminada «Aceptar».
  • cancelButtonText: Texto para el botón «Cancelar». Esto es opcional, ya que el texto del botón será por opción predeterminada «Cancelar».

Consulta Manejar ganchos de acción para conocer más detalles sobre cómo implementar el punto final de la acción.

¿Te resultó útil este artículo?
Con este formulario puedes enviar tu opinión sobre nuestros documentos para desarrolladores. Si tienes comentarios sobre el producto de HubSpot, puedes enviarlos al Foro de ideas.