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
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
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:
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
Criar um Gráfico
Adicionar Pontos de Dados
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:
- Tratamento de Erros da API - Aprende sobre respostas de erro e resolução de problemas
- Referência da API REST - Referência completa de todos os endpoints da API
Quer experimentar? O plano gratuito não tem limite de tempo.
Criar conta gratuita