# Guia do eWeLink / Sonoff (OAuth) — passo a passo bem fácil

Este guia liga os dispositivos **eWeLink / Sonoff** (tomadas, interruptores, relés) ao
Nexus, para você ligar/desligar e ver o estado deles pela tela de **Automação**.

O Nexus conversa com a **nuvem da eWeLink** usando **OAuth** — o jeito oficial e
seguro. Em vez de guardar a sua senha, o sistema te leva UMA vez à página da eWeLink,
você autoriza o acesso, e a eWeLink devolve uma "chave de acesso" (token) que o sistema
renova sozinho daí em diante.

Você vai precisar de duas coisas, uma vez só:

1. um **App** criado no console de desenvolvedor da eWeLink (de graça) — dá o `App ID`
   e o `App Secret`;
2. autorizar a sua conta clicando em **Conectar** dentro do Nexus.

---

## Antes de começar

- Você precisa de uma **conta eWeLink** (a mesma do app no celular), com os
  dispositivos já pareados e funcionando.
- O Nexus precisa estar acessível por **https** (a eWeLink exige https no
  redirecionamento). Em produção já é. Se você está testando em `http://` local, veja a
  observação no fim do **Passo 4**.

---

## Passo 1 — Criar o App no console da eWeLink

Você já está na tela **Create App** (em <https://dev.ewelink.cc> → Console → Create).
Preencha assim:

| Campo | O que colocar |
|---|---|
| **App Name** | Um nome curto. O texto cinza diz "nome em chinês", mas **pode ser em português/inglês**. Ex.: `Nexus Condominio` |
| **App Profile** | Uma descrição curta. Ex.: `Integracao de automacao do condominio (Sonoff)` |
| **App Type** | Deixe **OAuth2.0** (vem travado). |
| **App Role** | Deixe **Standard Role** (vem travado). |
| **Redirect URL** | **Muito importante — agora usamos de verdade.** Cole a URL que o Nexus mostra na tela do canal (Passo 3). Ela é `https://SEU-ENDERECO/automation/ewelink/callback`. |

> ⚠ A conta de desenvolvedor pessoal pode levar **1–2 dias úteis** para ser aprovada.
> Enquanto não aprovar, o App não funciona.

Clique em **OK**.

✅ **Deu certo se:** o App aparece na lista e, ao abrir, mostra **App ID** e **App
Secret**.

---

## Passo 2 — Copiar App ID e App Secret

Abra o App recém-criado e copie os dois valores (guarde num lugar seguro — o **App
Secret** é uma senha):

- **App ID** (às vezes *App Key* / *Client ID*)
- **App Secret** (às vezes *Client Secret*)

---

## Passo 3 — Cadastrar o canal no Nexus

1. No menu, vá em **Automação → Canais** (ou abra `/automation/accounts`).
2. Clique em **Novo canal**.
3. Em **Provedor**, escolha **eWeLink**.
4. Preencha o JSON (o formulário já vem com o modelo certo — agora **sem e-mail e sem
   senha**):

   | Campo | O que colocar |
   |---|---|
   | `region` | **`us`** (as contas do Brasil ficam no servidor das Américas). Se não conectar, tente `eu`. |
   | `app_id` | o **App ID** do Passo 2 |
   | `app_secret` | o **App Secret** do Passo 2 |

5. **Salvar**.

✅ **Deu certo se:** o canal aparece na lista com a etiqueta **"Não conectado"** (amarela)
— falta só autorizar (Passo 4). Abra **Editar** no canal: ali aparece a **URL de
redirecionamento** para você cadastrar no Passo 1 (se ainda não fez) e o botão
**Conectar**.

---

## Passo 4 — Conectar (autorizar a sua conta)

1. Confirme que a **Redirect URL** do App (Passo 1) é **idêntica** à mostrada na tela do
   canal (botão **Copiar** ao lado dela). Se você criou o App com outra URL, edite o App
   na eWeLink e corrija.
2. No canal (lista de Canais **ou** dentro de **Editar**), clique em **Conectar**.
3. Você vai para o site da eWeLink. **Entre com a sua conta eWeLink** (e-mail/senha do
   app do celular) e **autorize** o acesso.
4. A eWeLink te traz de volta ao Nexus automaticamente.

✅ **Deu certo se:** o canal passa a mostrar **"Conectado"** (verde).

> **Testando em `http://` local?** A eWeLink só aceita `https` na Redirect URL. Cadastre
> a URL com `https://` mesmo, e **no momento em que a eWeLink te redirecionar de volta**,
> troque na barra do navegador `https` por `http` (você tem ~30 s). Em produção, com
> https de verdade, isso não é necessário.

---

## Passo 5 — Puxar os dispositivos do canal

Jeito mais fácil (recomendado):

1. Vá em **Automação → Canais**.
2. No seu canal, clique em **🔍 Dispositivos** — o sistema lista tudo que está na sua
   conta na nuvem (online/offline).
3. Em cada aparelho, clique em **+ Adicionar** — abre o cadastro **já preenchido**
   (driver, canal e `device_id`). Aparelho com **vários canais** mostra um "+ canal 1",
   "+ canal 2"… (um dispositivo por canal).
4. Escolha o **cômodo**, ajuste o **nome** se quiser e **Salvar**.

> Também dá para fazer pelo caminho antigo: **Automação → Dispositivos → Novo**, escolher
> **Driver** eWeLink + **Canal**, e usar o **Buscar do canal ▾** ao lado do JSON.

✅ **Deu certo se:** o dispositivo aparece no painel de **Automação** e o botão
liga/desliga responde. Para **gerenciar** (editar/excluir) depois: **Automação →
Dispositivos**.

---

## Deu problema?

Primeiro, **olhe o log**: **Sistema → Diagnóstico → Log de integrações** (filtro
`eWeLink`). É lá que aparece o motivo real de uma falha (status HTTP, mensagem da
eWeLink) — sem expor tokens nem senhas.

- **Botão "Conectar" some / diz "Falta configurar".** Você ainda não salvou o `app_id`
  e o `app_secret`. Faça o Passo 3 primeiro.
- **"o código de segurança não confere" ao voltar da eWeLink.** A autorização demorou
  demais ou a sessão expirou. Clique em **Conectar** de novo (é rápido).
- **A eWeLink reclama da Redirect URL.** Ela tem que ser **idêntica** (incluindo
  `https://`, sem barra a mais no fim) à cadastrada no App. Use o botão **Copiar** da
  tela do canal.
- **Conectou mas "Buscar do canal" não traz nada.** A conta não tem dispositivos naquela
  **região** — troque `us` ↔ `eu` no canal, salve e conecte de novo.
- **Depois de um tempo parou de funcionar.** O token de acesso renova sozinho pelo
  *refresh token* (válido ~2 meses). Se ficar MUITO tempo sem uso, o refresh expira:
  basta clicar em **Reconectar**. O log de integrações avisa quando o refresh falha.
- **Troquei o App (app_id/app_secret).** Ao salvar com um App diferente, o sistema
  **descarta os tokens antigos** (eles não valem para o novo App) e o canal volta a
  "Não conectado" — clique em **Reconectar**.

---

## É seguro?

- O Nexus **não guarda a sua senha da eWeLink** — só o App ID/Secret e os *tokens*
  OAuth (que renovam sozinhos e podem ser revogados na sua conta eWeLink).
- Os tokens são tratados como segredo: **nunca** aparecem na tela nem no log.
- O sistema **só lê estado e liga/desliga** o que você cadastrar — não mexe em mais nada
  da sua conta.