Como conectar uma API REST ao HubCount BI Studio

Crie um cubo que busca dados de uma API REST. Serve para qualquer sistema com API que responda em JSON, como ERPs, CRMs e plataformas de anúncio.

Quando usar

• O sistema tem uma API e você quer que o HubCount BI Studio vá buscar os dados no horário que você escolher.
• A API devolve JSON. Uma lista de registros (pedidos, oportunidades, lançamentos) vira as linhas do cubo.

Se é o sistema que deve mandar os dados para o HubCount BI Studio quando algo acontece, use um webhook.

Antes de começar, tenha a documentação da API em mãos: a URL base, o tipo de autenticação e o endpoint que devolve os dados.

Como a configuração se divide

Onde	O que guarda	Vale para
Conexão	URL base, autenticação, cabeçalhos, parâmetros e corpo comuns, limite de chamadas	Todos os cubos que usam essa API
Cubo	Método, caminho do endpoint, paginação, caminho dos dados e cabeçalhos ou parâmetros próprios	Só esse cubo

Assim, um CRM com vários endpoints (oportunidades, contatos, atividades) usa uma conexão e um cubo por endpoint.

Criar a conexão

A URL base tem um caminho?

Se a URL base tem algo depois do domínio, como /v2, o HubCount BI Studio pergunta o que fazer ao salvar:

Botão	O que acontece
Salvar apenas base	Guarda só https://api.crm-aurora.com.br. Você informa /v2/... no endpoint de cada cubo. Recomendado.
Manter completa	Guarda a URL com /v2. Os endpoints dos cubos começam depois dela.
Cancelar	Volta para a janela sem salvar.

Abas da conexão

Aba	O que faz
Autenticação	Tipo de autenticação e credenciais.
Cabeçalhos da Requisição	Cabeçalhos enviados em toda chamada, como Accept: application/json.
Parâmetros	Parâmetros de URL enviados em toda chamada, como empresa=12.
Corpo	Corpo comum das chamadas POST, em JSON ou outro formato escolhido no editor.
Limites	Requisições por Minuto: o máximo de chamadas por minuto. Em branco, não há limite.

O limite da conexão vale para todos os cubos. No cubo, o mesmo campo aparece com o valor da conexão e o ícone de globo (Aplicado pela fonte de dados). Preencha lá só se aquele endpoint tem um limite diferente.

Tipos de autenticação

Tipo	Quando usar	Campos
Nenhuma	API pública, sem login	Nenhum. O botão Testar Autenticação some.
Autenticação Básica	A API pede usuário e senha	Usuário e Senha. Vão no cabeçalho Authorization: Basic.
Token Bearer	A API fornece um token fixo	Token. Vai no cabeçalho Authorization: Bearer.
Chave de API	A API fornece uma chave	Chave de API, Posicionamento e Nome do Parâmetro (tabela abaixo).
OAuth 2.0	A API usa OAuth 2.0	Quatro seções: credenciais, endpoints e escopos, redirecionamento e segurança, avançado.
Pré-Requisição	É preciso chamar um endpoint de login que devolve um token	Três seções: requisição, teste e posicionamento do token.

Chave de API

Campo	O que faz
Chave de API	A chave fornecida pela API. Fica mascarada. O olho mostra o valor.
Posicionamento	Onde a chave vai: Header (padrão), Parâmetro de Consulta, Cookie ou Corpo da Requisição.
Nome do Parâmetro	Nome do cabeçalho ou parâmetro, como X-API-Key ou api_key. Fica desabilitado quando a chave vai no corpo.
Formato do Corpo	Só com a chave no corpo: JSON ou x-www-form-urlencoded.
Nome do Campo no Corpo	Só com a chave no corpo: o nome do campo, como apiKey ou token.

OAuth 2.0

Seção	Campos
1. Credenciais	ID do Cliente e Segredo do Cliente, fornecidos pelo provedor.
2. Endpoints e escopos	URL do Endpoint de Autorização, URL do Endpoint de Token e Escopos. Digite cada escopo e aperte Enter.
3. Redirecionamento e segurança	Estratégia de URI de Redirecionamento (Servidor HTTP Local, Protocolo Personalizado ou URL Gerenciada HubCount), URI de Redirecionamento, Método de Autenticação do Cliente no Endpoint de Token (credenciais no corpo ou no cabeçalho Basic) e Habilitar PKCE.
4. Avançado	Parâmetros e cabeçalhos extras enviados ao endpoint de token. Opcional.

Token pedido antes de cada busca

Escolha Pré-Requisição quando o token expira e precisa ser pedido de novo antes de cada busca.

1. Configurar Requisição: a URL de login, o método (POST por padrão), os cabeçalhos e o corpo, como {"usuario": "bi", "senha": "{{ENCRYPT(...)}}"}. Clique em Próximo.
2. Testar e Extrair Token: clique em Enviar Requisição. Na resposta, clique no valor do token. O HubCount BI Studio preenche Localização do Token na Resposta (corpo JSON ou cabeçalho) e Caminho do Token / Nome do Cabeçalho, como data.access_token. Você também pode digitar o caminho.
3. Posicionamento do Token na Requisição: em Colocar Token Em, escolha Cabeçalho ou Parâmetro de Consulta e o nome, como Authorization. Em Prefixo do Token, informe o prefixo se a API pedir, como Bearer (com o espaço no fim).

Criar o cubo

Depois de salvar a conexão, o assistente continua na mesma tela com os campos do endpoint.

O cubo abre na aba Endpoint de API. Clique em Enviar para fazer a chamada e ver a resposta. Depois da primeira resposta, a aba Mapeamento de Campos fica disponível para conferir os campos.

Paginação

Ao lado da URL, o HubCount BI Studio mostra como fica a primeira chamada, como ?page=1&per_page=100.

Opção	Quando usar	Campos
Sem paginação	A API devolve tudo de uma vez	Nenhum. Padrão.
Offset e Limit	A API recebe a posição inicial e a quantidade	Offset Param Name (ex.: offset), Limit Param Name (ex.: limit), Initial Offset (normalmente 0), Records per page.
Número da Página	A API recebe o número da página	Param Name (ex.: page), Initial Page (normalmente 1), Page Size Param Name (ex.: per_page), Page Size.
Paginação por data	A API busca por intervalos de data	Parâmetro da data inicial, Parâmetro da data final, Data inicial, Data final (vazio = hoje), Período da paginação (Mês ou Ano, padrão Ano) e Formato da data (padrão yyyy-MM-dd).
Link no Corpo da Resposta	A resposta traz o link da próxima página no JSON	Next Link Path e Previous Link Path.
Link no Header da Resposta	A resposta traz o link da próxima página no cabeçalho Link	Next Link Path, Rel (ex.: next) e Previous Link Path.
Cursor	A resposta traz um cursor para pedir a próxima página	Cursor Param Name (ex.: after), Initial Cursor (opcional) e Next Cursor Path.

Localização de Paginação define onde os parâmetros de paginação vão: Param (na URL, padrão), Header ou Body. Body só fica disponível em chamadas POST. Os formatos de data aceitos são yyyy-MM-dd, dd/MM/yyyy, MM/dd/yyyy, yyyyMMdd e yyyy-MM.

Datas que mudam sozinhas

Na URL e no corpo da chamada, use variáveis que o HubCount BI Studio troca na hora da chamada. Veja a lista completa no ícone de Variáveis em tempo de execução ao lado da URL.

Variável	Vira
{{TODAY}}	A data de hoje, no formato yyyy-MM-dd
{{YESTERDAY}}	A data de ontem
{{START_OF_MONTH}} e {{END_OF_MONTH}}	O primeiro e o último dia do mês atual
{{START_OF_YEAR}} e {{END_OF_YEAR}}	O primeiro e o último dia do ano atual
{{TODAY|dd/MM/yyyy}}	A data de hoje no formato que você escolher

Exemplo: /v2/oportunidades?desde={{START_OF_MONTH}}&ate={{TODAY}} busca sempre as oportunidades do mês corrente.

Exemplo: oportunidades do CRM da Aurora

A Contabilidade Exemplo monta o projeto “Resultado Comercial 2026” para o cliente Aurora Comércio Ltda. O CRM da Aurora (fictício) tem esta API:

• URL base: https://api.crm-aurora.com.br
• Autenticação: chave no cabeçalho X-API-Key
• Endpoint: GET /v2/oportunidades?page=1&per_page=100, com no máximo 60 chamadas por minuto

A resposta tem este formato:

{
  "data": [
    { "id": 981, "data": "2026-03-04", "unidade": "Varejo", "valor": 18500.0, "etapa": "ganha" },
    { "id": 982, "data": "2026-03-05", "unidade": "Indústria", "valor": 42000.0, "etapa": "proposta" }
  ],
  "page": 1,
  "total_pages": 7
}

Onde	Campo	Valor
Conexão	URL Base	https://api.crm-aurora.com.br (com Salvar e Salvar apenas base)
Conexão	Tipo de Autenticação	Chave de API, Header, X-API-Key
Conexão	Requisições por Minuto	60
Cubo	URL do Endpoint	/v2/oportunidades
Cubo	Paginação	Número da Página: page, 1, per_page, 100
Cubo	Caminho de Extração de Dados	data

Cada item de data vira uma linha do cubo, com os campos id, data, unidade, valor e etapa.

API que atende várias empresas

No HubCount, o projeto pode ter empresas vinculadas. Se a API devolve registros de mais de uma empresa do projeto, mantenha na resposta o campo que identifica a empresa e marque-o com o tipo Id da Empresa na aba Mapeamento de Campos. Assim cada registro fica ligado à empresa a que pertence. Veja Campos do cubo e Empresas do escritório no projeto.

Erros comuns

Situação	O que fazer
Por favor, preencha todos os campos antes de enviar o formulário.	Ao salvar a conexão: falta o nome, a URL base, o método ou o tipo de autenticação.
O teste de autenticação falha	O HubCount BI Studio mostra o erro que a API devolveu. Confira a credencial, o posicionamento e o nome do cabeçalho.
A chamada funciona, mas o cubo fica sem linhas	O Caminho de Extração de Dados não aponta para a lista. Olhe a resposta e use o caminho até o colchete [.
A API devolve erro 429 (muitas chamadas)	Informe ou diminua Requisições por Minuto.
Só a primeira página chega	A paginação está em Sem paginação ou os nomes dos parâmetros não batem com a documentação da API.

Cuidados

• Para atualizar o cubo sozinho, veja Atualização automática.
• Uma API na internet pode atualizar em Nuvem HubCount, sem computador ligado, desde que a conexão esteja salva na nuvem: no topo da janela da conexão, mude o Armazenamento de Local para Nuvem.
• API que só existe na rede interna atualiza em Neste computador, com o HubCount BI Studio ou o HubCount Sync Agent aberto no horário, e não pela nuvem. Veja Neste computador ou Nuvem HubCount e Sync Agent.