Pautas de uso de la API

HubSpot monitoriza atentamente el uso de nuestras API públicas para garantizar una experiencia de calidad para cada usuario. Todos los desarrolladores de aplicaciones e integraciones deben cumplir con la Política de uso aceptable de HubSpot y los Términos de la API. Si bien HubSpot se reserva el derecho de cambiar o eliminar las API a lo largo del tiempo, siempre haremos que los desarrolladores sepan por adelantado a través de nuestro registro de cambios.

Autenticación y seguridad

Para tener una seguridad óptima, todas las aplicaciones deben usar el Protocolo OAuth de HubSpot directamente, o usar el token de acceso de tu aplicación si estás creando una aplicación privada. Las aplicaciones son responsables de almacenar datos en vivo (TTL) y actualizar los tokens de acceso de usuario de conformidad con este protocolo. Cuando se genere un token de acceso, incluirá un parámetro expires_in que indica cuánto tiempo puede usar para hacer llamadas a la API antes de actualizar. Las solicitudes No autorizadas (401) no son un indicador válido que debe recuperar un nuevo token de acceso

Comprobación del uso de la API

Aplicaciones privadas y aplicaciones que usan OAuth

Usa el monitoreo de llamadas de API en la configuración de la aplicación.

Integraciones que usan claves API

Nota: a partir del 30 de noviembre de 2022, las claves de API de HubSpot ya no podrán usarse como un método de autenticación para acceder a las API de HubSpot. Además, a partir del 15 de julio de 2022, las cuentas sin una clave de API de HubSpot ya hayan sido generadas no podrán crear otra.

En cambio, deberás usar un token de acceso a aplicaciones privadas o utilizar OAuth para autenticar llamadas de API. Más información sobre este cambio y cómo migrar una integración de claves de API para usar una aplicación privada en su lugar.

Usa GET /integrations/v1/limit/daily* para verificar cuántas llamadas de API se han realizado para el día actual y cuándo se restablecerá el límite. El día actual se mide desde la medianoche hasta la medianoche, según la configuración de zona horaria de la cuenta conectada

*Una llamada a este punto de terminación cuenta para los límites de API diarios.

 

Parámetros obligatorios Descripción Como usar
Clave de API de HubSpot La clave de API para la cuenta de HubSpot para la que estás verificando el uso de la API. hapikey= usado en la URL

Ejemplo GET URL:

https://api.hubapi.com/integrations/v1/limit/daily?hapikey=demo

Los datos devueltos por este punto de terminación se almacenarán en caché durante cinco minutos. Verifica los campos fetchStatus y collectedAt en la respuesta para determinar si es desde el caché.

Ejemplo de respuesta:

// [ { "name": "api-calls-daily", "usageLimit": 1000000, "currentUsage": 31779, "collectedAt": 1560189939285, "fetchStatus": "SUCCESS", "resetsAt": 1560204000000 } ]

El campo resetsAt es una marca de tiempo Unix (en milisegundos) del momento en que se restablecerá el límite. El límite se restablece a la medianoche según la configuración de zona horaria de la cuenta.

Respuesta de la memoria caché de ejemplo:

// [ { "name": "api-calls-daily", "usageLimit": 1000000, "currentUsage": 31779, "collectedAt": 1560189939285, "fetchStatus": "CACHED", "resetsAt": 1560204000000 } ]

Cuando la respuesta proviene de la memoria caché, fetchStatus será "CACHED" y collectedAt será una marca de tiempo de Unix en milisegundos que indica cuándo se actualizó por última vez la memoria caché.

Límite de tasa

Aplicaciones que usan OAuth

Las aplicaciones que usan OAuth solo están sujetas a un límite de 100 solicitudes cada 10 segundos (excepto la API de búsqueda, tal como se indica a continuación en «Otros límites»). Los límites relacionados con el complemento de la API no se aplican.

Aplicaciones privadas

Cada aplicación privada se somete a las directrices de directrices de uso de API de HubSpot. El número de llamadas que tu aplicación privada puede hacer se basa en la suscripción de tu cuenta y si compras el complemento para API:

  Nivel de productos Por 10 segundos Por día
Aplicaciones privadas

(Cualquier Hub)

Free y Starter

100/cuenta 250.000/cuenta
 

(Cualquier Hub)

Pro y Enterprise

150/aplicación privada 500.000/cuenta
Aplicaciones privadas con complemento API

(Cualquier Hub)

Gratuito, Starter, Pro y Enterprise.

200/aplicación privada 1.000.000/cuenta

Integraciones que usan claves API

Las integraciones que usan claves de API están sujetas a los límites diarios a continuación (excepto para la API de búsqueda, como se indica a continuación en «Otros límites»). Estos límites diarios se restablecen a la medianoche según la configuración de zona horaria de la cuenta conectada. 

 

Nivel de productos

Límites

Free y Starter

Ráfaga: 100/10 segundos

Diario: 250.000

Pro y Enterprise

Ráfaga: 150/10 segundos

Diario: 500.000 

Complemento de API (cualquier nivel)

Ráfaga: 200/10 segundos 

Diario: 1000000

 

Respuestas de Error

Cualquier aplicación o integración que supere los límites de su tasa recibirá una respuesta de error 429 para todas las llamadas de API subsiguientes. Las solicitudes que resultan en una respuesta de error no deberían exceder el 5% del total de solicitudes diarias. Si planeas anunciar tu aplicación para la venta en nuestro Mercado de aplicaciones, debes estar bajo este límite del 5% para ser certificado. 

La respuesta 429 tendrá el siguiente formato: 

//Example { "status": "error", "message": "You have reached your daily limit.", "errorType": "RATE_LIMIT", "correlationId": "c033cdaa-2c40-4a64-ae48-b4cec88dad24", "policyName": "DAILY", "requestId": "3d3e35b7-0dae-4b9f-a6e3-9c230cbcf8dd" }

Los parámetros  message y policyName indican qué límite alcanzaste (ya sea diariamente o en segundo lugar).

El límite diario se restablece a la medianoche según tu configuración de zona horaria.

Cada solicitud de API incluirá los siguientes encabezados de límite de tasa en la respuesta. NOTA: Los encabezados Daily y Daily-Remaining no están incluidos para las solicitudes autorizadas que usan OAuth.

Encabezado Descripción
X-HubSpot-RateLimit-Daily La cantidad de solicitudes de API permitidas por día.
X-HubSpot-RateLimit-Daily-Remaining La cantidad de solicitudes de API que aún se permiten para el día actual.
X-HubSpot-RateLimit-Interval-Milliseconds La ventana de tiempo al que se aplican los encabezados X-HubSpot-RateLimit-Max y X-HubSpot-RateLimit-Remaining .

Por ejemplo, un valor de 10.000 sería una ventana de 10 segundos.
X-HubSpot-RateLimit-Max La cantidad de solicitudes permitidas en la ventana especificada en X-HubSpot-RateLimit-Interval-Milliseconds.

Por ejemplo, si este encabezado tuviera un valor de 100 y el encabezado X-HubSpot-RateLimit-Interval-Milliseconds fuera 10000, el límite aplicado sería de 100 solicitudes por 10 segundos.
X-HubSpot-RateLimit-Remaining  La cantidad de solicitudes de API que aún se permiten para la ventana especificada en X-HubSpot-RateLimit-Interval-Milliseconds


Nota
: Los encabezados X-HubSpot-RateLimit-Secondly y X-HubSpot-RateLimit-Secondly-Remaining todavía están incluidos y aún tendrán datos precisos, pero el límite al que hacen referencia estos encabezados ya no se aplica y estos dos encabezados deben considerarse obsoletos.

También puedes comprobar la cantidad de llamadas utilizadas durante el día actual usando este punto de terminación.

Si estás llegando al límite de TEN_SECONDLY_ROLLING, debes limitar las solicitudes que realiza tu aplicación para mantenerte por debajo de ese límite. Además de eliminar las solicitudes, o si estás en el límite diario, echa un vistazo a las sugerencias a continuación.

Si encuentras que aún estás alcanzando los límites de llamadas después de analizar estas sugerencias, infórmanos en nuestros foros de desarrollador. Queremos conocer tantos detalles como sea posible sobre las API que estás usando, cómo las estás usando y qué límite estás alcanzando.

Datos de caché para llamadas recurrentes

Si tu sitio o aplicación usa datos de HubSpot en cada una de las páginas de carga, esa información debe estar almacenada y cargarse desde esa memoria caché en lugar de ser solicitada desde las API de HubSpot cada vez. Si haces llamadas reiteradas para obtener la configuración de tu cuenta para un trabajo por lotes (como obtener las propiedades, los propietarios o la configuración de tu objeto para un formulario), esas configuraciones también deberían ser almacenadas en caché cuando sea posible.

Usa API por lotes siempre que sea posible

Si no estás trabajando con datos de tiempo limitado, las actualizaciones de grupo en lotes periódicos en lugar de individuales pueden ser más eficaces. 

Si trabajas con objetos de CRM (contactos, empresas, negocios, etc.), existen métodos por lotes disponibles. 

Usa webhooks para obtener datos actualizados de HubSpot

Si tienes una suscripción de HubSpot Marketing Enterprise, puedes usar acciones de webhook en workflows para que los datos de los registros de contactos se envíen a tu sistema. Los Webhooks pueden activarse como una acción en cualquier workflow, por lo que puedes usar condiciones de inicio de workflow como criterios para que los datos de contacto se envíen a tu sistema. Puedes encontrar más detalles sobre cómo usar webhooks aquí y ejemplos de datos de webhooks están aquí.

 

Límites de servicio

Más información sobre nuestros límites de servicio y precios aquí.


Otros límites

  • Puedes crear hasta 100 aplicaciones por cuenta de desarrollador
  • Puedes crear hasta 20 aplicaciones privadas por cuenta de HubSpot.
  • Puedes crear hasta 1.000 suscripciones de webhook por aplicación.
  • Puedes crear hasta 25 configuraciones de extensión de CRM por aplicación.
  • Puedes crear hasta 750 tipos de eventos de línea de tiempo por aplicación.
  • Puedes crear hasta 500 propiedades por tipo de evento de línea de tiempo.
  • Los puntos de terminación de la API de búsqueda tienen una tasa limitada de cuatro solicitudes por segundo por token de autenticación

Documentos relacionados

Comprobación del uso de API en la aplicación