Pular para o conteúdo principal

Primeiros passos com a API

A API do DATAHILL permite integrar sistemas externos à plataforma para consultar e atualizar indicadores de desempenho programaticamente. Esta página apresenta o fluxo básico para realizar sua primeira integração.

Antes de começar​

Para consumir a API, você precisa de três elementos:

  • Developer Token — credencial de autenticação no formato JWT. Saiba como gerar um em Gerenciar Developer Tokens.
  • Base URL — o endereço base para todas as requisições é https://api.datahill.ai/go.app.
  • Autenticação — todas as requisições devem incluir o cabeçalho Authorization: Bearer {token}, onde {token} é o seu Developer Token.
observação

O DATAHILL armazena dados de indicadores consolidados por mês e ano. Os exemplos nesta página utilizam o formato YYYY-MM para o período (por exemplo, 2025-07).

Caso 1 — Listar indicadores​

Use o endpoint GET /metrics para listar indicadores. O parâmetro q permite filtrar por nome parcial.

Requisição:

cURL
curl -X GET "https://api.datahill.ai/go.app/metrics?q=Faturamento" \
  -H "Authorization: Bearer SEU_TOKEN_AQUI"
Python
import requests

url = "https://api.datahill.ai/go.app/metrics"
headers = {"Authorization": "Bearer SEU_TOKEN_AQUI"}
params = {"q": "Faturamento"}

response = requests.get(url, headers=headers, params=params)
print(response.json())

Resposta da API:

{
  "success": true,
  "count": 1,
  "total": 1,
  "results": [
    {
      "id": "123",
      "name": "Faturamento mensal",
      "description": "Faturamento total gerado pela empresa em um mês",
      "is_formula": "0",
      "positiveval_isgood": "Y",
      "last_period": "2025-06",
      "group": {
        "id": "345",
        "name": "Receitas"
      },
      "format": {
        "id": "4",
        "name": "Decimal (100,00)"
      },
      "url": "https://api.datahill.ai/go.app/metrics?id=123"
    }
  ]
}

Guarde o valor do campo id — ele será necessário para consultar ou atualizar os dados do indicador.

Caso 2 — Recuperar o valor de desempenho de um indicador​

Use o endpoint GET /metrics.data para consultar o valor de desempenho de um indicador em um período específico.

Requisição:

cURL
curl -X GET "https://api.datahill.ai/go.app/metrics.data?metric_id=123&period=2025-07" \
  -H "Authorization: Bearer SEU_TOKEN_AQUI"
Python
import requests

url = "https://api.datahill.ai/go.app/metrics.data"
headers = {"Authorization": "Bearer SEU_TOKEN_AQUI"}
params = {"metric_id": 123, "period": "2025-07"}

response = requests.get(url, headers=headers, params=params)
print(response.json())

Resposta da API:

{
  "success": true,
  "count": 1,
  "results": [
    {
      "value": 6542221.95,
      "annotation": "Início de campanha de Vendas"
    }
  ]
}

O campo value contém o valor numérico de desempenho do indicador no período informado.

Caso 3 — Incluir um resultado para o indicador no mês atual​

Use o endpoint POST /metrics.data para enviar um novo valor de desempenho para um indicador. Se já existir um registro para o mesmo indicador e período, o valor será atualizado automaticamente.

Requisição:

cURL
curl -X POST "https://api.datahill.ai/go.app/metrics.data" \
  -H "Authorization: Bearer SEU_TOKEN_AQUI" \
  -H "Content-Type: application/json" \
  -d '{
    "metrics": { "id": 123 },
    "period": "2025-07",
    "value": 6950000.50,
    "annotation": "Expansões de contrato na curva A de clientes"
  }'
Python
import requests

url = "https://api.datahill.ai/go.app/metrics.data"
headers = {
    "Authorization": "Bearer SEU_TOKEN_AQUI",
    "Content-Type": "application/json"
}
payload = {
    "metrics": {"id": 123},
    "period": "2025-07",
    "value": 6950000.50,
    "annotation": "Expansões de contrato na curva A de clientes"
}

response = requests.post(url, headers=headers, json=payload)
print(response.json())

Resposta da API:

{
  "success": true,
  "result": {
    "id": 42,
    "url": "https://api.datahill.ai/go.app/metrics.data?id=42"
  }
}

O campo annotation é opcional. Se não for necessário, omita-o do payload.

Próximo passo​

dica

Precisa conhecer todos os endpoints, parâmetros e modelos de dados? Consulte a documentação completa da API.

Veja também​