Referência da API

URL base

https://api.vbatpower.com

Todos os endpoints têm o prefixo /api/v1. A autenticação é feita por cookies de sessão (para clientes de navegador) ou por chaves de API (para clientes MCU/servidor). A API é gratuita e sem limites de utilização para além dos limites de taxa de proteção contra abuso descritos abaixo.

Autenticação

{"email": "user@example.com", "password": "securePassword123"}

{"email": "user@example.com", "password": "securePassword123"}

Projetos

Todos os endpoints de projetos requerem autenticação (cookie de sessão). Os corpos de projeto podem ter até 2 MB.

{"name": "Sensor Node", "data": {"batteries": [...]}}

Esquema data do projeto

O campo data contém o modelo do projeto: um objeto com um array batteries. Cada bateria tem um id numérico (o seu índice hierárquico de profundidade 1) e um array components; cada componente tem um id e um array states; cada estado tem um id mais os seus campos de modo de funcionamento. Os valores de id mapeiam diretamente para os IDs de telemetria em notação por pontos (bateria 0 → componente 0.0 → estado 0.0.0).

{
  "name": "Sensor Node",
  "description": "ESP32 + INA219",
  "tags": ["esp32", "lipo"],
  "data": {
    "batteries": [
      {
        "id": 0,
        "name": "18650 cell",
        "voltageMin": 3.0,
        "voltageMax": 4.2,
        "current": 2.5,
        "currentUnit": "Ah",
        "components": [
          {
            "id": 0,
            "name": "ESP32",
            "states": [
              {"id": 0, "name": "Deep Sleep", "alwaysOn": true, "current": 10, "currentUnit": "u"},
              {"id": 1, "name": "Active", "current": 80, "currentUnit": "m", "interval": 60, "intervalUnit": "s", "execTime": 5, "execTimeUnit": "s"}
            ]
          }
        ]
      }
    ]
  }
}

Campos de estado comuns: name, alwaysOn (booleano), current + currentUnit, interval + intervalUnit, execTime + execTimeUnit, e runOnce (booleano). O objeto data é armazenado tal como está, pelo que quaisquer campos produzidos pela aplicação são preservados na ida e volta.

Telemetria

{"records": [
  {"id": "0", "type": "v", "value": 3.28, "unit": "V", "nonce": 1, "runid": 1},
  {"id": "0.0.0", "type": "t", "value": 1523, "unit": "ms", "nonce": 1, "runid": 1},
  {"id": "0.0.0", "type": "v", "value": 12.5, "unit": "mA", "nonce": 1, "runid": 1}
]}

{
  "project_id": 1,
  "records": [
    {"id": 42, "record_id": "0", "record_type": "v", "value": 3.28, "unit": "V", "nonce": 1, "runid": 1, "received_at": "2026-01-01T12:00:00.000Z"}
  ],
  "next_cursor": 42
}

Histórico de Fórmulas

Todos os endpoints de histórico de fórmulas requerem autenticação (cookie de sessão).

{"formula_id": "ohms-law", "solve_for": "V", "inputs": {"I": 0.5, "R": 100}, "result": 50}

Chaves de API

Todos os endpoints de gestão de chaves de API requerem autenticação (cookie de sessão). As chaves são usadas por MCUs e scripts para carregar telemetria sem uma sessão de navegador.

{"project_id": 1, "name": "ESP32 Sensor"}

Limites de Taxa

O VBatPower é gratuito e sem quotas de utilização. Os únicos limites são os limites de taxa de proteção contra abuso, aplicados por IP (autenticação) ou por projeto (telemetria) em produção:

• POST /api/v1/auth/register — 5 pedidos por 15 minutos por IP
• POST /api/v1/auth/login — 10 pedidos por 15 minutos por IP
• POST /api/v1/telemetry — 60 pedidos por minuto por projeto

Exceder um limite devolve 429 com o corpo {"error": "Too many requests"}. Os corpos dos pedidos também têm limite: 64 KB para as rotas de autenticação, chaves e histórico de fórmulas; 2 MB para projetos e telemetria. Corpos demasiado grandes devolvem 413 com {"error": "Payload too large"}.

Respostas de Erro

Todos os erros devolvem JSON com um campo error a descrever o problema:

{"error": "Not authenticated"}

Códigos de estado HTTP usados pela API:

• 400 — pedido inválido (JSON inválido, campo em falta ou malformado)
• 401 — não autenticado (sessão em falta/expirada ou chave de API inválida)
• 403 — proibido (chave de API não restrita ao projeto solicitado)
• 404 — não encontrado (ou não pertencente ao utilizador autenticado)
• 409 — conflito (email já registado)
• 413 — payload demasiado grande
• 429 — demasiados pedidos (limite de taxa excedido)
• 500 — erro interno

Tutorial de MCU Ponta a Ponta

Isto liga os endpoints para o fluxo típico de hardware: gerar uma chave, criar um projeto, enviar telemetria e lê-la de volta. Todos os pedidos usam o URL base https://api.vbatpower.com.

1. Criar um projeto (sessão de navegador)

Inicie sessão na aplicação, ou chame a API com o seu cookie de sessão:

curl -X POST https://api.vbatpower.com/api/v1/projects \
  -H "Content-Type: application/json" \
  --cookie "session=YOUR_SESSION" \
  -d '{"name":"Sensor Node","data":{"batteries":[{"id":0,"components":[{"id":0,"states":[{"id":0}]}]}]}}'
# -> 201 {"project": {"id": 1, ...}}

2. Gerar uma chave de API para esse projeto

curl -X POST https://api.vbatpower.com/api/v1/keys \
  -H "Content-Type: application/json" \
  --cookie "session=YOUR_SESSION" \
  -d '{"project_id":1,"name":"ESP32 Sensor"}'
# -> 201 {"key": "vbat_xxxxxxxx...", "project_id": 1}
# Copy the key now — it is shown only once.

3. Enviar telemetria do dispositivo via POST (chave Bearer)

Não é necessária sessão nem cookie — a chave autentica o dispositivo e seleciona o projeto. Consulte Integração de MCU para código de Arduino/ESP32/STM32 que produz este pedido.

curl -X POST https://api.vbatpower.com/api/v1/telemetry \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer vbat_xxxxxxxx..." \
  -d '{"records":[
    {"id":"0","type":"v","value":3.28,"unit":"V","nonce":1,"runid":1},
    {"id":"0.0.0","type":"t","value":1523,"unit":"ms","nonce":1,"runid":1},
    {"id":"0.0.0","type":"v","value":12.5,"unit":"mA","nonce":1,"runid":1},
    {"id":"0.0.0","type":"n","value":0,"unit":"ms","nonce":1,"runid":1}
  ]}'
# -> 201 {"status": "ok", "inserted": 4}

4. Verificar se os dados chegaram

Leia-os de volta com a mesma chave, ou abra a página de Gráficos do projeto na aplicação:

curl https://api.vbatpower.com/api/v1/telemetry/1?limit=1000 \
  -H "Authorization: Bearer vbat_xxxxxxxx..."
# -> 200 {"project_id": 1, "records": [...], "next_cursor": 42}
# Page through more rows by passing ?cursor=42 on the next call.