Sambung dengan SAPRO

Aliran sambungan

OAuth 2.0 authorization code (RFC 6749), dengan PKCE S256 (RFC 7636) yang disyorkan. Semua panggilan token dari pelayan anda: client_secret tidak boleh berada dalam app telefon atau pelayar.

1. Hantar pemilik ke SAPRO

GET https://sapro.my/oauth/authorize
    ?response_type=code
    &client_id=sapro_xxxxxxxxxxxxxxxxxxxxxxxx
    &redirect_uri=https://sekolah.contoh.my/sapro/callback
    &scope=accounts:read branches:read journals:write
    &state=RAWAK_DISIMPAN_DALAM_SESI
    &code_challenge=BASE64URL(SHA256(code_verifier))
    &code_challenge_method=S256

• redirect_uri mesti sama tepat dengan yang didaftarkan. Untuk sistem yang memberi setiap pelanggan subdomain sendiri, SAPRO boleh mendaftarkan https://*.contoh.my/sapro/callback (satu subdomain sahaja).
• state wajib. Semak ia sama apabila pemilik kembali, untuk menghalang CSRF.
• scope dipisahkan dengan ruang; kalau tiada, semua akses yang didaftarkan untuk aplikasi anda diminta.
• Tambah &ui_locales=en untuk skrin dalam Bahasa Inggeris.

2. Pemilik kembali ke sistem anda

https://sekolah.contoh.my/sapro/callback?code=KOD_SEKALI_GUNA&state=RAWAK_DISIMPAN_DALAM_SESI
https://sekolah.contoh.my/sapro/callback?error=access_denied&state=RAWAK_DISIMPAN_DALAM_SESI

Kod sah 10 minit dan hanya sekali. Ralat lain yang mungkin: invalid_scope, invalid_request, unsupported_response_type.

3. Tukar kod kepada token (dari pelayan)

curl -X POST https://sapro.my/oauth/token \
  -u "CLIENT_ID:CLIENT_SECRET" \
  -d grant_type=authorization_code \
  -d code=KOD_SEKALI_GUNA \
  -d redirect_uri=https://sekolah.contoh.my/sapro/callback \
  -d code_verifier=CODE_VERIFIER_ASAL

{
  "access_token": "12|q8mW...",
  "token_type": "Bearer",
  "scope": "accounts:read branches:read journals:write",
  "company": { "id": 42, "name": "Splash Swim Academy Sdn Bhd" },
  "api_base_url": "https://sapro.my/api/v1"
}

client_id dan client_secret juga boleh dihantar dalam badan borang. Simpan token secara encrypted. Ia tidak luput; ia berhenti apabila pemilik memutuskan sambungan (app SAPRO → Tetapan → Integrasi), apabila anda memulangkannya, atau apabila pemilik menyambung semula (token lama diganti).

4. Putuskan dari sistem anda

curl -X POST https://sapro.my/oauth/revoke -u "CLIENT_ID:CLIENT_SECRET" -d token=ACCESS_TOKEN

Skop (akses)

Pemilik melihat senarai ini dalam Bahasa Melayu sebelum menekan Benarkan. Minta yang perlu sahaja.

Token juga sentiasa boleh memanggil GET /me (pengguna dan syarikat yang bersambung).

API

Asas: https://sapro.my/api/v1. Hantar Authorization: Bearer TOKEN dan Accept: application/json. Jumlah wang dalam ringgit (2 tempat perpuluhan), tarikh YYYY-MM-DD.

Hantar jurnal

POST /api/v1/journals
X-Branch-Id: 7            (pilihan: cawangan dari GET /branches)

{
  "date": "2026-10-01",
  "reference_number": "KELASPRO 2026-10-01",
  "external_ref": "KP:s12:sales:2026-10-01:7",
  "remark": "Yuran diinvois hari ini",
  "lines": [
    { "account_id": 1201, "description": "Yuran diinvois", "debit": 1250.00 },
    { "account_id": 4101, "description": "Yuran kelas", "credit": 1250.00 }
  ]
}

Elak catatan berganda dengan external_ref (unik dalam syarikat, sehingga 120 aksara). Hantar semula rujukan yang sama menjawab 409 dengan jurnal sedia ada dalam data, jadi cuba semula selepas rangkaian terputus adalah selamat. Untuk membetulkan angka, cari dengan GET /journals?external_ref=... dan PUT.

Contoh (PHP, Laravel)

$sapro = Http::withToken($token)->acceptJson()->baseUrl('https://sapro.my/api/v1');

$accounts = $sapro->get('accounts')->json('data');
$response = $sapro->post('journals', $journal);

if ($response->status() === 409) {
    $existing = $response->json('data');   // sudah dihantar sebelum ini
}

Buka SAPRO dengan satu klik

Dengan skop login, sistem anda boleh meletakkan butang "Buka SAPRO" yang membawa pengguna terus masuk, tanpa kata laluan. Pelayan anda meminta pautan untuk e-mel pengguna yang menekan butang; SAPRO hanya memberi pautan jika e-mel itu milik pengguna syarikat yang bersambung (pemilik atau ahli pasukan). Pautan berfungsi sekali, dalam 2 minit. Buka pautan itu terus (redirect); jangan simpan.

POST /api/v1/integrations/login-links
{ "email": "pengguna@sekolah.my", "path": "/reports/profit-loss" }

201  { "data": { "url": "https://sapro.my/app/#/sso?code=...", "expires_at": "..." } }
404  { "code": "no_user" }          e-mel itu bukan pengguna syarikat ini
403  { "code": "integration_scope" } sambungan tanpa skop login: minta pemilik sambung semula

path ialah halaman dalam app SAPRO, contohnya /reports/profit-loss, /reports/sst-summary atau /journals/{id} (jurnal yang anda hantar).

Ralat

Mesej ralat dalam message mengikut bahasa Accept-Language (ms atau en).