# Construir uma app para moradores

Inicie sessão de moradores com OAuth 2.0 e PKCE, mostre as contas e facturas a que cada um tem acesso pela Consumer API e abra um pagamento por M-Pesa.


## O que vai construir

Uma aplicação web ou móvel em que o morador entra com a sua própria conta, vê as contas de serviço a que está ligado, consulta as facturas e paga uma delas. A app nunca guarda chaves de API: obtém um token de acesso em nome do morador pelo fluxo Authorization Code com PKCE (`S256`) e chama a Consumer API (`$CONSUMER_API`) com esse token. Cada resposta contém apenas o que pertence a esse morador.

O exemplo `examples/resident-pkce` faz os passos 1 a 4 numa página HTML estática, sem build.

## Pré-requisitos

- Uma sandbox e um utilizador morador com pelo menos uma conta de serviço ligada (o evento `account.linked` assinala quando um morador ganha acesso a uma conta).
- Um cliente OAuth registado pelo operador do servidor em `security.oauth.clients`, com `kind` `mobile` (ou `desktop`) e os `redirect_uris` da sua app:

```yaml
security:
  oauth:
    clients:
      - id: app-moradores
        name: App de moradores
        kind: mobile
        redirect_uris:
          - http://localhost:3000/callback
```

O endpoint de token só aceita clientes públicos (`token_endpoint_auth_methods_supported` é `none`), por isso não há segredo de cliente: o PKCE é que prova que quem troca o código é quem o pediu.

## 1. Ler a configuração do servidor de autorização

```bash
curl -sS "https://api.gota.umbeluzi.com/.well-known/oauth-authorization-server"
```

✓ Checkpoint: a resposta traz `authorization_endpoint`, `token_endpoint` e `"code_challenge_methods_supported": ["S256"]`. Leia os endereços daqui em vez de os fixar no código.

## 2. Enviar o morador para o ecrã de entrada

Gere um `code_verifier` aleatório, guarde-o na sessão do navegador e envie só o seu hash no pedido de autorização. As funções vêm de `examples/resident-pkce/pkce.js`.

```javascript
import { generateCodeVerifier, generateCodeChallenge, buildAuthorizeURL } from "./pkce.js";

const verifier = generateCodeVerifier();
sessionStorage.setItem("pkce_verifier", verifier);
const state = crypto.randomUUID();
sessionStorage.setItem("pkce_state", state);

window.location.assign(buildAuthorizeURL({
  authorizationEndpoint: discovery.authorization_endpoint,
  clientId: "app-moradores",
  redirectUri: "http://localhost:3000/callback",
  scope: "openid profile offline_access",
  state,
  codeChallenge: await generateCodeChallenge(verifier),
}));
```

✓ Checkpoint: depois de entrar, o navegador volta ao `redirect_uri` com `code` e `state` na query string; confirme que o `state` é igual ao que guardou.

## 3. Trocar o código por tokens

```bash
curl -sS -X POST "https://api.gota.umbeluzi.com/oauth/token" \
  -d grant_type=authorization_code \
  -d client_id=app-moradores \
  -d redirect_uri=http://localhost:3000/callback \
  -d code="$AUTH_CODE" \
  -d code_verifier="$CODE_VERIFIER"
```

✓ Checkpoint: a resposta tem `access_token`, `"token_type": "Bearer"`, `expires_in` (900 segundos por omissão, ajustável pelo operador em `security.token_ttl`), `refresh_token`, `id_token` e o objecto `user`. Quando o acesso expira, peça outro com `grant_type=refresh_token`; cada renovação devolve um `refresh_token` novo e o anterior deixa de servir (`invalid_grant`).

## 4. Mostrar as contas do morador

```bash
curl -sS "$CONSUMER_API/accounts" \
  -H "Authorization: Bearer $CONSUMER_ACCESS_TOKEN"
```

Resposta, resumida:

```json
{
  "data": [
    {
      "id": "act_3eQrF3JmTj2ZXpkFlbdO36UPXGP",
      "tenant_id": "ten_3HclVhrn01Vsbj8CEBWAUk6h4MV",
      "customer_id": "cus_3Byj2A4oNoD4aVDMGLeWCWY5CWP",
      "property_id": "prp_35XwcW0AgJucy3jX5j2mk9J1XgP",
      "property_address": "Rua da Resistência 1187, Bairro Central",
      "account_number": "CTA-000044",
      "billing_entity_id": "ten_3HclVhrn01Vsbj8CEBWAUk6h4MV",
      "status": "active",
      "permissions": ["account.read", "invoice.read", "payment.create", "reading.create"]
    }
  ],
  "has_more": false
}
```

✓ Checkpoint: só aparecem contas com uma ligação activa a este morador, de todas as empresas. Use `permissions` para decidir que botões mostrar: sem `payment.create` não ofereça o pagamento, sem `reading.create` esconda o envio de leitura.

## 5. Listar facturas e abrir um pagamento

```bash
curl -sS "$CONSUMER_API/invoices?account_id=act_3eQrF3JmTj2ZXpkFlbdO36UPXGP" \
  -H "Authorization: Bearer $CONSUMER_ACCESS_TOKEN"

curl -sS -X POST "$CONSUMER_API/payment-sessions" \
  -H "Authorization: Bearer $CONSUMER_ACCESS_TOKEN" \
  -H "Idempotency-Key: 6f1d2c9a-3b47-4e1f-9a0c-5d8e7b2a4c61" \
  -H "Content-Type: application/json" \
  -d '{"invoice_id":"inv_3z9cS8ItYBqz0D66bvqNC7QSn8E","method":"mpesa","phone":"+258841234567"}'
```

✓ Checkpoint: a sessão volta com `id` começado por `pss_`, `"status": "pending"`, o `amount` igual ao saldo em dívida e um `next_action`. Para `mpesa`, `next_action.type` é `mobile_money_approval` e `instructions` diz ao morador o que aprovar no telemóvel; mostre esse texto tal como vem. O valor é calculado pelo servidor a partir da factura: a app não o envia.

## Testar

Consulte `GET $CONSUMER_API/payment-sessions/pss_3SUDQUDOqwxJDioVEQHBzy13wYD` até o `status` mudar. Na sandbox não há aprovação real: `POST $CONSUMER_API/payment-sessions/pss_3SUDQUDOqwxJDioVEQHBzy13wYD/sandbox/confirm` faz de fornecedor, regista o pagamento e o recibo e devolve a sessão `confirmed`. Do lado da empresa chega `payment.received` e, se o saldo ficou a zero, `invoice.paid`.

Uma factura sem saldo é recusada com `invoice.no_balance`, e enquanto os pagamentos da empresa não estiverem activos a resposta é `403` com `capability.inactive`.

## Próximos passos

- [Autenticação: chaves de API, OAuth e device grant](/docs/getting-started/authentication)
- [Receber pagamentos e confirmar por webhook](/docs/guides/receive-payments)
- [Paginação com limit, after e next_cursor](/docs/getting-started/pagination)
- [Referência completa da Consumer API](/docs/api/consumer)

