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.linkedassinala quando um morador ganha acesso a uma conta). - Um cliente OAuth registado pelo operador do servidor em
security.oauth.clients, comkindmobile(oudesktop) e osredirect_urisda sua app:
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#
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.
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#
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#
curl -sS "$CONSUMER_API/accounts" \
-H "Authorization: Bearer $CONSUMER_ACCESS_TOKEN"
Resposta, resumida:
{
"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#
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.