API del CRM | Tarjetas del CRM

Última modificación: 28 de agosto de 2025

Run in Postman

En una aplicación pública, puedes crear tarjetas del CRM personalizadas para mostrar información de otros sistemas en los registros de contactos, empresas, negocios y tickets de HubSpot. Cada aplicación puede incluir hasta 25 tarjetas del CRM.

A partir del 16 de junio de 2025, las funcionalidades de las tarjetas clásicas del CRM, descritas en este artículo, dejarán de recibir soporte y quedarán oficialmente obsoletas el 31 de octubre de 2026. Más información sobre este cambio en el registro de cambios para desarrolladores.Las tarjetas clásicas del CRM son diferentes de las tarjetas de aplicación que puedes crear como extensiones de la interfaz de usuario con proyectos. Las nuevas tarjetas de aplicación ofrecen más flexibilidad, personalización e interactividad utilizando un conjunto de herramientas más moderno basado en React. Si tu aplicación incluye actualmente una tarjeta del CRM clásica, aprende cómo migrarla al marco de proyectos para utilizar las tarjetas de aplicación más recientes.

Ejemplo de uso: estás creando una integración para el mercado de aplicaciones de tu software de seguimiento de errores. Quieres poder mostrar los errores detectados en los registros de contacto para que los representantes del servicio de asistencia puedan consultarlos cuando trabajen con los clientes. Tu aplicación puede definir una tarjeta personalizada que muestre esta información directamente en el registro de contacto de HubSpot.

Las tarjetas se pueden definir como parte de la configuración de características de tu aplicación. Una vez que la aplicación esté instalada y un usuario vea los registros del CRM, HubSpot hace una solicitud a la aplicación, extrae los datos pertinentes y los muestra en una tarjeta en la página del registro. Las aplicaciones también pueden especificar las medidas específicas que el usuario puede tomar en función de esta información. Por ejemplo, tu aplicación podría incluir la instrucción de abrir un modal para mostrar la interfaz del usuario de la aplicación en HubSpot.

diagrama de flujo de datos de la tarjeta crm

Permisos necesarios

Para crear tarjetas del CRM personalizadas, tu aplicación debe solicitar los permisos de OAuth necesarios a fin de modificar los registros del CRM donde aparecerá tu tarjeta. Por ejemplo, para que una tarjeta del CRM aparezca en los registros de contactos, la aplicación debe tener los permisos crm.objects.contacts.read y crm.objects.contacts.write. Si más tarde necesitas retirar los permisos de los objetos del CRM de tu aplicación, primero deberás eliminar todas las tarjetas existentes de esos tipos de objetos. Consulta la documentación de OAuth para obtener más detalles sobre los permisos y la configuración de la URL de autorización para tu aplicación.

Crear una tarjeta del CRM

Puedes crear tarjetas del CRM para tu aplicación usando la API o modificando la aplicación en tu cuenta de desarrollador. Para obtener más información sobre la configuración de una tarjeta mediante la API, consulta esta documentación de referencia. Para crear una tarjeta del CRM utilizando la interfaz del usuario de HubSpot:

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

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

Las extensiones de la interfaz del usuario creadas mediante proyectos de desarrolladores ofrecen formas más flexibles de mostrar los datos y facilitar la interacción del usuario, lo que incluye la visualización de contenido externo en marcos. Si es posible usar una aplicación privada con tu integración, consulta la guía rápida sobre extensiones de la interfaz del usuario, o consulta los proyectos de ejemplo de HubSpot para saber qué puedes hacer.

Solicitud de datos

Cuando un usuario de HubSpot ve un registro del CRM en el que está activada una tarjeta del CRM, HubSpot hará una solicitud a la integración para obtener los datos. Esta solicitud se envía a la URL de destino especificada, que incluye un conjunto de parámetros de consulta predeterminados, junto con parámetros adicionales que contienen los datos de las propiedades según lo especificado en la configuración de la tarjeta.

private-app-create-crm-card-data-request-tab

En el campo URL de obtención de los datos, introduce la URL de donde extraerá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 y seleccionar en qué registros del CRM aparecerá la tarjeta. A continuación, utiliza los menús desplegables Propiedades enviadas desde 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 serie objectTypes.

{
  "title": "New CRM Card",
  "fetch": {
    "targetUrl": "https://www.example.com/demo-fetch",
    "objectTypes": [
      {
        "name": "contacts",
        "propertiesToSend": [
          "firstname",
          "email",
          "lastname"
        ]
      }
    ]
  }
...
}

Solicitud de ejemplo

La configuración anterior daría como resultado que HubSpot envíe una solicitud GET de la siguiente manera:

https://www.example.com/demo-fetch?userId=12345&userEmail=loggedinuser@hubspot.com&associatedObjectId=53701&associatedObjectType=CONTACT&portalId=987654&firstname=Tim&email=timrobinson@itysl.com&lastname=Robinson

Parámetro	Tipo	Descripción
`userId`	Predeterminado	El ID del usuario de HubSpot que subió el registro del CRM.
`userEmail`	Predeterminado	La dirección de correo electrónico del usuario que subió el registro del CRM.
`associatedObjectId`	Predeterminado	El ID del registro del CRM que se subió.
`associatedObjectType`	Predeterminado	El tipo de registro del CRM que se subió (por ejemplo, contacto, empresa, negocio).
`portalId`	Predeterminado	El ID de la cuenta de HubSpot donde se subió el registro del CRM.
`firstname`	Personalizado	El nombre del contacto, como se especifica en el menú desplegable Propiedades enviadas desde HubSpot (en la aplicación) y la serie del parámetro `propertiesToSend` (API).
`email`	Personalizado	La dirección de correo del contacto, como se especifica en el menú desplegable Propiedades enviadas desde HubSpot (en la aplicación) y en la serie del parámetro `propertiesToSend` (API).
`lastname`	Personalizado	El apellido del contacto, como se especifica en el menú desplegable Propiedades enviadas desde HubSpot (en la aplicación) y en la serie del parámetro `propertiesToSend` (API).

Nota:

Una conexión debe realizarse antes de tres segundos y las solicitudes expirarán a los cinco segundos.

Ejemplo de respuesta

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

{
  "results": [
    {
      "objectId": 245,
      "title": "API-22: APIs working too fast",
      "link": "http://example.com/1",
      "created": "2016-09-15",
      "priority": "HIGH",
      "project": "API",
      "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"
  }
}

Propiedad	Tipo	Descripción
`results`	Matriz	Una serie de hasta cinco propiedades de la tarjeta válidas. Si hay más propiedades disponibles para un objeto del CRM específico, tu aplicación puede establecer un enlace a ellos.
`objectId`	Número	Un ID único para el objeto.
`title`	Cadena	El título de el objeto.
`link`	Cadena	La URL que el usuario puede seguir para obtener más detalles sobre el objeto. Esta propiedad es opcional, pero si ningún objeto tiene un enlace, deberías proporcionar un valor `null`.
`created`	Cadena	Una propiedad personalizada, según como se define en la configuración de la tarjeta, que indica la fecha de creación del objeto.
`priority`	Cadena	Una propiedad personalizada, según como se define en la configuración de la tarjeta, que indica el nivel de prioridad del ticket externo.
`actions`	Matriz	Una lista de las acciones que un usuario puede realizar.
`properties`	Propiedades	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 en que se proporcionan, pero después de las propiedades definidas en la configuración de la tarjeta.
`settingsAction`	Objeto	Una acción del elemento iframe que permite a los usuarios cambiar la configuración de la aplicación.
`primaryAction`	Objeto	La acción principal de un tipo de registro, normalmente es una acción de creación.
`secondaryActions`	Matriz	Una lista de acciones que se muestran en la tarjeta.

Solicitar firmas

Para garantizar que las solicitudes provienen realmente de HubSpot, se incluye el encabezado indicado abajo. Este encabezado contendrá un hash del secreto para tu aplicación y los detalles de la solicitud. X-HubSpot-Signature: <some base64 string> Para verificar esta firma, lleva a cabo los siguientes pasos:

Crea una cadena que concatene lo siguiente: <app secret> + <HTTP method> + <URL> + <request body> (if present).
Crea un hash SHA-256 de la cadena resultante.
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 endpoint.

Más información sobre cómo validar solicitudes de HubSpot.

Propiedades de la tarjeta

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

Haz clic en Agregar propiedad a fin de agregar una nueva propiedad para que la tarjeta la muestre. La carga útil que proporciones en respuesta a la llamada de obtención de datos debe contener los valores de 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: Divisa, 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.

private-app-create-crm-card-card-properties-tab

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 del parámetro results. 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 que se muestra abajo, los parámetros created y priority se definen en la pestaña Propiedades de la tarjeta, mientras que la serie del parámetro properties envía sus propias definiciones y valores de propiedad. Estas propiedades específicas del objeto deben definirse por cada objeto.

{
  "objectId": 988,
  "title": "API-54: Question about bulk APIs",
  "link": "http://example.com/2",
  "created": "2016-08-04",
  "priority": "HIGH",
  "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": [
   ...
  ]
}

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

Propiedades de divisa

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

{
  "results": [
    {
      "properties": [
        {
          "label": "Resolution impact",
          "dataType": "CURRENCY",
          "value": "94.34",
          "currencyCode": "GBP"
        }
      ]
    }
  ]
}

Propiedades de fecha

Las propiedades DATE deben tener el formato yyyy-mm-dd. Estas propiedades se mostrarán en un formato que coincida con la configuración regional del usuario. Si necesitas incluir una marca de tiempo, debes utilizar una propiedad DATETIME.

{
  "results": [
    {
      "properties": [
        {
          "label": "Date",
          "dataType": "DATE",
          "value": "2023-10-13"
        }
      ]
    }
  ]
}

Propiedades de fecha y hora

Las propiedades con el atributo DATETIME indican una hora específica y deben proporcionarse en milisegundos desde el tiempo en Epoch. Estas propiedades se mostrarán en un formato que coincida con la configuración regional del usuario.

{
  "results": [
    {
      "properties": [
        {
          "label": "Timestamp",
          "dataType": "DATETIME",
          "value": "1697233678777"
        }
      ]
    }
  ]
}

Propiedades de correo electrónico

Las propiedades con el atributo EMAIL corresponden a valores que contienen una dirección de correo electrónico. Estas propiedades se mostrarán como enlaces mailto.

{
  "results": [
    {
      "properties": [
        {
          "label": "Email address",
          "dataType": "EMAIL",
          "value": "hobbes.baron@gmail.com"
        }
      ]
    }
  ]
}

Propiedades de enlace

Las propiedades con el atributo LINK muestran hipervínculos y se abren en una nueva ventana. Puedes especificar un valor linkLabel; si no está, se mostrará la URL misma.

{
  "results": [
    {
      "properties": [
        {
          "label": "Link property",
          "dataType": "LINK",
          "value": "https://www.hubspot.com",
          "linkLabel": "Test link"
        }
      ]
    }
  ]
}

Propiedades numéricas

Las propiedades con el atributo NUMERIC muestran números.

{
  "results": [
    {
      "properties": [
        {
          "label": "Number",
          "dataType": "NUMERIC",
          "value": "123.45"
        }
      ]
    }
  ]
}

Propiedades de estado

Las propiedades con el atributo STATUS se muestran como indicadores de color. Para definir una propiedad de estado, la integración necesita un valor optionType que indique los posibles estados. Los estados incluyen:

DEFAULT: Gris
SUCCESS: Verde
WARNING: Amarillo
DANGER: Rojo
INFO: Azul

{
  "results": [
    {
      "properties": [
        {
          "label": "Status",
          "dataType": "STATUS",
          "value": "Errors occurring",
          "optionType": "DANGER"
        }
      ]
    }
  ]
}

Propiedades de cadena

Las propiedades con el atributo STRING muestran texto.

{
  "results": [
    {
      "properties": [
        {
          "label": "First name",
          "dataType": "STRING",
          "value": "Tim Robinson"
        }
      ]
    }
  ]
}

Acciones personalizadas

En la pestaña Acciones personalizadas, puedes definir las URL de base que se solicitarán cuando un usuario haga clic en un botón de acción. Puedes incluir varias URL de acción para varias acciones en tu tarjeta del CRM. Las acciones de las tarjetas deben llamar al endpoint que se especifique en esta pestaña.

Los ganchos de acción y las solicitudes de confirmación de los ganchos incluirán un encabezado X-HubSpot-Signature para verificar la solicitud. Las solicitudes de acción con el elemento iframe no incluirán una firma para la solicitud. Consulta la sección Solicitar firmas para obtener más información. Las URL de acciones se acceden mediante el campo uri en 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 será diferente según el tipo de acción. A continuación, encontrarás más información sobre los tipos de acción.

Tipos de acción

Acciones con el elemento iframe

Las acciones con el elemento IFRAME abrirán un modal con un elemento iframe que apunta a la URL proporcionada. No se envía ninguna firma de solicitud cuando el iframe se abre desde la interfaz del CRM. Esto se debe a que la URL del iframe se incluye en la solicitud de obtención de datos original y no se necesitan solicitudes de proxy adicionales.

{
  "type": "IFRAME",
  "width": 890,
  "height": 748,
  "uri": "https://example.com/iframe-contents",
  "label": "Edit",
  "associatedObjectProperties": ["some_crm_property"]
}

Cuando el usuario haya terminado de completar una acción en el iframe, el modal debe cerrarse y devolver al usuario al registro del CRM donde comenzó. Para cerrar la ventana modal, la integración puede usar el parámetro window.postMessage para indicar al CRM que el usuario ha terminado. Se admiten los siguientes mensajes:

{"action": "DONE"}: el usuario ha completado correctamente la acción.
{"action": "CANCEL"}: el usuario ha cancelado la acción.

window.parent.postMessage(JSON.stringify({"action": "DONE"}), "*");

Acciones de gancho de acción

Las acciones de tipo ACTION_HOOK envían una solicitud del lado del servidor al elemento de la integración. La única interfaz que el usuario ve para esta acción es un mensaje que indica el éxito o el fallo de la operación. Este tipo de acción es útil para operaciones simples que no requieren más información por parte del usuario. Se incluirá un encabezado X-HubSpot-Signature en la solicitud de verificación. Encuentra más información sobre solicitar firmas.

{
  "type": "ACTION_HOOK",
  "httpMethod": "POST",
  "uri": "https://example.com/action-hook",
  "label": "Example action",
  "associatedObjectProperties": ["some_crm_property"]
}

El parámetro httpMethod se puede establecer con GET, POST, PUT, DELETE o PATCH. Si utilizas GET o DELETE, los valores associatedObjectProperties se agregarán a la URL de la solicitud como parámetros de consulta. Si usas las otras funciones, las propiedades se enviarán en el cuerpo de la solicitud.

window.parent.postMessage(JSON.stringify({"action": "DONE"}), "*");

Acciones de confirmación

Las acciones de tipo 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 lado del servidor. Se incluirá un encabezado X-HubSpot-Signature en la solicitud de verificación. Encuentra más información sobre solicitar firmas.

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

Eliminar una tarjeta del CRM

Una vez creada, puedes eliminar una tarjeta del CRM desde la configuración de la aplicación:

En tu cuenta de desarrollador de HubSpot, navega a Aplicaciones en la barra de navegación principal.
Haz clic en el nombre de la aplicación de la que quieres borrar una tarjeta.
En el menú de la barra lateral izquierda, selecciona Tarjetas del CRM.
Pasa el cursor sobre la tarjeta y haz clic en Eliminar.

delete-a-classic-crm-card-from-within-app-settings

En el cuadro de diálogo, confirma la eliminación haciendo clic en Eliminar esta tarjeta.

Analíticas y eventos

CRM

Run in Postman

​Permisos necesarios

​Crear una tarjeta del CRM

​Solicitud de datos

​Solicitud de ejemplo

​Nota:

​Ejemplo de respuesta

​Solicitar firmas

​Propiedades de la tarjeta

​Propiedades de divisa

​Propiedades de fecha

​Propiedades de fecha y hora

​Propiedades de correo electrónico

​Propiedades de enlace

​Propiedades numéricas

​Propiedades de estado

​Propiedades de cadena

​Acciones personalizadas

​Tipos de acción

​Acciones con el elemento iframe

​Acciones de gancho de acción

​Acciones de confirmación

​Eliminar una tarjeta del CRM

Permisos necesarios

Crear una tarjeta del CRM

Solicitud de datos

Solicitud de ejemplo

Nota:

Ejemplo de respuesta

Solicitar firmas

Propiedades de la tarjeta

Propiedades de divisa

Propiedades de fecha

Propiedades de fecha y hora

Propiedades de correo electrónico

Propiedades de enlace

Propiedades numéricas

Propiedades de estado

Propiedades de cadena

Acciones personalizadas

Tipos de acción

Acciones con el elemento iframe

Acciones de gancho de acción

Acciones de confirmación

Eliminar una tarjeta del CRM