API OPEN SOLAIOS

Referência completa da API REST.

Integre o SOLAIOS ao seu CRM, ERP, BI ou ferramenta interna. Autenticação via Bearer Token, endpoints REST clássicos, webhooks com assinatura HMAC e SDKs oficiais para as principais linguagens.

Status: operacionalBase: https://api.solaios.com.br/v1Versão: v1 · estávelOpenAPI 3.0

Autenticação

A Open API usa Bearer Token. Gere o token em Configurações → Usuário de API dentro do painel do SOLAIOS. Cada token é exclusivo para o tenant e herda as permissões do usuário que o criou.

Header Authorization

httphttp

GET /v1/plants HTTP/1.1
Host: api.solaios.com.br
Authorization: Bearer sk_live_xxxxxxxx
Accept: application/json

Rate limits

Todas as requisições são limitadas por tenant. Os limites são reajustados por janela deslizante de 60 segundos.

Plano	Requests/min	Burst
Starter	60	100
Pro	300	500
Enterprise	1000	2000

Quando você excede o limite, a API responde com 429 Too Many Requests e os headers X-RateLimit-* indicam quando tentar de novo. Recomendamos retry exponencial com jitter.

httphttp

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 17
Retry-After: 17

Webhooks

Webhooks são o caminho mais eficiente de manter seu CRM sincronizado. Em vez de fazer polling, seu sistema recebe um POST sempre que algo relevante acontece.

Eventos disponíveis

Evento	Quando dispara
plant.critical_alert	Usina entra em status crítico.
plant.alert_resolved	Alerta foi resolvido ou ticket fechado.
plant.offline	Usina ficou mais de 2h sem comunicação.
client.created	Novo cliente cadastrado.
client.updated	Dados cadastrais do cliente mudaram.
report.sent	Relatório PDF enviado por canal.
ticket.created	Ticket aberto em uma planta.
ticket.closed	Ticket fechado.

Validação de assinatura

Toda entrega inclui o header X-Solaios-Signature: t=<unix_ts>,v1=<hmac_sha256>. Calcule o HMAC-SHA256 do corpo bruto da requisição usando o secret retornado no POST /v1/webhooks, concatenado com o timestamp. Compare em tempo constante.

validar.tsts

import crypto from 'node:crypto';

export function validar(req: Request, secret: string): boolean {
  const header = req.headers.get('X-Solaios-Signature') ?? '';
  const [tsPart, sigPart] = header.split(',');
  const ts = tsPart.replace('t=', '');
  const sigRecebido = sigPart.replace('v1=', '');

  const payload = ts + '.' + (await req.text());
  const sigCalculado = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(sigRecebido, 'hex'),
    Buffer.from(sigCalculado, 'hex')
  );
}

SDKs e exemplos

Implementações prontas para as linguagens mais comuns. Todos os SDKs oficiais são assinados pela equipe do SOLAIOS e seguem o mesmo contrato.

Node.js / TypeScript — `npm install @solaios/api`
Python — `pip install solaios`
Go — `go get github.com/solaios/solaios-go`
PHP — `composer require solaios/api`

Exemplo Node.js

listar-usinas.tsts

import Solaios from '@solaios/api';

const solaios = new Solaios({
  token: process.env.SOLAIOS_TOKEN!,
});

async function main() {
  for await (const plant of solaios.plants.list({ limit: 50 })) {
    console.log(`${plant.name} — ${plant.status} (${plant.installed_power_kwp} kWp)`);
  }
}

main();

Exemplo Python

listar_usinas.pyts

from solaios import Solaios

client = Solaios(token="sk_live_xxxxxxxx")

for plant in client.plants.list(limit=50):
    print(f"{plant.name} — {plant.status} ({plant.installed_power_kwp} kWp)")

Endpoints

Cada endpoint abaixo tem método, path, descrição e exemplo completo de request/response. Para o schema completo, consulte o OpenAPI.

GET/v1/plants

Lista todas as usinas do tenant autenticado. Suporta paginação por cursor.

Exemplo

curl https://api.solaios.com.br/v1/plants?limit=50 \
  -H "Authorization: Bearer sk_live_xxxxxxxx"

Resposta

{
  "data": [
    {
      "id": "plnt_3a8f9c",
      "name": "Usina Sol Nascente",
      "tenant_id": "tnt_2c91",
      "manufacturer": "elekeepper",
      "installed_power_kwp": 12.5,
      "status": "online",
      "last_sync_at": "2026-09-16T10:42:13Z",
      "address": {
        "city": "Belo Horizonte",
        "state": "MG",
        "concessionaria": "CEMIG"
      }
    }
  ],
  "next_cursor": null,
  "has_more": false
}

GET/v1/plants/{id}

Retorna o detalhe de uma usina específica. Inclui inversores, cliente vinculado e configuração do sistema de crédito.

Exemplo

curl https://api.solaios.com.br/v1/plants/plnt_3a8f9c \
  -H "Authorization: Bearer sk_live_xxxxxxxx"

Resposta

{
  "id": "plnt_3a8f9c",
  "name": "Usina Sol Nascente",
  "inverters": [
    {
      "id": "inv_01",
      "model": "SAJ R5",
      "serial": "S5-12345",
      "installed_power_kw": 5.0,
      "status": "online"
    }
  ],
  "client": {
    "id": "cli_42",
    "name": "Carlos Souza",
    "email": "carlos@example.com"
  },
  "credit_system": {
    "concessionaria": "CEMIG",
    "unit_code": "12345-678",
    "active": true
  }
}

GET/v1/plants/{id}/generation/daily

Série diária de geração em kWh. Aceita start_date e end_date (ISO 8601).

Exemplo

curl "https://api.solaios.com.br/v1/plants/plnt_3a8f9c/generation/daily?start_date=2026-09-01&end_date=2026-09-16" \
  -H "Authorization: Bearer sk_live_xxxxxxxx"

Resposta

{
  "plant_id": "plnt_3a8f9c",
  "unit": "kWh",
  "data": [
    { "date": "2026-09-01", "value": 42.8, "expected": 45.0 },
    { "date": "2026-09-02", "value": 48.1, "expected": 45.0 },
    { "date": "2026-09-03", "value": 38.5, "expected": 45.0 }
  ]
}

GET/v1/plants/{id}/generation/monthly

Geração mensal consolidada em kWh ou MWh. Retorna comparativo com o mesmo mês do ano anterior.

Exemplo

curl "https://api.solaios.com.br/v1/plants/plnt_3a8f9c/generation/monthly?year=2026" \
  -H "Authorization: Bearer sk_live_xxxxxxxx"

Resposta

{
  "plant_id": "plnt_3a8f9c",
  "year": 2026,
  "data": [
    { "month": 1,  "kwh": 612.4, "previous_year_kwh": 580.0 },
    { "month": 2,  "kwh": 690.1, "previous_year_kwh": 645.3 },
    { "month": 3,  "kwh": 728.9, "previous_year_kwh": 712.0 }
  ]
}

GET/v1/plants/{id}/inverters

Lista inversores com status individual (online/offline/atenção) e leitura em tempo real quando disponível.

Exemplo

curl https://api.solaios.com.br/v1/plants/plnt_3a8f9c/inverters \
  -H "Authorization: Bearer sk_live_xxxxxxxx"

Resposta

{
  "data": [
    {
      "id": "inv_01",
      "model": "SAJ R5",
      "serial": "S5-12345",
      "status": "online",
      "realtime_kw": 3.42,
      "realtime_at": "2026-09-16T10:42:08Z"
    }
  ]
}

GET/v1/plants/{id}/alerts

Lista alertas ativos e históricos. Aceita filtros por status (active/resolved) e severity (info/warning/critical).

Exemplo

curl "https://api.solaios.com.br/v1/plants/plnt_3a8f9c/alerts?status=active" \
  -H "Authorization: Bearer sk_live_xxxxxxxx"

Resposta

{
  "data": [
    {
      "id": "alt_882",
      "plant_id": "plnt_3a8f9c",
      "severity": "warning",
      "title": "Comunicação atrasada",
      "description": "Sem leitura há 1h 12min",
      "created_at": "2026-09-16T09:30:00Z",
      "status": "active"
    }
  ]
}

GET/v1/plants/{id}/consumption

Consumo instantâneo da usina: solar → casa → rede. Retorna em kW no momento da leitura.

Exemplo

curl https://api.solaios.com.br/v1/plants/plnt_3a8f9c/consumption \
  -H "Authorization: Bearer sk_live_xxxxxxxx"

Resposta

{
  "plant_id": "plnt_3a8f9c",
  "solar_kw": 4.8,
  "load_kw": 2.1,
  "grid_kw": -2.7,
  "captured_at": "2026-09-16T10:42:13Z"
}

POST/v1/webhooks

Registra um webhook para receber eventos do SOLAIOS no seu endpoint. Suporta múltiplos eventos por hook.

Exemplo

curl -X POST https://api.solaios.com.br/v1/webhooks \
  -H "Authorization: Bearer sk_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://seu-crm.com/webhooks/solaios",
    "events": ["plant.critical_alert", "plant.alert_resolved", "plant.offline"]
  }'

Resposta

{
  "id": "whk_01",
  "url": "https://seu-crm.com/webhooks/solaios",
  "events": ["plant.critical_alert", "plant.alert_resolved", "plant.offline"],
  "secret": "whsec_xxxxxxxx",
  "active": true,
  "created_at": "2026-09-16T10:42:13Z"
}

DELETE/v1/webhooks/{id}

Remove um webhook. Chamadas futuras do evento param de ser entregues imediatamente.

Exemplo

curl -X DELETE https://api.solaios.com.br/v1/webhooks/whk_01 \
  -H "Authorization: Bearer sk_live_xxxxxxxx"

Resposta

{
  "deleted": true,
  "id": "whk_01"
}

Códigos de erro

A API retorna erros no formato Problem Details (RFC 7807). O JSON traz título, status, detail e um identificador único para você reportar no suporte.

Status	Quando	Ação
400	Body malformado ou parâmetro inválido.	Revise a request.
401	Token ausente ou inválido.	Gere um novo token.
403	Token sem permissão para a operação.	Escopo insuficiente.
404	Recurso inexistente.	Confirme o id.
429	Rate limit excedido.	Aguarde Retry-After.
500	Erro interno inesperado.	Retry com backoff.
503	Manutenção programada.	Veja status.solaios.com.br.

Todos os artigos

API OPEN SOLAIOS

Referência completa da API REST.

Status: operacionalBase: https://api.solaios.com.br/v1Versão: v1 · estávelOpenAPI 3.0

Autenticação

A Open API usa Bearer Token. Gere o token em Configurações → Usuário de API dentro do painel do SOLAIOS. Cada token é exclusivo para o tenant e herda as permissões do usuário que o criou.

Header Authorization

httphttp

GET /v1/plants HTTP/1.1
Host: api.solaios.com.br
Authorization: Bearer sk_live_xxxxxxxx
Accept: application/json

Rate limits

Todas as requisições são limitadas por tenant. Os limites são reajustados por janela deslizante de 60 segundos.

Plano	Requests/min	Burst
Starter	60	100
Pro	300	500
Enterprise	1000	2000

Quando você excede o limite, a API responde com 429 Too Many Requests e os headers X-RateLimit-* indicam quando tentar de novo. Recomendamos retry exponencial com jitter.

httphttp

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 17
Retry-After: 17

Webhooks

Webhooks são o caminho mais eficiente de manter seu CRM sincronizado. Em vez de fazer polling, seu sistema recebe um POST sempre que algo relevante acontece.

Eventos disponíveis

Evento	Quando dispara
plant.critical_alert	Usina entra em status crítico.
plant.alert_resolved	Alerta foi resolvido ou ticket fechado.
plant.offline	Usina ficou mais de 2h sem comunicação.
client.created	Novo cliente cadastrado.
client.updated	Dados cadastrais do cliente mudaram.
report.sent	Relatório PDF enviado por canal.
ticket.created	Ticket aberto em uma planta.
ticket.closed	Ticket fechado.

Validação de assinatura

validar.tsts

import crypto from 'node:crypto';

export function validar(req: Request, secret: string): boolean {
  const header = req.headers.get('X-Solaios-Signature') ?? '';
  const [tsPart, sigPart] = header.split(',');
  const ts = tsPart.replace('t=', '');
  const sigRecebido = sigPart.replace('v1=', '');

  const payload = ts + '.' + (await req.text());
  const sigCalculado = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(sigRecebido, 'hex'),
    Buffer.from(sigCalculado, 'hex')
  );
}

SDKs e exemplos

Implementações prontas para as linguagens mais comuns. Todos os SDKs oficiais são assinados pela equipe do SOLAIOS e seguem o mesmo contrato.

Node.js / TypeScript — `npm install @solaios/api`
Python — `pip install solaios`
Go — `go get github.com/solaios/solaios-go`
PHP — `composer require solaios/api`

Exemplo Node.js

listar-usinas.tsts

import Solaios from '@solaios/api';

const solaios = new Solaios({
  token: process.env.SOLAIOS_TOKEN!,
});

async function main() {
  for await (const plant of solaios.plants.list({ limit: 50 })) {
    console.log(`${plant.name} — ${plant.status} (${plant.installed_power_kwp} kWp)`);
  }
}

main();

Exemplo Python

listar_usinas.pyts

from solaios import Solaios

client = Solaios(token="sk_live_xxxxxxxx")

for plant in client.plants.list(limit=50):
    print(f"{plant.name} — {plant.status} ({plant.installed_power_kwp} kWp)")

Endpoints

Cada endpoint abaixo tem método, path, descrição e exemplo completo de request/response. Para o schema completo, consulte o OpenAPI.

GET/v1/plants

Lista todas as usinas do tenant autenticado. Suporta paginação por cursor.

Exemplo

curl https://api.solaios.com.br/v1/plants?limit=50 \
  -H "Authorization: Bearer sk_live_xxxxxxxx"

Resposta

{
  "data": [
    {
      "id": "plnt_3a8f9c",
      "name": "Usina Sol Nascente",
      "tenant_id": "tnt_2c91",
      "manufacturer": "elekeepper",
      "installed_power_kwp": 12.5,
      "status": "online",
      "last_sync_at": "2026-09-16T10:42:13Z",
      "address": {
        "city": "Belo Horizonte",
        "state": "MG",
        "concessionaria": "CEMIG"
      }
    }
  ],
  "next_cursor": null,
  "has_more": false
}

GET/v1/plants/{id}

Retorna o detalhe de uma usina específica. Inclui inversores, cliente vinculado e configuração do sistema de crédito.

Exemplo

curl https://api.solaios.com.br/v1/plants/plnt_3a8f9c \
  -H "Authorization: Bearer sk_live_xxxxxxxx"

Resposta

{
  "id": "plnt_3a8f9c",
  "name": "Usina Sol Nascente",
  "inverters": [
    {
      "id": "inv_01",
      "model": "SAJ R5",
      "serial": "S5-12345",
      "installed_power_kw": 5.0,
      "status": "online"
    }
  ],
  "client": {
    "id": "cli_42",
    "name": "Carlos Souza",
    "email": "carlos@example.com"
  },
  "credit_system": {
    "concessionaria": "CEMIG",
    "unit_code": "12345-678",
    "active": true
  }
}

GET/v1/plants/{id}/generation/daily

Série diária de geração em kWh. Aceita start_date e end_date (ISO 8601).

Exemplo

curl "https://api.solaios.com.br/v1/plants/plnt_3a8f9c/generation/daily?start_date=2026-09-01&end_date=2026-09-16" \
  -H "Authorization: Bearer sk_live_xxxxxxxx"

Resposta

{
  "plant_id": "plnt_3a8f9c",
  "unit": "kWh",
  "data": [
    { "date": "2026-09-01", "value": 42.8, "expected": 45.0 },
    { "date": "2026-09-02", "value": 48.1, "expected": 45.0 },
    { "date": "2026-09-03", "value": 38.5, "expected": 45.0 }
  ]
}

GET/v1/plants/{id}/generation/monthly

Geração mensal consolidada em kWh ou MWh. Retorna comparativo com o mesmo mês do ano anterior.

Exemplo

curl "https://api.solaios.com.br/v1/plants/plnt_3a8f9c/generation/monthly?year=2026" \
  -H "Authorization: Bearer sk_live_xxxxxxxx"

Resposta

{
  "plant_id": "plnt_3a8f9c",
  "year": 2026,
  "data": [
    { "month": 1,  "kwh": 612.4, "previous_year_kwh": 580.0 },
    { "month": 2,  "kwh": 690.1, "previous_year_kwh": 645.3 },
    { "month": 3,  "kwh": 728.9, "previous_year_kwh": 712.0 }
  ]
}

GET/v1/plants/{id}/inverters

Lista inversores com status individual (online/offline/atenção) e leitura em tempo real quando disponível.

Exemplo

curl https://api.solaios.com.br/v1/plants/plnt_3a8f9c/inverters \
  -H "Authorization: Bearer sk_live_xxxxxxxx"

Resposta

{
  "data": [
    {
      "id": "inv_01",
      "model": "SAJ R5",
      "serial": "S5-12345",
      "status": "online",
      "realtime_kw": 3.42,
      "realtime_at": "2026-09-16T10:42:08Z"
    }
  ]
}

GET/v1/plants/{id}/alerts

Lista alertas ativos e históricos. Aceita filtros por status (active/resolved) e severity (info/warning/critical).

Exemplo

curl "https://api.solaios.com.br/v1/plants/plnt_3a8f9c/alerts?status=active" \
  -H "Authorization: Bearer sk_live_xxxxxxxx"

Resposta

{
  "data": [
    {
      "id": "alt_882",
      "plant_id": "plnt_3a8f9c",
      "severity": "warning",
      "title": "Comunicação atrasada",
      "description": "Sem leitura há 1h 12min",
      "created_at": "2026-09-16T09:30:00Z",
      "status": "active"
    }
  ]
}

GET/v1/plants/{id}/consumption

Consumo instantâneo da usina: solar → casa → rede. Retorna em kW no momento da leitura.

Exemplo

curl https://api.solaios.com.br/v1/plants/plnt_3a8f9c/consumption \
  -H "Authorization: Bearer sk_live_xxxxxxxx"

Resposta

{
  "plant_id": "plnt_3a8f9c",
  "solar_kw": 4.8,
  "load_kw": 2.1,
  "grid_kw": -2.7,
  "captured_at": "2026-09-16T10:42:13Z"
}

POST/v1/webhooks

Registra um webhook para receber eventos do SOLAIOS no seu endpoint. Suporta múltiplos eventos por hook.

Exemplo

curl -X POST https://api.solaios.com.br/v1/webhooks \
  -H "Authorization: Bearer sk_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://seu-crm.com/webhooks/solaios",
    "events": ["plant.critical_alert", "plant.alert_resolved", "plant.offline"]
  }'

Resposta

{
  "id": "whk_01",
  "url": "https://seu-crm.com/webhooks/solaios",
  "events": ["plant.critical_alert", "plant.alert_resolved", "plant.offline"],
  "secret": "whsec_xxxxxxxx",
  "active": true,
  "created_at": "2026-09-16T10:42:13Z"
}

DELETE/v1/webhooks/{id}

Remove um webhook. Chamadas futuras do evento param de ser entregues imediatamente.

Exemplo

curl -X DELETE https://api.solaios.com.br/v1/webhooks/whk_01 \
  -H "Authorization: Bearer sk_live_xxxxxxxx"

Resposta

{
  "deleted": true,
  "id": "whk_01"
}

Códigos de erro

A API retorna erros no formato Problem Details (RFC 7807). O JSON traz título, status, detail e um identificador único para você reportar no suporte.

Status	Quando	Ação
400	Body malformado ou parâmetro inválido.	Revise a request.
401	Token ausente ou inválido.	Gere um novo token.
403	Token sem permissão para a operação.	Escopo insuficiente.
404	Recurso inexistente.	Confirme o id.
429	Rate limit excedido.	Aguarde Retry-After.
500	Erro interno inesperado.	Retry com backoff.
503	Manutenção programada.	Veja status.solaios.com.br.