> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://ajuda.groner.app/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# API Monitoramento — usinas, equipamentos, portais e telemetria

Referência de **Monitoramento** para integrar as operações descritas abaixo.

[Guia principal e downloads](https://ajuda.groner.app/pt-br/article/documentacao-da-api-groner-crm-vz2bq2/) · [Exemplos](#2-exemplos-de-requisicao-e-resposta) · [Endpoints](#2-referencia-dos-endpoints)

|| Revisão: **14/10/2026**. Classificação conferida nos clients dos produtos e nas rotas registradas do servidor. Respostas abaixo são exemplos completos do contrato escolhido com dados fictícios, não capturas de produção.

## Índice clicável

[Usinas e frota — plants](#3-usinas-e-frota-plants) · [Vínculos da usina com o CRM — crm](#3-vinculos-da-usina-com-o-crm-crm) · [Equipamentos — devices](#3-equipamentos-devices) · [Conexões com fabricantes — portal-connections](#3-conexoes-com-fabricantes-portal-connections) · [Leituras e telemetria — readings](#3-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):**

```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:**

```json
{
  "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.

[Voltar ao índice](#2-indice-clicavel)

#### `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.

[Voltar ao índice](#2-indice-clicavel)

#### `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.

[Voltar ao índice](#2-indice-clicavel)

#### `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.

[Voltar ao índice](#2-indice-clicavel)

#### `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.

[Voltar ao índice](#2-indice-clicavel)

#### `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.

[Voltar ao índice](#2-indice-clicavel)

#### `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.

[Voltar ao índice](#2-indice-clicavel)

#### `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.

[Voltar ao índice](#2-indice-clicavel)

#### `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.

[Voltar ao índice](#2-indice-clicavel)

#### `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.

[Voltar ao índice](#2-indice-clicavel)

#### `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.

[Voltar ao índice](#2-indice-clicavel)

#### `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).

[Voltar ao índice](#2-indice-clicavel)

#### `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).

[Voltar ao índice](#2-indice-clicavel)

#### `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).

[Voltar ao índice](#2-indice-clicavel)

#### `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).

[Voltar ao índice](#2-indice-clicavel)

#### `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).

[Voltar ao índice](#2-indice-clicavel)

#### `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).

[Voltar ao índice](#2-indice-clicavel)

#### `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).

[Voltar ao índice](#2-indice-clicavel)

#### `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).

[Voltar ao índice](#2-indice-clicavel)

#### `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).

[Voltar ao índice](#2-indice-clicavel)

#### `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).

[Voltar ao índice](#2-indice-clicavel)

#### `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).

[Voltar ao índice](#2-indice-clicavel)

#### `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).

[Voltar ao índice](#2-indice-clicavel)

#### `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.

[Voltar ao índice](#2-indice-clicavel)

#### `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.

[Voltar ao índice](#2-indice-clicavel)

#### `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.

[Voltar ao índice](#2-indice-clicavel)

#### `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).

[Voltar ao índice](#2-indice-clicavel)

#### `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.

[Voltar ao índice](#2-indice-clicavel)

#### `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).

[Voltar ao índice](#2-indice-clicavel)

#### `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.

[Voltar ao índice](#2-indice-clicavel)

#### `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.

[Voltar ao índice](#2-indice-clicavel)

#### `POST /api/v1/plants/:id/restore`

Restaura uma usina da lixeira

**Acesso:** JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.

[Voltar ao índice](#2-indice-clicavel)

#### `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).

[Voltar ao índice](#2-indice-clicavel)

#### `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.

[Voltar ao índice](#2-indice-clicavel)

#### `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.

[Voltar ao índice](#2-indice-clicavel)

#### `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.

[Voltar ao índice](#2-indice-clicavel)

#### `GET /api/v1/plants/tags`

Lista as tags do tenant

**Acesso:** JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.

[Voltar ao índice](#2-indice-clicavel)

#### `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).

[Voltar ao índice](#2-indice-clicavel)

#### `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).

[Voltar ao índice](#2-indice-clicavel)

#### `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).

[Voltar ao índice](#2-indice-clicavel)

#### `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).

[Voltar ao índice](#2-indice-clicavel)

#### `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).

[Voltar ao índice](#2-indice-clicavel)

#### `GET /api/v1/plants/monitoring-plans`

Planos de monitoramento do tenant

**Acesso:** JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.

[Voltar ao índice](#2-indice-clicavel)

#### `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).

[Voltar ao índice](#2-indice-clicavel)

#### `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).

[Voltar ao índice](#2-indice-clicavel)

#### `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).

[Voltar ao índice](#2-indice-clicavel)

#### `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).

[Voltar ao índice](#2-indice-clicavel)

#### `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).

[Voltar ao índice](#2-indice-clicavel)

#### `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).

[Voltar ao índice](#2-indice-clicavel)

#### `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).

[Voltar ao índice](#2-indice-clicavel)

#### `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).

[Voltar ao índice](#2-indice-clicavel)

#### `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.

[Voltar ao índice](#2-indice-clicavel)

#### `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.

[Voltar ao índice](#2-indice-clicavel)

#### `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.

[Voltar ao índice](#2-indice-clicavel)

#### `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.

[Voltar ao índice](#2-indice-clicavel)

#### `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']).

[Voltar ao índice](#2-indice-clicavel)

#### `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.

[Voltar ao índice](#2-indice-clicavel)

#### `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).

[Voltar ao índice](#2-indice-clicavel)

#### `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']).

[Voltar ao índice](#2-indice-clicavel)

#### `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).

[Voltar ao índice](#2-indice-clicavel)

#### `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.

[Voltar ao índice](#2-indice-clicavel)

#### `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.

[Voltar ao índice](#2-indice-clicavel)

#### `PATCH /api/v1/plants/:id/strings/:stringId`

Atualiza uma string/MPPT

**Acesso:** JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.

[Voltar ao índice](#2-indice-clicavel)

#### `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.

[Voltar ao índice](#2-indice-clicavel)

#### `DELETE /api/v1/plants/:id/strings/:stringId`

Remove uma string/MPPT

**Acesso:** JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.

[Voltar ao índice](#2-indice-clicavel)

#### `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.

[Voltar ao índice](#2-indice-clicavel)

#### `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.

[Voltar ao índice](#2-indice-clicavel)

#### `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.

[Voltar ao índice](#2-indice-clicavel)

#### `GET /api/v1/plants/:plantId/energy-bills/analysis`

**Acesso:** JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.

[Voltar ao índice](#2-indice-clicavel)

#### `POST /api/v1/plants/:plantId/energy-bills/grupo-a/leitura`

**Acesso:** JWT do ecossistema; acesso e tenant conferidos pelo guard da operação.

[Voltar ao índice](#2-indice-clicavel)

#### `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.

[Voltar ao índice](#2-indice-clicavel)

#### `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.

[Voltar ao índice](#2-indice-clicavel)

#### `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.

[Voltar ao índice](#2-indice-clicavel)

#### `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.

[Voltar ao índice](#2-indice-clicavel)

#### `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.

[Voltar ao índice](#2-indice-clicavel)

#### `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.

[Voltar ao índice](#2-indice-clicavel)

### 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.

[Voltar ao índice](#2-indice-clicavel)

#### `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).

[Voltar ao índice](#2-indice-clicavel)

#### `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).

[Voltar ao índice](#2-indice-clicavel)

#### `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.

[Voltar ao índice](#2-indice-clicavel)

#### `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.

[Voltar ao índice](#2-indice-clicavel)

#### `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.

[Voltar ao índice](#2-indice-clicavel)

#### `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.

[Voltar ao índice](#2-indice-clicavel)

#### `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.

[Voltar ao índice](#2-indice-clicavel)

#### `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.

[Voltar ao índice](#2-indice-clicavel)

#### `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.

[Voltar ao índice](#2-indice-clicavel)

#### `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.

[Voltar ao índice](#2-indice-clicavel)

#### `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.

[Voltar ao índice](#2-indice-clicavel)

#### `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.

[Voltar ao índice](#2-indice-clicavel)

#### `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.

[Voltar ao índice](#2-indice-clicavel)

#### `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.

[Voltar ao índice](#2-indice-clicavel)

#### `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.

[Voltar ao índice](#2-indice-clicavel)

#### `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.

[Voltar ao índice](#2-indice-clicavel)

### 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).

[Voltar ao índice](#2-indice-clicavel)

#### `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).

[Voltar ao índice](#2-indice-clicavel)

#### `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).

[Voltar ao índice](#2-indice-clicavel)

#### `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).

[Voltar ao índice](#2-indice-clicavel)

#### `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).

[Voltar ao índice](#2-indice-clicavel)

#### `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).

[Voltar ao índice](#2-indice-clicavel)

#### `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).

[Voltar ao índice](#2-indice-clicavel)

### 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).

[Voltar ao índice](#2-indice-clicavel)

#### `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).

[Voltar ao índice](#2-indice-clicavel)

#### `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).

[Voltar ao índice](#2-indice-clicavel)

#### `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).

[Voltar ao índice](#2-indice-clicavel)

#### `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).

[Voltar ao índice](#2-indice-clicavel)

#### `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).

[Voltar ao índice](#2-indice-clicavel)

#### `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).

[Voltar ao índice](#2-indice-clicavel)

#### `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).

[Voltar ao índice](#2-indice-clicavel)

#### `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).

[Voltar ao índice](#2-indice-clicavel)

#### `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).

[Voltar ao índice](#2-indice-clicavel)

#### `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).

[Voltar ao índice](#2-indice-clicavel)

#### `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).

[Voltar ao índice](#2-indice-clicavel)

#### `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).

[Voltar ao índice](#2-indice-clicavel)

#### `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.

[Voltar ao índice](#2-indice-clicavel)

#### `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.

[Voltar ao índice](#2-indice-clicavel)

#### `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.

[Voltar ao índice](#2-indice-clicavel)

#### `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.

[Voltar ao índice](#2-indice-clicavel)

#### `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.

[Voltar ao índice](#2-indice-clicavel)

#### `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.

[Voltar ao índice](#2-indice-clicavel)

#### `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.

[Voltar ao índice](#2-indice-clicavel)

#### `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.

[Voltar ao índice](#2-indice-clicavel)

#### `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.

[Voltar ao índice](#2-indice-clicavel)

#### `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.

[Voltar ao índice](#2-indice-clicavel)

#### `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.

[Voltar ao índice](#2-indice-clicavel)

#### `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.

[Voltar ao índice](#2-indice-clicavel)

### 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.

[Voltar ao índice](#2-indice-clicavel)

#### `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.

[Voltar ao índice](#2-indice-clicavel)

#### `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.

[Voltar ao índice](#2-indice-clicavel)


<!-- groner-suporte:veja-tambem:inicio -->
## Veja também

* [Guia principal, autenticação e coleção Postman](https://ajuda.groner.app/pt-br/article/documentacao-da-api-groner-crm-vz2bq2/)
* [Como gerar token de API](https://ajuda.groner.app/pt-br/article/como-gerar-um-token-de-api-para-integrar-o-groner-com-outros-sistemas-2okhj6/)
* [Limites de requisições](https://ajuda.groner.app/pt-br/article/limites-de-requisicoes-da-api-da-groner-1cwtj65/)
<!-- groner-suporte:veja-tambem:fim -->