# Integração com a fechadura TTLock / PADO

A fechadura **PADO** é um "whitelabel" do **TTLock** — por baixo é o mesmo sistema.
O Nexus conversa com a **API aberta oficial do TTLock** (documentada, não é gambiarra)
para: ver o estado da fechadura, **destrancar**, criar/apagar **senhas** e receber os
**registros** (quem abriu, quando, com quê) em tempo real por um **webhook**.

> Termos rápidos:
> - **App developer** = sua conta de desenvolvedor no site do TTLock (open.ttlock.com).
> - **Gateway (Hub)** = o aparelhinho da PADO ligado na tomada que dá internet para a
>   fechadura. Sem ele online, o "destrancar pela internet" não funciona.
> - **callback_url / webhook** = um endereço do SEU servidor onde a nuvem TTLock avisa,
>   na hora, cada vez que a fechadura é usada.

---

## Passo 1 — Preencher o "callback URL" no console (é o que você está fazendo agora)

Esse campo é um **webhook**: a nuvem TTLock vai fazer um POST no seu servidor a cada
operação da fechadura. **Precisa ser HTTPS público, com certificado válido, e responder 200.**
O Nexus já tem o receptor pronto (`/ttlock`).

1. No console (**https://open.ttlock.com/manager** → sua aplicação → editar), no campo
   **Callback URL** cole:

   ```
   https://flnghahnomada.myddns.me/ttlock
   ```

   (troque `flnghahnomada.myddns.me` pelo domínio público do seu servidor, se for outro.)
2. Salve.

**✅ Deu certo se:** salvou sem erro. Para testar de fora, abra no navegador
`https://flnghahnomada.myddns.me/ttlock` — deve aparecer só **`OK`** (é o receptor
respondendo 200).

**Deu problema?**
- "URL inválida / não acessível": o domínio precisa estar **no ar por HTTPS** (o
  Let's Encrypt que configuramos) e acessível da internet (porta 443 liberada). Certificado
  **auto-assinado NÃO funciona** com a TTLock.
- Abriu e não apareceu "OK": confirme que copiou a pasta `public/` e o `.htaccess` novos, e
  que o Apache está no ar.

---

## Passo 2 — Pegar as credenciais e ligar no `.env`

No console do TTLock você tem: **Client ID** e **Client Secret** (da aplicação). E você usa
a conta do **app da PADO** (o e-mail/telefone e a senha com que você entra no app da
fechadura no celular).

No `C:\wamp64\www\Nexus\api\.env`, preencha:

```
TTLOCK_ENABLED=true
TTLOCK_CLIENT_ID=coloque_o_client_id
TTLOCK_CLIENT_SECRET=coloque_o_client_secret
TTLOCK_USERNAME=sua_conta_do_app_pado
TTLOCK_PASSWORD=sua_senha_do_app_pado
```

> A senha vai em **texto** — o Nexus aplica o MD5 sozinho (a TTLock exige o MD5). Se você
> só tem o hash, ponha o hash e adicione `TTLOCK_PASSWORD_IS_MD5=true`.

**✅ Deu certo se:** salvou o `.env`. (Ainda não testamos — é o próximo passo.)

---

## Passo 3 — Validar que a conta PADO funciona na API aberta

Como a PADO é whitelabel, precisamos confirmar que a conta dela funciona no cloud padrão
do TTLock. Rode no servidor:

```
"C:\wamp64\bin\php\php8.3.14\php.exe" "C:\wamp64\www\Nexus\api\scripts\ttlock_test.php"
```

**✅ Deu certo se:** aparecer "Login OK" e a **lista das suas fechaduras** (com o `lockId`).

**Deu problema?**
- "Falha no login" / `errcode` de credencial: confira usuário/senha do **app** (não é a
  conta de desenvolvedor). Se persistir, a conta PADO pode estar num cloud diferente —
  tente trocar no `.env`: `TTLOCK_BASE_URL=https://api.ttlock.com` e rode de novo.
- "SSL certificate problem": falta o `cacert.pem` no `php.ini` do CLI (veja
  `deploy/INSTALACAO-*` / rode o `diag_https.bat`).

---

## Passo 4 — Testar o webhook (registros em tempo real)

Com o callback salvo (Passo 1) e o módulo ligado:

1. Destranque a fechadura (pelo app, senha ou digital).
2. Em segundos, o Nexus recebe o registro e grava em `ttlock_evento`.

**✅ Deu certo se:** aparecerem linhas na tabela `ttlock_evento` (ou na futura tela
`/fechadura`). O parser é testável sem banco:

```
"C:\wamp64\bin\php\php8.3.14\php.exe" "C:\wamp64\www\Nexus\api\scripts\tests_ttlock.php"
```

deve imprimir **TUDO OK**.

---

## Passo 5 — Usar a fechadura no Nexus

Com o módulo ligado e a conta validada, abra no menu **Automação → Fechadura** (ou
`https://SEU-DOMINIO/fechadura`). Você verá:

- O **estado ao vivo** (Trancada / Destrancada), a **bateria** e se o **gateway está online**.
- Botões **Destrancar** e **Trancar** (pedem confirmação; exigem o gateway online).
- Em **Registros e senhas** (clicando na fechadura): o histórico de aberturas (por app, senha,
  digital) e o cadastro de **senhas de acesso** (permanente, de uso único ou por período) — a
  TTLock gera o código e ele aparece na lista para você repassar a quem precisar.

Quem enxerga o quê:
- **Dono e morador**: veem o estado e podem **destrancar/trancar**.
- **Só o dono**: cria e apaga **senhas**.

**✅ Deu certo se:** a página mostra a fechadura "Porta de Entrada" com o estado e a bateria, e o
botão **Destrancar** abre a porta (com o gateway online).

---

## Como funciona por dentro (para quem for mexer no código)

- **`App\Ttlock\TtlockClient`** — fala com a API (token/fechaduras/estado/destrancar/senhas/
  registros/gateways). Auth OAuth2 password grant; toda chamada leva `clientId`+`accessToken`+
  `date` (ms). A API responde **200 mesmo em erro** → sempre conferir `errcode` (0 = ok).
- **`public/ttlock.php`** — recebe o webhook (POST form-urlencoded), passa pelo parser PURO
  `App\Ttlock\TtlockWebhook::parse()`, grava em `ttlock_evento` e **responde 200 sempre**.
- **Módulo `ttlock`** no kill-switch (`/modulos`): desligado, o receptor aceita e ignora, e o
  cliente não é usado — nada quebra.
- **Destrancar pela internet exige o Gateway (Hub) online.** Sem ele, o Nexus consegue ler
  estado/registros (via nuvem), mas o comando de abrir pode não chegar à fechadura.