Como conectar o HubSpot ao Excel - Consultar dados de CRM com SQL

Conecte o HubSpot ao Excel

Obtenha dados de HubSpot em Excel

Importe linhas em tempo real da sua conta HubSpot para o Excel e atualize-as quando quiser. Sem driver ODBC, sem exportações, sem macros. Leva cerca de dez minutos na primeira vez, e o plano gratuito cobre isso.

Cerca de 10 minutos Não é necessário programar As credenciais permanecem com você. Excel em qualquer lugar, até mesmo na web.

O resultado final será o que você obterá.

Uma planilha que exibe os resultados em tempo real de uma consulta SQL em sua conta do HubSpot, com um botão que busca as linhas mais recentes sempre que os dados forem alterados. Assim:

Vendas.xlsx — Excel

InícioInserirDadosFluxos de consulta

	A	B	C	D	E
1	ID do cliente	primeiro nome	sobrenome	país	total
2	1042	Maria	Álvarez	EUA	1,284.50
3	1043	Daniel	Okafor	EUA	612.00
4	1047	Priya	Nair	EUA	2,090.75
5	1051	Thomas	Berg	EUA	338.20
6	1056	Lúcia	Ferreira	EUA	1,455.00
7	1060	Kenji	Sato	EUA	874.10
8

Folha1 Direto da HubSpot

O HubSpot armazena seus dados por trás de sua API. Para importá-los para o Excel, geralmente é necessário exportar um arquivo CSV do painel do HubSpot sempre que precisar de novos números. O Query Streams elimina essa necessidade: um pequeno programa auxiliar, chamado Agente, executa a consulta no local onde seus dados estão armazenados, e um suplemento do Excel solicita as linhas desejadas. Somente os resultados são transmitidos por meio de uma conexão criptografada, e o Excel pode ser acessado de qualquer lugar: seu laptop em casa, o computador de um colega em outra cidade ou o Excel na web.

O que você vai precisar

Uma conta do Query Streams

O plano gratuito é suficiente para este guia. Cadastre-se em my.querystreams.com.

O Agente em qualquer computador sempre ligado

Um pequeno programa que roda em segundo plano e acessa o HubSpot quando o Excel solicita. Ele só precisa de acesso à internet.

Seu login do HubSpot

Você fará login no HubSpot uma única vez e concederá acesso de leitura. Nenhuma senha é digitada nos Fluxos de Consulta.

Conecte-o em cinco etapas

1. Crie sua conta

   Vá para my.querystreams.com e inscreva-se. Escolha o Gratuito É um plano real, não uma versão de teste, e inclui a conexão da sua conta HubSpot e a execução de consultas a partir do Excel.

2. Instale o Agente em qualquer computador que esteja sempre ligado.

   Faça login e abra DownloadInstale o Agente em qualquer computador ou servidor que esteja sempre ligado e com acesso à internet. Leva apenas um minuto e, a partir daí, ele inicia automaticamente.

   Por que um programa pequeno em vez de um driver? O Agente é um único instalador para Windows, Mac ou Linux (cerca de 85 MB no Windows, um pouco mais de 100 MB no Mac e Linux) que funciona silenciosamente em segundo plano. Ele estabelece uma única conexão de saída criptografada com o Query Streams, da mesma forma que um navegador, portanto, você não precisa abrir nenhuma porta de firewall nem configurar uma VPN. Suas chaves permanecem nessa máquina e as linhas são enviadas para onde você estiver, pela internet, se necessário. A única coisa do seu lado é o complemento.

   A página de download mostra Sua chave de acessoCole o código no Agente quando solicitado e aguarde até que o crachá exiba a mensagem. Conectado a fluxos de consultaEssa é a única coisa que você faz no próprio Agente.

   Guias completos, se você quiser: Janelas, Mac, Linux.

3. Aponte para sua conta do HubSpot.

   De volta ao seu navegador, abra Agentes de dados (sob Dados (no menu superior). Seu agente está listado lá. Clique Adicionar conector e escolha HubSpot. Need your HubSpot credentials first? Open the walkthrough, then fill in:

   Create your HubSpot credentials (about 5 minutes)

   Follow this with HubSpot open in another tab. Query Streams keeps what you create here so your Agent can use it, and only ever reads from HubSpot.

   Who can do this

   Super admin, or a user with the Developer tools access permission (service keys). Legacy private apps need a Super admin.

   Recomendado

   Service key with read-only scopes (Development → Keys → Service Keys). HubSpot recommends service keys for scheduled data syncs to BI tools and warehouses, and is removing the option to create new legacy private apps.

   Antes de começar

   • A HubSpot login that is a Super admin or has the Developer tools access permission. A service key can only be given scopes your own HubSpot user already has.
   • Know which HubSpot account you want to query. A key only reads the account it was created in, so create it in that account, not in a test or sandbox account.
   • Decide which HubSpot tables you want. Contacts, Companies, Deals, Owners, Pipelines, Pipeline Stages and Properties are on by default; every extra table needs its own read scope (see Permissions).
   • The Query Streams Agent installed and online on an always-on computer, and the Query Streams portal open in another tab: Data Agents → Add connector → HubSpot.

   Steps

   1. Sign in to HubSpot

      Open HubSpot in a new tab and sign in as a Super admin, or as a user with the Developer tools access permission.

      If you belong to more than one HubSpot account, switch to the one whose data you want before you continue. The key only works for the account it is created in.

   2. Open Development

      In the left main navigation, near the bottom, click Development (the </> icon). The Development page opens with its own sidebar: Overview, Projects, Legacy Apps, Monitoring, Keys and more.

      No Development item? Your HubSpot user is not a Super admin and lacks Developer tools access. Ask a Super admin to create the key, or to give you that permission.

   3. Open Service Keys

      In the Development sidebar, click Keys to expand it, then click Service Keys (it has a Beta badge). The Service Keys page opens; if you have none yet it says No Service Keys Created.

      Do not use Personal Access Key or Developer API Key, which sit just above Service Keys in the same menu. They are developer-tool keys and will not connect. Some accounts also reach this page from Settings (gear icon) → Integrations → Service Keys.

   4. Click Create service key

      In the top right of the Service Keys page, click Create service key. The Create Service Key page opens with a Name box and a Scopes section.

   5. Name the key

      In Name, type a name you will recognise later, for example Query Streams read-only. HubSpot shows this name in its logs.

      The name must be unique in your HubSpot account.

   6. Open the scope picker

      Next to Selected scopes, click + Add new scope. A panel opens on the right with a Find a scope search box and a checkbox for each scope.

   7. Tick the four required scopes

      Type each name into Find a scope and tick its checkbox: crm.objects.contacts.read, crm.objects.companies.read, crm.objects.deals.read, crm.objects.owners.read. These four cover every table Query Streams syncs by default.

      Tick only scopes that end in .read. Query Streams only reads from HubSpot; it never needs a .write scope.

   8. Tick scopes for any extra tables

      For each extra table you want, tick its scope from the Permissions list below. For example: crm.objects.tickets.read for Tickets; crm.objects.line_items.read for Line Items, Taxes, Discounts and Fees; crm.lists.read for Lists. Skip this step if the default tables are enough.

      You can add scopes later without making a new key (open the key, then Edit).

   9. Click Update

      Click Update in the right panel. The panel closes and your scopes are listed under Selected scopes.

   10. Check the scope list

       Read through Selected scopes. If anything ends in .write, click Delete next to it. Expand Summary of selected scopes if you want a plain-language list of what the key can see.

   11. Create the key

       Click Create in the top right, then confirm in the dialog box that opens.

   12. Open your new key

       Go to Development → Keys → Service Keys and click the name of the key you just created. Its details page opens with a Service Key box.

   13. Show and copy the key

       In the Service Key box the value is partly hidden and starts with pat- (for example pat-na1-…). Click Show under it, then click Copy.

       Use Copy rather than selecting the text by hand: a missing character, a trailing space or the hidden dots will fail the test. HubSpot does not show the key only once; you can come back and click Show again. Treat it like a password.

   14. Paste it into Query Streams and test

       In the Query Streams portal open Data Agents, click Add connector and choose HubSpot. Paste the key into App Access Token, type a Connection name, then click Test connection. The result reads Connected.

       Query Streams stores the key for your Agent and only ever reads your HubSpot data.

   15. Match the tables to your scopes

       On the Sync step that follows, leave on only the HubSpot tables whose scopes you ticked in steps 7 and 8, then finish the wizard.

       A table switched on without its scope fails to sync with a Forbidden error. Add the scope to the key (step 8) or switch the table off.

   Alternatives

   Use a legacy private app token

   Your account already has a legacy private app you want to reuse. HubSpot is removing the option to create new ones: accounts created on or after 28 September 2026 already cannot, and older accounts lose it on 26 October 2026. Existing private apps and their tokens keep working.

   Who can do this: Super admin

   1. Open Legacy Apps

      In HubSpot click Development in the left main navigation, then Legacy Apps in the Development sidebar.

      Older HubSpot navigation called this Settings → Integrations → Private Apps.

   2. Open your private app, or start a new one

      If the app is listed, click its name and go to step 6 (or step 5 to add scopes). If not, and the button is still there, click Create legacy app in the top right and choose Private in the dialog box.

      No Create legacy app button means creation is already switched off for your account. Use a service key (main steps) instead.

   3. Name the new app

      On the Basic Info tab, enter a name such as Query Streams read-only. The logo and description are optional.

   4. Add the read scopes

      Click the Scopes tab, click Add new scope, tick the same scopes as in main steps 7 and 8, then click Update. Then click Create app in the top right, read the access-token message in the dialog box and click Continue creating.

   5. Add scopes to an existing app (only if needed)

      On the app’s page click Edit app in the top right, open the Scopes tab, add the missing read scopes and save. The token string does not change when you change scopes.

   6. Show and copy the token

      On the app’s page click the Auth tab. Under Access token click Show token, then click Copy. The token starts with pat-. Paste it into App Access Token as in main step 14.

      If the HubSpot user who created the app is removed from HubSpot, some calls fail with USER_DOES_NOT_HAVE_PERMISSIONS. Rotate the token (Rotate next to it) and paste the new one, or move to a service key.

   Use a developer-platform app’s static auth token

   Your team has already built a HubSpot app on the new developer platform with the HubSpot CLI, configured with static auth and private distribution. Building one needs the CLI; if you don’t have one, use a service key.

   Who can do this: Super admin, or a user with a developer seat, to view the token; Super admin or the HubSpot Marketplace access permission to install the app

   1. Open the project

      In HubSpot click Development, then Projects in the sidebar, then the name of the project that holds your app.

   2. Open the app

      On the project’s Overview tab, under Project Components, click the app’s name.

   3. Open the Distribution tab

      Click the Distribution tab.

   4. Install the app if it isn’t yet

      Under Manage distribution your current HubSpot account is listed. Click Install now, check that the access requested matches the read scopes you configured, then click Connect app.

      A static-token app can be installed in only one standard HubSpot account at a time.

   5. Show and copy the token

      Once installed, the Distribution tab shows an access token. Click Show to reveal it, copy it, and paste it into App Access Token as in main step 14.

      If you change the app’s scopes later, reinstall it with the Reinstall URL on the Distribution tab, or the new scopes won’t apply.

   Permissions to grant

   Resource	Acesso	Used for
   crm.objetos.contatos.ler	Ler	Required. hubspot.contacts, plus the activity tables hubspot.calls, hubspot.emails, hubspot.meetings, hubspot.notes, hubspot.tasks and hubspot.communications (HubSpot’s activity APIs use this scope), and contact fields in hubspot.properties and hubspot.associations.
   crm.objetos.empresas.ler	Ler	Required. hubspot.companies, and company fields in hubspot.properties and hubspot.associations.
   crm.objetos.negociações.ler	Ler	Required. hubspot.deals, the deal pipelines in hubspot.pipelines and hubspot.pipeline_stages, and deal fields in hubspot.properties and hubspot.associations.
   crm.objetos.proprietários.ler	Ler	Required. hubspot.owners, the HubSpot users who own records, so deals and contacts can be joined to a rep’s name.
   crm.objects.tickets.read	Ler	Only if you sync Tickets: hubspot.tickets and the ticket pipelines in hubspot.pipelines and hubspot.pipeline_stages. Older apps may show the legacy tickets scope instead, which also allows changes.
   crm.objects.products.read	Ler	Only if you sync Products: hubspot.products. Search the picker for products; HubSpot’s products API accepts this scope, although HubSpot’s scope reference page does not list it yet.
   crm.objects.line_items.read	Ler	Only if you sync Line Items, Taxes, Discounts or Fees: hubspot.line_items, hubspot.taxes, hubspot.discounts, hubspot.fees.
   crm.objects.quotes.read	Ler	Only if you sync Quotes: hubspot.quotes.
   crm.objects.invoices.read	Ler	Only if you sync Invoices: hubspot.invoices.
   crm.objects.subscriptions.read	Ler	Only if you sync Subscriptions: hubspot.subscriptions (HubSpot commerce subscriptions).
   crm.objects.commercepayments.read	Ler	Only if you sync Payments: hubspot.payments (HubSpot commerce payments).
   crm.objects.marketing_events.read	Ler	Only if you sync Marketing Events: hubspot.marketing_events.
   forms	Read and write (HubSpot has no read-only forms scope)	Only if you sync Forms or Form Submissions: hubspot.forms and hubspot.form_submissions. Query Streams only reads them.
   crm.objects.feedback_submissions.read	Ler	Only if you sync Feedback: hubspot.feedback_submissions. Service Hub Professional or Enterprise only. HubSpot’s scope reference spells it crm.objects.feedback_submission.read, so search the picker for feedback.
   crm.lists.read	Ler	Only if you sync Lists: hubspot.lists.
   automação	Read and write (HubSpot has no read-only workflows scope)	Only if you sync Workflows: hubspot.workflows. Professional or Enterprise accounts only. Query Streams only reads workflow definitions.
   crm.schemas.custom.read	Ler	Only if you sync Custom Schemas: hubspot.schemas (custom object definitions). Enterprise accounts only.

   Paste into Query Streams

   Token de acesso ao aplicativo

   The service key you copied in step 13 (it starts with pat-), or a legacy private app token, or a developer-platform app’s static auth token

   Common problems

   Test connection fails with Invalid or expired access token, straight after you pasted a new key.

   Why: The value is not an app or service key. The usual mix-up is the Personal Access Key or Developer API Key, which sit next to Service Keys under Development → Keys and are for HubSpot’s developer tools.

   Fix: Go to Development → Keys → Service Keys, open your key, click Show, then Copy, and paste that into App Access Token. Test connection again; it reads Connected.

   The wizard says Not a valid HubSpot app token before it even tests.

   Why: Only part of the key was pasted: the text doesn’t start with pat- and is very short or contains a space.

   Fix: Back in HubSpot click Show, then use the Copy link (don’t select the text by hand) and paste again.

   You can’t see Development in HubSpot’s left navigation, or Service Keys is missing under Keys.

   Why: Your HubSpot user is not a Super admin and doesn’t have the Developer tools access permission.

   Fix: Ask a Super admin in your company to create the key (steps 2 to 13) and paste it into the wizard, or to grant you Developer tools access.

   Test connection reads Connected, but one table fails to sync with a Forbidden error or stays empty.

   Why: The key is missing the read scope for that table, or your HubSpot plan doesn’t include that feature (Workflows needs Professional or Enterprise; Custom Schemas needs Enterprise; Feedback needs Service Hub Professional or Enterprise).

   Fix: Open the key (Development → Keys → Service Keys → key name), click Edit, add the scope from the Permissions list and save, then sync again. If your plan doesn’t include the feature, switch that table off in the connection’s Sync settings.

   Syncs that used to work start failing with Invalid or expired access token.

   Why: Someone rotated or deleted the key. Rotate and expire now stops the old key at once; Rotate and expire later stops it after 7 days.

   Fix: Copy the current key from Development → Keys → Service Keys → key name → Show → Copy. In Data Agents, edit the HubSpot connection, paste it into App Access Token and run Test connection.

   With a legacy private app token, some tables fail with USER_DOES_NOT_HAVE_PERMISSIONS.

   Why: The HubSpot user who created the private app was removed from the account.

   Fix: Rotate the app’s token (Development → Legacy Apps → app → Rotate) and paste the new token into the connection, or create a service key instead.

   You can’t find Create legacy app, or HubSpot’s docs call private apps legacy.

   Why: HubSpot is retiring creation of new legacy private apps (already off for accounts created on or after 28 September 2026; off for older accounts from 26 October 2026). Existing private apps keep working.

   Fix: Create a service key (main steps). Existing private app tokens can stay in place.

   Data in Query Streams doesn’t match what you see in HubSpot.

   Why: The key was created in a different HubSpot account (for example a test or sandbox account).

   Fix: Switch to the right HubSpot account, create a key there, and paste it into the connection.

   Limits to know

   • HubSpot’s limits for service keys and private apps: 100 requests per 10 seconds per key on Free and Starter, 190 on Professional and Enterprise, 250 with the API Limit Increase add-on. The Agent paces itself to the lowest of these, so the first full sync of a large CRM can take a while.
   • Daily limit per HubSpot account: 250,000 requests on Free and Starter, 625,000 on Professional, 1,000,000 on Enterprise. It is shared by every private app and service key in the account, so other integrations use the same budget.
   • HubSpot’s CRM search, which the Agent uses to fetch only changed records, allows 5 requests per second per account and at most 10,000 results per query.
   • Some tables depend on your HubSpot plan: Workflows (Professional or Enterprise), Custom Schemas (Enterprise), Feedback (Service Hub Professional or Enterprise).
   • Service keys are in public beta (since 10 February 2026), so HubSpot may change details. HubSpot recommends rotating keys every six months.
   • New legacy private apps can’t be created in accounts made on or after 28 September 2026, nor in older accounts from 26 October 2026. Existing apps and tokens keep working.

   Steps verified 8 October 2026. Sources: developers.hubspot.com/docs/apps/developer-platform/build…, developers.hubspot.com/changelog/service-keys, developers.hubspot.com/blog/hubspot-service-keys-the-righ…, developers.hubspot.com/changelog/legacy-private-app-creat…, developers.hubspot.com/docs/apps/legacy-apps/private-apps…, developers.hubspot.com/docs/apps/developer-platform/build…, developers.hubspot.com/docs/apps/developer-platform/build…, developers.hubspot.com/docs/apps/developer-platform/build…, developers.hubspot.com/docs/getting-started/developer-ove…, developers.hubspot.com/docs/apps/developer-platform/build…, developers.hubspot.com/docs/developer-tooling/platform/us…, developers.hubspot.com/docs/api-reference/latest/crm/sear…, knowledge.hubspot.com/user-management/hubspot-user-permis…, developers.hubspot.com/docs/api-reference/legacy/crm/obje…, developers.hubspot.com/docs/api-reference/legacy/crm/acti…, developers.hubspot.com/docs/api-reference/legacy/crm/acti…, developers.hubspot.com/docs/api-reference/legacy/crm/obje…, developers.hubspot.com/docs/api-reference/legacy/crm/obje…, developers.hubspot.com/docs/api-reference/legacy/crm/pipe…, developers.hubspot.com/docs/api-reference/legacy/crm/obje…, developers.hubspot.com/docs/api-reference/legacy/automati…, developers.hubspot.com/docs/api-reference/legacy/marketin…, developers.hubspot.com/docs/api-reference/legacy/account/…, docs.n8n.io/integrations/builtin/credentials/hubspot.

   Nome da conexão

   Qualquer nome que você reconheça mais tarde, como Banco de Dados de Vendas.

   Token de acesso ao aplicativo

   Um token de aplicativo privado do HubSpot (começa com pat-), encontrado em Configurações, Integrações, Aplicativos Privados, seu aplicativo, guia Autenticação.

   Clique em Teste de conexãoQuando lê Conectado, clique SalvarA conexão chega ao seu agente em poucos segundos.

   Agentes de Dados Abertos

   O teste falhou? Usually a missing permission, or a credential from the wrong HubSpot account. The walkthrough above lists the common problems and their fixes.

4. Adicionar fluxos de consulta ao Excel

   No Excel, acesse Inserir → Obter suplementos, procurar Fluxos de consultae clique AdicionarOu abra-o diretamente de Consultar fluxos no Microsoft AppSourceUm botão "Consultar fluxos" aparece na faixa de opções. Faça login com a mesma conta.

   Funciona no Excel para Microsoft 365 no Windows e no Mac, e no Excel na Web.

5. Puxe sua primeira mesa.

   Clique no botão Consultar fluxos e escolha Transmita uma consultaE selecione a conexão que você acabou de fazer.

   Digite a consulta que deseja executar. Esta consulta extrai algumas colunas de uma tabela. hubspot.promoções mesa:

   Exemplo · SQL

   SELECT dealname, dealstage, amount, closedate FROM hubspot.deals ORDER BY closedate DESC LIMIT 100;

   Sob Folha de Destino escolher Criar uma nova planilhaEm seguida, pressione o botão de reprodução (a seta ▶). As linhas serão exibidas no Excel em um ou dois segundos. Pressione-o novamente sempre que os dados forem alterados e a planilha será atualizada automaticamente.

   Não conhece SQL? Em vez disso, crie a consulta no portal Query Streams. Construtor de consultas Exibe suas tabelas e colunas para que você possa apontar e clicar. Nos planos Business, você também pode usar o Nova em linguagem natural ("mostre-me os clientes nos EUA") e ele gera o SQL para você. Salve a consulta e ela estará a um clique de distância no portal e na lista de Consultas Salvas do suplemento, a partir do plano Personal Core.

Boas próximas jogadas

• Salvar consulta no portal, para que você possa executá-lo novamente com um clique, a partir do Excel ou do Google Sheets.
• Adicionar um filtro como um intervalo de datas, para que a mesma consulta possa responder "este mês" sem precisar editar.
• Compartilhe os resultados Com um colega. Eles veem as fileiras, não suas credenciais.

Perguntas que as pessoas fazem

Guias relacionados

• HubSpot para Google Sheets
• Stripe para Microsoft Excel
• Do Shopify ao Microsoft Excel
• Google Analytics 4 para Microsoft Excel
• Executando SQL no Excel
• Todos os guias