Contas Voneka

Integrar o Contas Voneka

Login e registo únicos para as apps Voneka. OAuth 2.0 (Authorization Code). Base: https://contas.get.co.mz

Começar em 5 minutos

  1. Peça um cliente OAuth à equipa Voneka (recebe client_id e client_secret).
  2. Registe a redirect URI exacta da sua app (ex.: https://sua-app.co.mz/callback).
  3. Configure as variáveis de ambiente abaixo.
  4. Redireccione o utilizador para /oauth/authorize (login) ou /register (criar conta).
  5. No callback, troque o code por access_token e chame GET /api/user.

Variáveis na sua aplicação

OAUTH_BASE_URI=https://contas.get.co.mz/
OAUTH_CLIENT_ID=seu-uuid-aqui
OAUTH_CLIENT_SECRET=seu-segredo-aqui
OAUTH_REDIRECT_URI=https://sua-app.co.mz/callback

Como funciona (visão geral)

  1. A sua app redirecciona o browser para o Contas.
  2. O utilizador entra ou cria conta no Contas.
  3. O Contas devolve um code para a sua redirect_uri.
  4. O seu backend troca o code por access_token (nunca no browser se tiver secret).
  5. Com o token, obtém o perfil em /api/user e cria/actualiza a sessão local.

Guarde o client_secret só no servidor. Use state aleatório e valide-o no callback (protecção CSRF).

Exemplos de código

Substitua CLIENT_ID, CLIENT_SECRET, REDIRECT_URI e BASE. Os snippets cobrem o fluxo completo: autorizar → trocar code → ler /api/user.

# 1) Abrir no browser (guarde state na sessão)
https://contas.get.co.mz/oauth/authorize?response_type=code&client_id=CLIENT_ID&redirect_uri=https%3A%2F%2Fsua-app.co.mz%2Fcallback&scope=&state=RANDOM

# 2) Trocar o code (no servidor)
curl -sS -X POST https://contas.get.co.mz/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "client_id=CLIENT_ID" \
  -d "client_secret=CLIENT_SECRET" \
  -d "redirect_uri=https://sua-app.co.mz/callback" \
  -d "code=CODE_DO_CALLBACK"

# 3) Perfil
curl -sS https://contas.get.co.mz/api/user \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Accept: application/json"

Criar conta a partir da sua app

Em vez do formulário local, envie o utilizador ao Contas. Cada cliente define quais campos extras são obrigatórios (telefone, morada, etc.).

URL de registo

https://contas.get.co.mz/register?client_id=CLIENT_ID&return_to=https%3A%2F%2Fsua-app.co.mz%2Fredirect

Ver campos exigidos (JSON público)

GET https://contas.get.co.mz/api/registration-schema?client_id=CLIENT_ID

return_to deve ser HTTPS no seu domínio (ex.: https://sua-app.co.mz/redirect). Após o registo, o Contas devolve o utilizador a esse URL.

Perfil do utilizador

Com Authorization: Bearer {access_token}:

GET https://contas.get.co.mz/api/user
Authorization: Bearer ACCESS_TOKEN
Accept: application/json

Resposta típica (campos podem ser null se o perfil da app não os pediu):

{
  "pessoa_id": 1,
  "id": 1,
  "name": "Agostinho Uanicela",
  "email": "user@exemplo.com",
  "telefone": "+25884xxxxxxx",
  "bairro": null,
  "distrito_id": null,
  "genero": null,
  "data_nascimento": null,
  "email_verified_at": "2026-08-04T00:00:00.000000Z"
}

SPA e mobile (PKCE)

Apps públicas (sem secret no cliente) usam PKCE: gere code_verifier e code_challenge (S256) no authorize; no token envie code_verifier em vez de client_secret.

Nunca embuta client_secret em apps móveis ou JavaScript público.

Referência rápida

Endpoint Para quê
GET https://contas.get.co.mz/oauth/authorize Iniciar login / consentimento
POST https://contas.get.co.mz/oauth/token Trocar code ou refresh por tokens
GET https://contas.get.co.mz/api/user Perfil do utilizador autenticado
GET https://contas.get.co.mz/register Formulário de registo Contas
GET https://contas.get.co.mz/api/registration-schema Schema de campos de registo
GET https://contas.get.co.mz/up Health check

Erros comuns

Precisa de um client_id? Contacte a equipa Voneka com a URL da app e a redirect_uri pretendida.