Diretrizes de uso de APIs
A HubSpot monitora o uso de nossas APIs públicas para garantir uma experiência de qualidade para todos os usuários. Todos os desenvolvedores de apps e integrações devem cumprir a Política de Utilização Responsável da HubSpot e os Termos de APIs. Embora a HubSpot se reserve o direito de alterar as APIs ou torná-las obsoletas ao longo do tempo, as atualizações sempre serão fornecidas por meio do log de alterações do desenvolvedor.
Autenticação e segurança
Para segurança ideal, todos os apps devem usar o protocolo OAuth da HubSpot diretamente ou o token de acesso do app se você estiver criando um app privado. Os aplicativos são responsáveis por armazenar dados de tempo de vida (TTL) e atualizar os tokens de acesso do usuário de acordo com esse protocolo. Quando um token de acesso for gerado, ele incluirá um parâmetro expires_in que indica por quanto tempo ele poderá ser usado para fazer chamadas de API antes de precisar ser atualizado. As solicitações Unauthorized (401) não são um indicador válido de que é preciso recuperar um novo token de acesso.
Apps e apps privados usando OAuth
Use o monitoramento de chamadas de API nas configurações do app privado ou app público.
Integrações com chaves de API
Observação: a partir de 30 de novembro de 2022, as chaves de API da HubSpot serão desativadas e não terão mais suporte. Continuar usando as chaves de API da HubSpot representará um risco de segurança para sua conta e dados. Durante esta fase, a HubSpot poderá desativar sua chave a qualquer momento.
Você deve autenticar usando um token de acesso de aplicativo privado ou OAuth. Saiba mais sobre essa alteração e como migrar uma integração de chave de API para usar um aplicativo privado.
Para verificar quantas chamadas de API foram feitas no dia atual e quando o limite será redefinido, faça uma solicitação GET para /integrations/v1/limit/daily?hapikey=key_value, onde key_value é a chave de API da conta da HubSpot. O dia atual é medido de meia-noite a meia-noite de acordo com as configurações do fuso horário da conta conectada. Chamadas para este endpoint são imputadas nos seus limites diários de APIs.
Os dados retornados por esse endpoint ficarão armazenados no cache por cinco minutos. Verifique os campos fetchStatus e collectedAt na resposta para determinar se ele é proveniente do cache.
Exemplo de resposta:
O campo resetsAt consiste em um registro de data/hora Unix (em milissegundos) do tempo em que o limite será redefinido. O limite é redefinido meia-noite com base na configuração do fuso horário da conta.
Exemplo de resposta do cache:
Quando a resposta for proveniente do cache, fetchStatus será "CACHED" e collectedAt será uma marca de data/hora do Unix (em milissegundos) que indica a última vez em que o cache foi atualizado.
Aplicativos com OAuth
Para aplicativos OAuth, cada conta da HubSpot que instala o aplicativo está limitada a 100 solicitações a cada 10 segundos. Isso exclui a API de pesquisa, conforme observado na seção Outros limites abaixo. Limites relacionados ao complemento para API não se aplicam.
Apps privados
Cada aplicativo privado está sujeito às diretrizes de uso de APIs da HubSpot. O número de chamadas que seu aplicativo privado pode fazer se baseia na assinatura da sua conta e se você comprou o complemento de API:
| Nível de produto | Por 10 segundos | Por dia | |
|---|---|---|---|
| Aplicativos privados |
(Qualquer Hub) Gratuito e Starter |
100/aplicativo privado | 250.000/conta |
|
(Qualquer Hub) Pro e Enterprise |
150/aplicativo privado | 500.000/conta | |
| Aplicativos privados com o complemento de API |
(Qualquer Hub) Gratuito, Starter, Professional e Enterprise |
200/aplicativo privado | 1.000.000/conta |
Qualquer aplicativo ou integração que exceda seus limites de taxa receberá uma resposta de erro 429 para todas as chamadas de API subsequentes. As solicitações que resultam em resposta de erro não devem exceder 5% das solicitações diárias. Se você planejar listar seu aplicativo no Marketplace de aplicativos, ele deverá estar abaixo desse limite de 5% para que seja certificado.
a resposta 429 terá o seguinte formato:
A message e o policyName indicarão o limite que você atingiu (diariamente ou por segundo).
O limite diário é redefinido meia-noite de acordo com sua configurações do fuso horário.
Cada solicitação de API incluirá os seguintes cabeçalhos de limite de taxa na resposta. OBSERVAÇÃO: os cabeçalhos Daily e Daily-Remaining não estão incluídos em solicitações autorizadas usando OAuth.
| Cabeçalho | Descrição |
|---|---|
X-HubSpot-RateLimit-Daily |
O número de solicitações de API permitidas por dia. |
X-HubSpot-RateLimit-Daily-Remaining |
O número de solicitações de API ainda permitidas no dia atual. |
X-HubSpot-RateLimit-Interval-Milliseconds |
A janela de tempo a que os cabeçalhos X-HubSpot-RateLimit-Max e X-HubSpot-RateLimit-Remaining se aplicam:Por exemplo, o valor 10.000 seria uma janela de 10 segundos. |
X-HubSpot-RateLimit-Max |
O número de solicitações permitidas na janela especificada em X-HubSpot-RateLimit-Interval-Milliseconds.Por exemplo, se o valor desse cabeçalho fosse 100 e o cabeçalho X-HubSpot-RateLimit-Interval-Milliseconds foi 10.000, o limite forçado seria 100 solicitações por 10 segundos. |
X-HubSpot-RateLimit-Remaining |
O número de solicitações de API ainda permitidas para a janela especificada em X-HubSpot-RateLimit-Interval-Milliseconds |
Observação: os cabeçalhos X-HubSpot-RateLimit-Secondly e X-HubSpot-RateLimit-Secondly-Remaining continuarão incluídos e terão dados exatos, mas o limite a que eles fazem referência não será mais aplicado e esses dois cabeçalhos deverão ser considerados obsoletos.
Você também pode verificar o número de chamadas usadas durante o dia atual usando este endpoint.
Se você se deparar com TEN_SECONDLY_ROLLING, acelere as solicitações que o aplicativo está fazendo para se manter abaixo desse limite. Confira as sugestões abaixo para acelerar as solicitações ou se você estiver atingindo o limite diário.
Se você perceber que, mesmo após ler estas sugestões, continua atingindo os limites de chamada, utilize nossos fóruns de desenvolvedor para nos avisar. Forneça o máximo de detalhes possível sobre as APIs que você está usando, como elas estão sendo usadas e qual limite está sendo atingido.
Armazenamento de dados no cache para chamadas repetidas
Se seu site ou aplicativo usar dados do HubSpot em cada carregamento de página, esses dados deverão ser armazenados no cache e carregados dele, em vez de serem solicitados todas as vezes nas APIs da HubSpot. Se você estiver fazendo chamadas repetidas para obter configurações sobre sua conta para um trabalho em lote (como obter as propriedades do objeto, os proprietários ou as configurações de um formulário), essas configurações também deverão armazenadas no cache sempre que possível.
Use APIs em lote sempre que possível
Se você não estiver trabalhando com dados sensíveis ao tempo, o agrupamento de atualizações em lotes periódicos, em vez de em lotes individuais, pode ser mais eficaz.
Se você estiver trabalhando com objetos de CRM (contatos, empresas, negócios, etc), há métodos de lote disponíveis.
Use webhooks para obter dados atualizados do HubSpot
Se tiver uma assinatura do HubSpot Operations Professional, você poderá usar ações de webhook em fluxos de trabalho para que os dados de registros de contatos sejam enviados para o seu sistema. Os Webhooks podem ser disparados como uma ação em qualquer fluxo de trabalho. Dessa forma, é possível usar condições iniciais de qualquer fluxo de trabalho como os critérios para que os dados de contato sejam enviados para o sistema. Encontre aqui mais detalhes sobre como usar webhooks e aqui um exemplo de dados de webhooks. As chamadas de webhook feitas por meio de fluxos de trabalho não contam para o limite de taxa da API.
Saiba mais sobre nossos limites e preços de serviço aqui.
- Você pode criar até 100 apps por conta de desenvolvedor.
- Você pode criar até 20 apps privados por conta da HubSpot.
- Você pode criar até 1.000 assinaturas de webhook por app.
- Você pode criar até 25 configurações de extensão de CRM por app.
- Você pode criar até 750 tipos de evento de linha do tempo por app.
- Você pode criar até 500 propriedades por tipo de evento de linha do tempo.
- Os endpoints da API de pesquisa são limitados a quatro solicitações por segundo por token de autenticação.