Pedidos e Respostas da API

Este documento cobre os detalhes de como fazer pedidos à API do Dashboard.PT e como lidar com as respostas, incluindo formatos de pedido, estruturas de resposta e tratamento de erros.

Formato do Pedido

Todos os pedidos à API do Dashboard.PT devem:

  • Usar HTTPS
  • Incluir um cabeçalho de autorização com a tua chave de API
  • Enviar dados em formato JSON nos pedidos POST e PUT
  • Usar os métodos HTTP apropriados para as diferentes operações

Cabeçalhos

Cabeçalho Valor Descrição
Authorization Bearer YOUR_API_KEY Obrigatório para autenticação
Content-Type application/json Obrigatório para pedidos POST e PUT
Accept application/json Opcional, indica o formato de resposta pretendido

Exemplo de Pedido POST

POST /api/data-points HTTP/1.1
Host: dashboard.pt
Authorization: Bearer your-api-key
Content-Type: application/json

{
  "graph_id": 123,
  "data": [
    {
      "timestamp": "2023-06-15 14:30:00",
      "value": 42,
      "label": "Example"
    }
  ]
}

Exemplo de Pedido GET com Parâmetros

GET /api/graphs?limit=10&offset=0 HTTP/1.1
Host: dashboard.pt
Authorization: Bearer your-api-key
Accept: application/json

Parâmetros Comuns de Pedido

Muitos endpoints da API suportam estes parâmetros comuns para filtragem e paginação:

Parâmetro Descrição Exemplo
limit Número máximo de resultados a devolver (por omissão: 100, máx: 1000) ?limit=50
offset Número de registos a saltar (para paginação) ?offset=100
sort Campo pelo qual ordenar ?sort=created_at
order Ordem de ordenação (asc ou desc) ?order=desc
filter[field] Filtrar resultados pelo valor do campo ?filter[type]=line
search Termo de pesquisa a encontrar nos campos de nome ou descrição ?search=sales

Exemplos de Filtragem

Combina vários parâmetros para filtrar e paginar resultados:

# Get all line graphs, sorted by creation date (newest first), 10 per page GET /api/graphs?filter[type]=line&sort=created_at&order=desc&limit=10&offset=0 # Search for dashboards with "sales" in the name, 20 per page, page 2 GET /api/dashboards?search=sales&limit=20&offset=20

Formatos do Corpo do Pedido

Nos pedidos POST e PUT, os dados têm de ser enviados em formato JSON. Aqui ficam exemplos para diferentes endpoints:

Criar um Dashboard

POST /api/dashboards HTTP/1.1 Host: dashboard.pt Authorization: Bearer your-api-key Content-Type: application/json { "name": "Sales Dashboard", "description": "Monthly sales performance tracking", "is_public": false }

Criar um Gráfico

POST /api/graphs HTTP/1.1 Host: dashboard.pt Authorization: Bearer your-api-key Content-Type: application/json { "dashboard_id": 123, "name": "Monthly Sales", "type": "line", "config": { "theme": "light", "title": "Monthly Sales Trends", "xAxis": { "title": "Month" }, "yAxis": { "title": "Revenue (€)", "min": 0 }, "legend": true, "animation": true, "updateFrequency": "daily" }, "is_public": false }

Adicionar Pontos de Dados

POST /api/data-points HTTP/1.1 Host: dashboard.pt Authorization: Bearer your-api-key Content-Type: application/json { "graph_id": 123, "data": [ { "timestamp": "2023-06-15 14:30:00", "value": 42.5, "label": "June Sales" }, { "timestamp": "2023-07-15 14:30:00", "value": 47.8, "label": "July Sales" } ] }

Exemplos de Código

Não precisas de instalar nada: basta um cliente HTTP, que a tua linguagem já tem. Estes exemplos enviam um ponto para o gráfico 123, por isso substitui o número pelo do teu gráfico e a chave pela tua.

cURL

curl -X POST https://dashboard.pt/api/data-points \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"graph_id": 123, "data": [{"timestamp": "2026-06-15 14:30:00", "value": 42.5, "label": "June Sales"}]}'

JavaScript (Node.js 18 ou mais recente)

fetch('https://dashboard.pt/api/data-points', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ' + process.env.DASHBOARD_API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    graph_id: 123,
    data: [{ timestamp: '2026-06-15 14:30:00', value: 42.5, label: 'June Sales' }]
  })
}).then(async (response) => {
  console.log(response.status, await response.json());
});

Python

import json
import os
import urllib.request

request = urllib.request.Request(
    "https://dashboard.pt/api/data-points",
    data=json.dumps({
        "graph_id": 123,
        "data": [{"timestamp": "2026-06-15 14:30:00", "value": 42.5, "label": "June Sales"}],
    }).encode(),
    headers={
        "Authorization": "Bearer " + os.environ["DASHBOARD_API_KEY"],
        "Content-Type": "application/json",
    },
)
with urllib.request.urlopen(request, timeout=30) as response:
    print(response.status, response.read().decode())

PHP

<?php
$ch = curl_init('https://dashboard.pt/api/data-points');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('DASHBOARD_API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'graph_id' => 123,
        'data' => [['timestamp' => '2026-06-15 14:30:00', 'value' => 42.5, 'label' => 'June Sales']],
    ]),
]);
echo curl_exec($ch);

Se correr bem, recebes o estado HTTP 200 e {"status":"success","message":"1 data points added"}.

Atenção: o Dashboard.PT não tem bibliotecas oficiais em npm, PyPI ou Packagist. Se encontrares um pacote com este nome, não é nosso: não lhe dês a tua chave.

Próximos Passos

Agora que percebes como fazer pedidos à API, consulta estes documentos relacionados:

Quer experimentar? O plano gratuito não tem limite de tempo.

Criar conta gratuita