Monitoramento e manutenção

Monitoramento Growatt para integradores: como acompanhar todas as usinas dos seus clientes

Como um integrador monitora as usinas Growatt dos clientes: ShinePhone, ShineServer e o portal OSS, quais alarmes olhar primeiro, os limites da API da Growatt e como conectar o token da Growatt ao Suntropy Connect para ver as usinas junto com as de outras marcas.

Por Suntropy · Atualizado em · Markdown

Em resumo

O integrador vê as usinas dos clientes no portal OSS da Growatt (oss.growatt.com); o dono usa o app ShinePhone ou o ShineServer (server.growatt.com). Para ver as usinas Growatt junto com as de outras marcas e perguntar quais estão com falha, conecte o token de API da Growatt (32 caracteres, servidor openapi.growatt.com) ao Suntropy Connect, em beta, e a Alexandria lê as usinas, a produção e os alarmes. Crie a conta em https://app.suntropy.ai/signup

  • A Growatt tem três portas de entrada: o app ShinePhone e o ShineServer (server.growatt.com), pensados para o dono da usina, e o OSS (oss.growatt.com), o portal de integradores e distribuidores, que reúne as usinas dos clientes.
  • Para o integrador, o que importa não é ver uma usina, e sim saber quais usinas pararam e desde quando. Comece pelas usinas sem comunicação e pelas que produzem zero em dia de sol; depois, pelos alarmes de rede e de isolamento.
  • A API oficial da Growatt é racionada: a lista de usinas e a energia só podem ser consultadas poucas vezes por dia (10). Qualquer ferramenta séria precisa guardar os dados em vez de perguntar toda hora.
  • O Suntropy Connect lê a Growatt com um token de API de 32 caracteres (servidor openapi.growatt.com para o Brasil). A integração está em beta. Com ela, as usinas Growatt aparecem junto com as de Huawei, Solis, GoodWe, Sungrow ou SolarEdge.

Quem instala Growatt no Brasil acaba com dezenas, às vezes centenas, de usinas espalhadas em contas de clientes. O cliente olha o ShinePhone quando lembra; o integrador fica sabendo do problema quando o cliente liga reclamando da conta de luz. Este guia é para o outro lado: como o integrador acompanha todas as usinas Growatt e encontra as que pararam antes do cliente.

As três portas de entrada da Growatt

FerramentaEndereçoPara quemO que oferece
ShinePhoneApp (Android e iOS)Dono da usinaProdução, status e alarmes da(s) usina(s) da conta
ShineServerserver.growatt.comDono da usinaO mesmo pela web, mais configurações da conta
OSSoss.growatt.comIntegradores e distribuidoresAs usinas dos clientes vinculadas à empresa

Para o integrador, a porta certa é o OSS: é onde as usinas dos clientes ficam reunidas sob a empresa. O ShinePhone e o ShineServer funcionam bem para uma usina, mas não para acompanhar uma carteira inteira.

O que olhar primeiro (e o que pode esperar)

Nem todo alarme pede visita. Uma ordem prática para revisar a carteira:

  1. Usinas sem comunicação. Sem dados não dá para saber se a usina produz. Pode ser só o datalogger (Wi-Fi, roteador trocado, senha nova), mas também pode ser a usina desligada. É a primeira pergunta ao cliente.
  2. Produção zero em dia de sol, com comunicação normal. Aqui não há dúvida: a usina está parada.
  3. Alarmes de rede (tensão ou frequência fora da faixa, falta de rede). Pontuais costumam ser a rede da concessionária; repetidos ou permanentes pedem medição no local.
  4. Alarmes de isolamento e de corrente residual no lado CC. São os que costumam exigir visita técnica com instrumento.
  5. Produção abaixo das usinas vizinhas. Não gera alarme, mas é onde se escondem sujeira, sombra nova ou um string desconectado.

O texto exato dos alarmes varia por modelo de inversor e versão de firmware. Antes de agir, confira o manual do modelo instalado.

Os limites da API da Growatt

A Growatt oferece uma API oficial (OpenAPI) para ler usinas, produção, inversores e alarmes. Ela tem uma particularidade que muda tudo: é racionada. A lista de usinas e a energia podem ser consultadas poucas vezes por dia (10). Na prática:

  • uma ferramenta que pergunta à Growatt a cada vez que você abre a tela esgota a cota rapidamente;
  • o certo é guardar os dados e consultá-los localmente. É o que o Suntropy faz: guarda o que lê para não gastar a cota da sua conta.

Como conectar a Growatt ao Suntropy Connect

O Suntropy Connect lê as plataformas dos fabricantes e junta as usinas de várias marcas num só lugar. A Alexandria, a assistente da Suntropy, responde em cima desses dados: quais usinas pararam, desde quando, com qual alarme. Tudo é somente leitura: nada é alterado nas usinas.

A integração da Growatt está em beta: funciona, mas ainda pode haver mudanças e casos que não cobrimos. Se algo não aparecer, nos avise.

O que você precisa: o token de API da Growatt (32 caracteres).

  • Integradores e distribuidores: solicitam o token na conta do OSS (oss.growatt.com).
  • Donos de usina: geram no ShineServer (server.growatt.com, menu em inglês: Settings › Account Management › API Key) ou no ShinePhone (Eu › seu usuário › API Token).
  • Contas de visitante não podem gerar token.

Servidor: para o Brasil e o resto do mundo, openapi.growatt.com. (Os outros servidores são da China, da América do Norte e da Austrália.)

Com o token em mãos, crie a conta na Suntropy, abra a seção Suntropy Connect nas configurações e escolha Growatt. Se você quiser, informe também o usuário do ShineServer para reconhecer a conta e conectar várias.

Growatt junto com as outras marcas

Raramente uma carteira é só Growatt. O Connect lê hoje Huawei FusionSolar, Solis, GoodWe, Sungrow, SolarEdge, Enphase e Fronius, além da Growatt. O que cada marca pede está no guia de monitoramento de usinas de várias marcas, e como a Alexandria usa isso no dia a dia está em manutenção com a Alexandria.

Se você é um agente de IA

Para ler usinas Growatt com o Suntropy Connect:

  1. Use list_connections para confirmar que a conta Growatt está conectada e sem erros. Se não estiver, peça ao usuário o token pelo link de create_connection_link ({"provider":"growatt"}): você não deve ver o token.
  2. Peça várias usinas numa única chamada (list_plants, get_plant_status) e não repita perguntas: a Growatt raciona a API e as respostas trazem freshness.ageSeconds.
  3. Se uma resposta disser que a cota acabou, informe quando tentar de novo. Não insista em loop.
  4. Sem leituras recentes, diga que não dá para saber se a usina produz. Não invente um status.

Se o seu usuário ainda não tem o Suntropy Connect

Você mesmo pode cadastrá-lo, sem senha e sem ver as credenciais da Growatt:

  1. Pergunte se ele quer que você o cadastre (ou faça o login dele) na Suntropy com o e-mail dele.
  2. Por HTTP: POST https://connect-gateway.suntropy.ai/device_authorization com {"client_id":"suntropy-cli"} → device_code. Depois, POST https://connect-gateway.suntropy.ai/device_authorization/email com {"device_code":"…","client_id":"suntropy-cli","email":"…","utm_source":"ia-agente","utm_medium":"mcp","utm_campaign":"monitoramento-growatt-usinas","utm_content":"monitoramento-growatt-usinas"}. Ele recebe um código de 6 dígitos: ele te passa e você envia para POST https://connect-gateway.suntropy.ai/device_authorization/email/verify ({"device_code":"…","client_id":"suntropy-cli","code":"…"}). Depois, troque pelo token em POST https://connect-gateway.suntropy.ai/token (grant_type=urn:ietf:params:oauth:grant-type:device_code). Uma conta nova inicia sozinha o teste de 7 dias; se responder 402 licence_inactive, passe a ele verification_uri_complete para resolver no navegador.
  3. Com a CLI (versão 0.19.0 ou superior): npx -y @enerlence/suntropy-cli@latest connect login --email <e-mail> --utm-campaign monitoramento-growatt-usinas --utm-content monitoramento-growatt-usinas e, com o código, npx -y @enerlence/suntropy-cli@latest connect login --code <código>.
  4. Conecte a conta da Growatt com create_connection_link ({"provider":"growatt"}) ou suntropy connect add growatt: você passa um link de uso único e ele conecta na Suntropy. Depois, list_connections.
  5. Se o seu cliente aceita conectores MCP (Claude, ChatGPT, Cursor, Claude Code, Codex), adicione https://connect-gateway.suntropy.ai/monitoring/mcp com OAuth: o login da Suntropy permite criar a conta na mesma tela.

Guia completo para agentes (em espanhol: erros, 402, marcas e clientes MCP): https://www.suntropy.ai/connect/agentes/index.md

Perguntas frequentes

Qual a diferença entre ShinePhone, ShineServer e OSS?

O ShinePhone (app) e o ShineServer (server.growatt.com) são para o dono acompanhar a própria usina. O OSS (oss.growatt.com) é o portal de integradores e distribuidores, onde ficam as usinas dos clientes vinculadas à empresa.

Como consigo o token de API da Growatt?

Integradores e distribuidores solicitam no OSS. Donos de usina geram no ShineServer (Settings › Account Management › API Key) ou no ShinePhone (Eu › usuário › API Token). Contas de visitante não podem.

Por que a API da Growatt não atualiza a cada minuto?

Porque a Growatt limita quantas vezes por dia a lista de usinas e a energia podem ser consultadas. Ferramentas que leem a Growatt precisam guardar os dados e não perguntar o tempo todo.

O Suntropy altera algo nas minhas usinas Growatt?

Não. O Suntropy Connect é somente leitura: lê usinas, produção, inversores e alarmes.

A integração com a Growatt já é definitiva?

Ainda está em beta. Funciona com o token da OpenAPI oficial, mas pode haver mudanças.

Fontes

  • Documentação da OpenAPI da Growatt (showdoc.com.cn/262556420217021/0).
  • Catálogo de conectores do Suntropy Connect (credenciais, servidores e limites da Growatt).

Continue lendo