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, sempre informaremos essas mudanças aos desenvolvedores por meio do nosso log de alterações

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 não autorizadas (401) não são um indicador válido de que é preciso recuperar um novo token de acesso

Verificando o uso da API

Apps e apps privados usando OAuth

Use o monitoramento de chamadas de API nas configurações do aplicativo.

Integrações com chaves de API

Observação: a partir de 30 de novembro de 2022, as chaves de API da HubSpot não poderão mais ser usadas como um método de autenticação para acessar as APIs da HubSpot. Além disso, a partir de 15 de julho de 2022, as contas sem uma chave de API da HubSpot gerada não poderão mais criar uma.

Em vez disso, você precisará usar um token de acesso a um app privado ou OAuth para autenticar chamadas de API. Saiba mais sobre essa alteração e como migrar uma integração de chave de API para usar um app privado.

Use GET /integrations/v1/limit/daily* para verificar quantas chamadas de API foram feitas no dia atual e quando o limite será redefinido. O dia atual é medido de meia-noite até meia-noite de acordo com as configurações do fuso horário da conta conectada. 

* Uma chamada para este endpoint é incluída na contagem de seus limites diários de APIs.

 

Parâmetros obrigatórios Descrição Como usar
Chave de API do HubSpot A chave de API da conta da HubSpot cujo uso da API você está verificando. hapikey= usado no URL

Examplo do URL GET:

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

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:

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

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:

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

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.

Limites de taxa

Aplicativos com OAuth

Os aplicativos que usam OAuth estão sujeitos a um limite de 100 solicitações a cada 10 segundos (exceto para a API de pesquisa, conforme indicado abaixo em “Outros limites”). 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

Integrações com chaves de API

As integrações que usam chaves de API estão sujeitas aos limites diários abaixo (exceto para a API de pesquisa, conforme indicado abaixo em “Outros limites”). Esses limites diários são redefinidos meia-noite de acordo com as configurações do fuso horário da conta conectada. 

 

Nível de produto

Limites

Gratuito e Starter

Estouro: 100/10 segundos

Diariamente: 250.000

Professional e Enterprise

Estouro: 150/10 segundos

Diariamente: 500.000 

Complemento de API (qualquer nível)

Estouro: 200/10 segundos 

Diariamente: 1.000.000

 

Respostas de erro

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: 

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

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 do HubSpot continuarão sendo incluídos e tendo 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. Mais detalhes sobre como usar webhooks podem ser encontrados aqui . Dados de webhooks de exemplo podem ser encontrados aqui.

 

Limites de serviço

Saiba mais sobre nossos limites e preços de serviço aqui.


Outros limites

  • 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.

Documentos relacionados

Verificando o uso de APIs no aplicativo