API Monitoramento — usinas, equipamentos, portais e telemetria
Referência de Monitoramento para integrar as operações descritas abaixo.
Guia principal e downloads · Exemplos · Endpoints
Índice clicável
Usinas e frota — plants · Vínculos da usina com o CRM — crm · Equipamentos — devices · Conexões com fabricantes — portal-connections · Leituras e telemetria — readings
Como usar esta referência
API de Monitoramento de usinas: https://monitoramento.groner.app (host). As rotas incluem /api/v1. Use MONITORAMENTO_URL com esse host, sem /api/v1. Tenant é resolvido pelo token do ecossistema nas operações correspondentes. Resposta comum: success, data, timestamp; algumas actions omitem timestamp. Rotas legadas de faturamento indicadas abaixo têm guard próprio.
Substitua tenant/token pelo ambiente autorizado e IDs de exemplo pelos cadastros reais. Os comandos são Bash; no PowerShell use curl.exe e adapte variáveis e continuação de linha.
Recursos compartilhados: a organização segue a finalidade principal da operação, não exclusividade de produto. Um client consumir um controller não significa que todas as actions desse controller sejam liberadas para aquele usuário. Consulte guard e contrato.
Cadastro no CRM é diferente: /api/AbaComplementar/Monitoramento está na referência de operação do CRM. UUID de usina, ID do negócio e ID da aba de monitoramento são identificadores distintos.
Exemplos de requisição e resposta
Consultar a frota de usinas
Requisição completa (Bash):
curl --request GET \
--url "$MONITORAMENTO_URL/api/v1/plants?page=1&limit=20" \
--header "Authorization: Bearer $TOKEN" \
--header "Accept: application/json"Resposta ilustrativa — HTTP 200:
{
"success": true,
"data": {
"data": [],
"total": 0,
"page": 1,
"limit": 20,
"totalPages": 0,
"hasNextPage": false,
"hasPreviousPage": false
},
"timestamp": 1791979200000
}A lista está em data.data; page e limit não são PageNumber e PageSize. IDs de usina e equipamentos são UUIDs do Monitoramento. O vínculo com o negócio usa external_project_id, não uma substituição direta de UUID por ProjetoId.
Referência dos endpoints
Usinas e frota — plants
GET /api/v1/plants/:plantId/client-access
Acesso PLG da usina no Portal do Cliente (full/trial/paywall). 1ª chamada em modo PLG inicia o trial.
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
POST /api/v1/plants/:plantId/client-access/subscribe
Contratação self-service do plano PLG: cria/ativa o contrato no provedor configurado e devolve o link de pagamento.
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
GET /api/v1/plants/:plantId/client-access/subscription
Assinatura PLG da usina (status, plano, valor e faturas p/ 2ª via). data=null quando não há.
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
POST /api/v1/plants/:plantId/client-access/cancel
Cancela a assinatura PLG da usina a pedido do cliente (cancela a recorrência no provedor).
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
GET /api/v1/plants/plg/funnel
Funil PLG do tenant: trials iniciados/ativos, expirados, aguardando pagamento, assinantes, conversão e MRR.
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
GET /api/v1/plants/health-summary
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
O corpo/filtro é validado no handler; confirme a operação no Swagger/contrato implantado antes de enviar campos adicionais.
POST /api/v1/plants/health-recompute
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
O corpo/filtro é validado no handler; confirme a operação no Swagger/contrato implantado antes de enviar campos adicionais.
GET /api/v1/plants/cockpit/summary
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
O corpo/filtro é validado no handler; confirme a operação no Swagger/contrato implantado antes de enviar campos adicionais.
GET /api/v1/plants/cockpit
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
O corpo/filtro é validado no handler; confirme a operação no Swagger/contrato implantado antes de enviar campos adicionais.
GET /api/v1/plants/central-acao
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
O corpo/filtro é validado no handler; confirme a operação no Swagger/contrato implantado antes de enviar campos adicionais.
GET /api/v1/plants/ampliacao
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
O corpo/filtro é validado no handler; confirme a operação no Swagger/contrato implantado antes de enviar campos adicionais.
GET /api/v1/plants
List plants
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
query: search (string); status (string); city (string); state (string); external_project_id (string); health (string); health_causa (string); sort (string); order (string); type (string); online (string); monitoring_plan_id (string); tag_id (string); portal_type (string); page (number); limit (number).
GET /api/v1/plants/:id
Get plant by ID
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
path: id (string obrigatório).
POST /api/v1/plants/:id/photo
Upload da foto de capa da usina (JPG/PNG/WebP)
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
path: id (string obrigatório).
GET /api/v1/plants/:id/overview
Get plant overview with realtime data
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
path: id (string obrigatório).
GET /api/v1/plants/:id/generation-history
Generation history (daily/monthly) from the plant portal
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
path: id (string obrigatório).
query: granularity (string); date (string).
POST /api/v1/plants/:id/import-history
Import (backfill) generation history from the plant portal
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
path: id (string obrigatório).
GET /api/v1/plants/:id/hourly-generation
Curva do dia vinda do portal (energia por hora). Preenchida no import de histórico.
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
path: id (string obrigatório).
GET /api/v1/plants/metrics-summary
Resumo de métricas (PR, yield, disponibilidade, geração) de até 200 usinas na janela
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
query: ids (string obrigatório); days (number).
GET /api/v1/plants/:id/metrics
Daily efficiency/performance metrics (PR, yield, capacity factor, availability)
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
path: id (string obrigatório).
query: days (number); from (string); to (string).
GET /api/v1/plants/:id/sync-logs
Log da usina: histórico de coletas/sync da conta de portal (com o motivo das falhas)
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
path: id (string obrigatório).
query: limit (number).
GET /api/v1/plants/:id/sources
Fontes de coleta da usina (conta de portal + estação). Uma usina pode ter N.
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
path: id (string obrigatório).
POST /api/v1/plants/:id/sources
Adiciona uma fonte (conta de portal + estação) a uma usina existente
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
path: id (string obrigatório).
body: portal_connection_id (string obrigatório); external_station_id (string obrigatório).
GET /api/v1/plants/inverters/pending
Propostas de saída de inversor aguardando confirmação
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
GET /api/v1/plants/inverters/:sn/history
Por onde este número de série já passou (currículo do inversor)
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
GET /api/v1/plants/:id/inverters
Inversores lotados nesta usina (abertos e histórico)
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
POST /api/v1/plants/:id/inverters
Registra manualmente um inversor nesta usina (SN + período)
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
body: serial_number (string obrigatório); rated_power_kw (number); started_at (string obrigatório); ended_at (string); note (string).
PATCH /api/v1/plants/inverters/:assignmentId
Corrige a lotação de um inversor (datas, potência, observação)
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
POST /api/v1/plants/inverters/:assignmentId/resolve
Confirma a proposta: o inversor saiu (fecha) ou continua na usina
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
body: saiu (boolean obrigatório); quando (string).
DELETE /api/v1/plants/inverters/:assignmentId
Remove um registro de lotação
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
GET /api/v1/plants/trash
Usinas na lixeira (excluídas, restauráveis)
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
POST /api/v1/plants/:id/restore
Restaura uma usina da lixeira
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
DELETE /api/v1/plants/:id/sources/:sourceId
Remove uma fonte de coleta da usina
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
path: id (string obrigatório); sourceId (string obrigatório).
GET /api/v1/plants/slim
Frota inteira em campos mínimos (id, nome, posição, saúde, portal)
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
GET /api/v1/plants/portals
Lista os portais com usinas no tenant (com contagem)
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
GET /api/v1/plants/lojas
Lista as lojas/filiais com usinas no tenant (com contagem)
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
GET /api/v1/plants/tags
Lista as tags do tenant
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
POST /api/v1/plants/tags
Cria uma tag no tenant
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
body: name (string obrigatório); color (string).
PATCH /api/v1/plants/tags/:tagId
Renomeia/recolore uma tag
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
path: tagId (string obrigatório).
body: name (string); color (string).
DELETE /api/v1/plants/tags/:tagId
Apaga uma tag (remove de todas as usinas)
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
path: tagId (string obrigatório).
POST /api/v1/plants/:id/tags
Atribui uma tag à usina
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
path: id (string obrigatório).
body: tag_id (string obrigatório).
DELETE /api/v1/plants/:id/tags/:tagId
Remove uma tag da usina
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
path: id (string obrigatório); tagId (string obrigatório).
GET /api/v1/plants/monitoring-plans
Planos de monitoramento do tenant
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
POST /api/v1/plants/monitoring-plans
Cria um plano de monitoramento
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
body: name (string obrigatório); color (string); description (string); client_view_enabled (boolean); price_mode (string); fixed_amount_brl (['number', 'null']); per_plant_amount_brl (['number', 'null']); plg_enabled (boolean); trial_days (integer); trial_scope (string); features (object); trial_end_plan_id (['string', 'null']); upgrade_plan_id (['string', 'null']); overdue_grace_days (integer).
PATCH /api/v1/plants/monitoring-plans/:planId
Atualiza um plano de monitoramento
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
path: planId (string obrigatório).
body: name (string); color (string); description (string); client_view_enabled (boolean); price_mode (string); fixed_amount_brl (['number', 'null']); per_plant_amount_brl (['number', 'null']); plg_enabled (boolean); trial_days (integer); trial_scope (string); features (object); trial_end_plan_id (['string', 'null']); upgrade_plan_id (['string', 'null']); overdue_grace_days (integer).
DELETE /api/v1/plants/monitoring-plans/:planId
Apaga um plano de monitoramento (usinas ficam sem plano)
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
path: planId (string obrigatório).
POST /api/v1/plants/monitoring-plans/assign
Vincula (ou desvincula, plan_id null) um lote de usinas a um plano
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
body: plan_id (['string', 'null']); plant_ids (array obrigatório).
GET /api/v1/plants/:id/expectation
Expectativa de geração mensal (do orçamento) da usina
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
path: id (string obrigatório).
PUT /api/v1/plants/:id/expectation
Salva (upsert) a expectativa de geração mensal da usina
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
path: id (string obrigatório).
POST /api/v1/plants/:id/expectation/estimate
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
path: id (string obrigatório).
body: apply (boolean); overwrite (boolean).
GET /api/v1/plants/:id/irradiacao
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
path: id (string obrigatório).
query: tipo (string).
GET /api/v1/plants/performance-summary
Cohorts de desempenho (1D/15D/30D/12M) de todas as usinas do tenant
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
GET /api/v1/plants/performance-reference
PR de referência geral do tenant + padrão e limites
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
GET /api/v1/plants/performance-distribution
Distribuição do desempenho por faixa (lt70/70_90/90_110/gte110/sem_dado)
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
GET /api/v1/plants/:id/performance
Régua de desempenho da usina (janelas até ontem + PR de referência)
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
PUT /api/v1/plants/performance-reference
Define o PR de referência geral (0,50–0,95); null volta ao padrão
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
body: pr_ref (['number', 'null']).
GET /api/v1/plants/fleet-stats
KPIs agregados da frota (total, potência instalada, energia hoje)
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
POST /api/v1/plants
Create a new plant
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
body: name (string obrigatório); capacity_kWp (number obrigatório); address (string); city (string); state (string); lat (number); lng (number); timezone (string); commission_date (string); metadata (object).
PATCH /api/v1/plants/:id
Update plant
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
path: id (string obrigatório).
body: name (string); capacity_kWp (number); address (string); city (string); state (string); lat (number); lng (number); timezone (string); commission_date (string); metadata (object); investment_brl (['number', 'null']); pr_ref (['number', 'null']).
DELETE /api/v1/plants/:id
Delete plant (soft delete)
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
path: id (string obrigatório).
GET /api/v1/plants/:id/strings
Lista o cadastro de strings/MPPT da usina
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
POST /api/v1/plants/:id/strings
Cria uma string/MPPT no cadastro da usina
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
PATCH /api/v1/plants/:id/strings/:stringId
Atualiza uma string/MPPT
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
POST /api/v1/plants/:id/strings/:stringId/replicar
Replica módulo, specs e orientação desta string para outras
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
DELETE /api/v1/plants/:id/strings/:stringId
Remove uma string/MPPT
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
POST /api/v1/plants/:plantId/energy-bills
Upload de conta de energia (PDF/imagem) com extração via IA
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
POST /api/v1/plants/:plantId/energy-bills/extract-fields
Extrai os campos de cadastro (PascalCase) de uma conta de energia via IA, sem persistir
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
GET /api/v1/plants/:plantId/energy-bills
Lista contas de energia da usina
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
GET /api/v1/plants/:plantId/energy-bills/analysis
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
POST /api/v1/plants/:plantId/energy-bills/grupo-a/leitura
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
GET /api/v1/plants/:plantId/energy-bills/:invoiceId
Detalhe de uma conta de energia
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
PATCH /api/v1/plants/:plantId/energy-bills/:invoiceId
Corrige campos extraídos de uma conta de energia
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
DELETE /api/v1/plants/:plantId/energy-bills/:invoiceId
Remove uma conta de energia
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
GET /api/v1/plants/:plantId/energy-bills/:invoiceId/document
URL assinada para baixar o arquivo original da conta
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
POST /api/v1/plants/:plantId/energy-bills/:invoiceId/reprocess
Reprocessa a extração via IA de uma conta (falha/travada)
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
POST /api/v1/plants/:plantId/energy-bills/revalidate
Revalida TODAS as contas da usina com as regras determinísticas atuais (não chama a IA)
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
Vínculos da usina com o CRM — crm
GET /api/v1/crm/projetos
Lista Negócios/Projetos do CRM (safeleads) para importar como Usinas
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
GET /api/v1/crm/projetos/:id
Detalhe de um Negócio/Projeto do CRM (safeleads)
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
path: id (string obrigatório).
GET /api/v1/crm/projetos/:id/proposta
Resumo da Proposta Aceita do Negócio (geração 12m, kit, inversor, módulo, payback)
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
path: id (string obrigatório).
POST /api/v1/crm/match-estacoes
Auto-casamento em massa: estações → melhor Negócio (uma chamada)
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
POST /api/v1/crm/import
Importa Projetos do CRM como Usinas (+ Portal pré-preenchido quando possível)
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
GET /api/v1/crm/funil-monitoramento
Etapas do funil de monitoramento + os cards
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
GET /api/v1/crm/funil-monitoramento/colunas/:statusId/cards
Página seguinte de cards de uma coluna (scroll infinito)
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
GET /api/v1/crm/funil-monitoramento/:projetoId/destinos
Para onde este card pode ser movido (regras do CRM)
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
POST /api/v1/crm/funil-monitoramento/:projetoId/mover
Move o card de etapa/status no CRM
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
GET /api/v1/crm/tipos-servico
Tipos de Serviço do CRM (para escolher ao abrir a OS)
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
GET /api/v1/crm/plants/:plantId/ordens-servico
Ordens de Serviço do Negócio desta usina (todas: instalação, entrega, vistoria, manutenção)
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
PUT /api/v1/crm/plants/:plantId/negocio
Vincula a usina a um Negócio do CRM (destrava OS, relatório e retorno)
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
POST /api/v1/crm/backfill-lojas
Preenche metadata.lojaId/lojaNome das usinas com Negócio e sem loja
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
GET /api/v1/crm/agenda/:alvo
Agenda do dia de tecnicos|equipes: ordens, bloqueios e carga em minutos
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
POST /api/v1/crm/agenda/verificar-conflito
Diz se a janela conflita com algo ja agendado (avisa, nao bloqueia)
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
POST /api/v1/crm/plants/:plantId/ordem-servico
Abre uma OS no CRM a partir da usina (sem alerta)
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
POST /api/v1/crm/alertas/:alertId/ordem-servico
Abre uma OS no CRM a partir do alerta
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
Equipamentos — devices
GET /api/v1/devices
List devices
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
query: plant_id (string); type (string); status (string); search (string); page (number); limit (number).
GET /api/v1/devices/:id
Get device by ID
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
path: id (string obrigatório).
GET /api/v1/devices/:id/status
Get device status
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
path: id (string obrigatório).
GET /api/v1/devices/plant/:plantId
List devices for a plant
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
path: plantId (string obrigatório).
POST /api/v1/devices
Create a new device
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
body: plant_id (string obrigatório); type (string obrigatório); manufacturer (string); model (string); serial_number (string); rated_power_kW (number); metadata (object).
PATCH /api/v1/devices/:id
Update device
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
path: id (string obrigatório).
body: type (string); manufacturer (string); model (string); serial_number (string); rated_power_kW (number); metadata (object).
DELETE /api/v1/devices/:id
Delete device
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
path: id (string obrigatório).
Conexões com fabricantes — portal-connections
GET /api/v1/portal-connections
List portal connections
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
query: plant_id (string); portal_type (string); status (string); page (number); limit (number).
GET /api/v1/portal-connections/:id
Get portal connection by ID
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
path: id (string obrigatório).
GET /api/v1/portal-connections/:id/sync-logs
Get sync logs for a portal connection
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
path: id (string obrigatório).
query: limit (number).
POST /api/v1/portal-connections
Create a new portal connection
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
body: label (string); portal_type (string obrigatório); credentials (object obrigatório); sync_interval_sec (number).
PATCH /api/v1/portal-connections/:id
Update portal connection
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
path: id (string obrigatório).
body: credentials (object); sync_interval_sec (number); status (string).
DELETE /api/v1/portal-connections/:id
Delete portal connection
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
path: id (string obrigatório).
POST /api/v1/portal-connections/:id/test
Test portal connection
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
path: id (string obrigatório).
POST /api/v1/portal-connections/:id/sync
Trigger manual sync for portal connection
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
path: id (string obrigatório).
GET /api/v1/portal-connections/:id/stations
List stations of the portal account
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
path: id (string obrigatório).
query: refresh (string).
GET /api/v1/portal-connections/:id/sync-status
Estado do sync de estações da conta (running/total/progress)
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
path: id (string obrigatório).
POST /api/v1/portal-connections/:id/link
Link a station to a Negócio (creates the plant)
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
path: id (string obrigatório).
body: external_station_id (string obrigatório); name (string obrigatório); capacity_kWp (number); external_project_id (string); cliente (string); city (string); state (string); lat (number); lng (number); commission_date (string).
POST /api/v1/portal-connections/:id/link-bulk
Link many stations to Negócios at once (creates N plants)
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
path: id (string obrigatório).
body: items (array obrigatório); modo_faixa (string).
POST /api/v1/portal-connections/:id/unlink
Desvincula a estação da usina (única fonte → usina na Lixeira; com outras fontes → remove só esta)
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
path: id (string obrigatório).
body: external_station_id (string obrigatório).
POST /api/v1/portal-connections/:id/link-jobs
Abre o job de vínculo em massa (casa todas as estações não vinculadas)
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
POST /api/v1/portal-connections/:id/link-jobs/revisao
Abre a REVISÃO: recasa as usinas JÁ vinculadas para corrigir vínculo errado
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
GET /api/v1/portal-connections/:id/link-jobs/latest
Último job de vínculo da conexão (a tela reabre onde parou)
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
GET /api/v1/portal-connections/link-jobs/:jobId
Estado do job (a consulta também RETOMA um job órfão)
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
GET /api/v1/portal-connections/link-jobs/:jobId/items
Itens do job, paginados e filtrados no banco
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
POST /api/v1/portal-connections/link-jobs/:jobId/select
Marca/desmarca itens (ids ou todos do filtro)
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
PUT /api/v1/portal-connections/link-jobs/:jobId/items/:itemId/negocio
Troca o Negócio do item por uma das sugestões
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
POST /api/v1/portal-connections/link-jobs/:jobId/apply
Aplica o vínculo dos itens marcados (roda em segundo plano). modo_faixa: usinas novas ocupam vagas pagas (excedente nasce gratuito marcado) ou entram todas como gratuitas.
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
GET /api/v1/portal-connections/link-jobs
Importações do tenant (área de acompanhamento)
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
POST /api/v1/portal-connections/link-jobs/:jobId/retry
Tenta de novo SÓ as estações que falharam (não duplica)
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
DELETE /api/v1/portal-connections/link-jobs/:jobId
Descarta uma importação encerrada
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
POST /api/v1/portal-connections/link-jobs/:jobId/cancel
Cancela o job
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
Leituras e telemetria — readings
GET /api/v1/readings/plants-latest
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
O corpo/filtro é validado no handler; confirme a operação no Swagger/contrato implantado antes de enviar campos adicionais.
GET /api/v1/readings/plants/:plantId/latest
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
O corpo/filtro é validado no handler; confirme a operação no Swagger/contrato implantado antes de enviar campos adicionais.
GET /api/v1/readings/plants/:plantId
Acesso: JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.
O corpo/filtro é validado no handler; confirme a operação no Swagger/contrato implantado antes de enviar campos adicionais.
Veja também
Atualizado em: 14/10/2026
Obrigado!