PT EN

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"

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),
}));

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"

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
}

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"}'

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#