api REST API v1

API Documentation

Dokumentasi lengkap untuk mengintegrasikan aplikasi Anda dengan SMAGE ID. API ini menyediakan akses data member yang terdaftar di sistem SSO.

Daftar Isi

1 Autentikasi

Setiap request ke API harus menyertakan API Key melalui HTTP header. API key didapatkan dari admin panel ScholarGate di menu Portal & API.

Header Tipe Keterangan
X-API-Key string Wajib. API key 64 karakter yang digenerate dari admin panel.

Verifikasi Domain

Selain API key, sistem juga memverifikasi domain pengirim request melalui header Origin atau Referer. Domain harus cocok dengan yang didaftarkan saat generate API key.

tips_and_updates
Tips: Untuk request server-to-server (backend), domain diambil dari IP pengirim. Gunakan domain * saat development untuk melewati pengecekan domain.

2 Base URL

BASE URL 
https://portal.smage.my.id/api/v1

3 Endpoints

GET /api/v1/test

Endpoint sederhana untuk mengetes koneksi API dan memastikan API key + verifikasi domain sudah benar. Cocok dipakai sebagai health-check oleh aplikasi pendukung.

Contoh Request

cURL 
curl -X GET "https://portal.smage.my.id/api/v1/test" \
  -H "X-API-Key: YOUR_API_KEY_HERE"

Contoh Response (200 OK)

JSON Response 
{
  "success": true,
  "data": {
    "status": "ok",
    "server_time": "2026-04-03T12:34:56+07:00"
  },
  "meta": {
    "app_name": "CBT Exam System",
    "request_domain": "app-pendukung.sch.id",
    "request_domain_source": "origin",
    "origin": "https://app-pendukung.sch.id",
    "referer": null,
    "ip": "203.0.113.10"
  }
}

Catatan Role keluar: dipakai untuk siswa mutasi/keluar (non-aktif). Data masih bisa diakses via API, namun user tidak dapat login/claim akun sampai admin mengembalikan role menjadi siswa.

GET /api/v1/members

Mengambil seluruh data member yang terdaftar di database ScholarGate SSO.

Query Parameters (Opsional)

Parameter Tipe Default Keterangan
search string - Cari berdasarkan nama, NIK, NISN, NIS, NIP, email
email string - Cari spesifik berdasarkan Google Email member
role string - Filter role: siswa, guru, tendik, alumni, keluar
page integer 1 Nomor halaman
per_page integer 50 Jumlah data per halaman (maks 100)

Contoh Request

cURL 
curl -X GET "https://portal.smage.my.id/api/v1/members?role=siswa&page=1&per_page=10" \
  -H "X-API-Key: YOUR_API_KEY_HERE"

Contoh Response (200 OK)

JSON Response 
{
  "success": true,
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "nama": "Ahmad Rizky Pratama",
      "role": "siswa",
      "jenis_kelamin": "L",
      "nik": "3275011234560001",
      "nomor_kk": "3174010101010101",
      "nisn": "0051234567",
      "nis": "2024.10.001",
      "nip": null,
      "tempat_lahir": "Jakarta",
      "tanggal_lahir": "2008-03-15",
      "agama": "Islam",
      "kelas": "XII IPA 1",
      "academic_year_id": "8d3h-7ns8-29sj-10dm",
      "academic_year_name": "2024/2025",
      "google_email": "ahmad.rizky@school.sch.id",
      "google_name": "Ahmad Rizky Pratama",
      "google_avatar": "https://lh3.googleusercontent.com/...",
      "email_pribadi": "ahmad@gmail.com",
      "no_telepon": "081234567890",
      "alamat": "Jl. Merdeka No. 123",
      "kode_pos": "11750",
      "ayah_nama": "Budi Pratama",
      "ibu_nama": "Siti Pratama",
      "wali_nama": null,
      "is_claimed": true,
      "claimed_at": "2025-03-15 10:30:00",
      "created_at": "2025-01-01 08:00:00",
      "updated_at": "2025-03-15 10:30:00"
    }
  ],
  "meta": {
    "total": 150,
    "page": 1,
    "per_page": 10,
    "total_pages": 15,
    "app_name": "CBT Exam System"
  }
}
GET /api/v1/members/lookup

Mencari satu member secara spesifik berdasarkan email Google mereka. Endpoint ini berguna bagi aplikasi pendukung untuk mengecek apakah user Google sudah terdaftar di SSO ScholarGate sebelum mengizinkan login lokal.

Query Parameters

Parameter Tipe Default Keterangan
email string - Wajib. Email Google pengguna.

Contoh Request

cURL 
curl -X GET "https://portal.smage.my.id/api/v1/members/lookup?email=ahmad.rizky@school.sch.id" \
  -H "X-API-Key: YOUR_API_KEY_HERE"

Contoh Response (200 OK - Jika ditemukan)

JSON Response 
{
  "success": true,
  "found": true,
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "nama": "Ahmad Rizky Pratama",
    "role": "siswa",
    "google_email": "ahmad.rizky@school.sch.id"
    // ... field lainnya (NIK/NISN/NIS, biodata, orang tua/wali, dll) ...
  },
  "meta": {
    "app_name": "CBT Exam System"
  }
}

Contoh Response (404 Not Found - Jika tidak ada)

JSON Response 
{
  "success": false,
  "found": false,
  "error": "Member not found",
  "message": "Email ahmad.rizky@school.sch.id belum terdaftar di SSO. Pengguna harus mendaftar di ScholarGate terlebih dahulu."
}
GET /api/v1/academic-year/active

Mengambil data tahun pelajaran yang sedang aktif di sistem.

Contoh Request

cURL 
curl -X GET "https://portal.smage.my.id/api/v1/academic-year/active" \
  -H "X-API-Key: YOUR_API_KEY_HERE"

Contoh Response (200 OK)

JSON Response 
{
  "success": true,
  "data": {
    "id": "8d3h-7ns8-29sj-10dm",
    "name": "2024/2025",
    "is_active": true,
    "created_at": "2024-06-01 00:00:00"
  },
  "meta": {
    "app_name": "CBT Exam System"
  }
}

4 Error Handling

HTTP Code Error Penyebab
401 API key is required Header X-API-Key tidak disertakan
403 Unauthorized API key salah, nonaktif, atau domain tidak cocok
Error Response Example
{
  "success": false,
  "error": "Unauthorized",
  "message": "API key tidak valid atau domain tidak sesuai dengan yang terdaftar."
}

5 Contoh Implementasi

P PHP (cURL)

PHP
<?php
$apiKey = 'YOUR_API_KEY_HERE';
$baseUrl = 'https://portal.smage.my.id/api/v1';

$ch = curl_init($baseUrl . '/members?role=siswa&per_page=20');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-API-Key: ' . $apiKey,
    ],
]);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($httpCode === 200) {
    $data = json_decode($response, true);
    foreach ($data['data'] as $member) {
        echo $member['nama'] . ' - ' . $member['kelas'] . "\n";
    }
} else {
    echo "Error: " . $response;
}

JS JavaScript (Fetch)

JavaScript
const API_KEY = 'YOUR_API_KEY_HERE';
const BASE_URL = 'https://portal.smage.my.id/api/v1';

async function getMembers(role = '', page = 1) {
    const params = new URLSearchParams({ role, page, per_page: 20 });
    
    const response = await fetch(
        `${BASE_URL}/members?${params}`,
        {
            headers: {
                'X-API-Key': API_KEY,
            }
        }
    );

    if (!response.ok) {
        const err = await response.json();
        throw new Error(err.message);
    }

    return await response.json();
}

// Usage
getMembers('siswa')
    .then(res => console.log(res.data))
    .catch(err => console.error(err));

Py Python (requests)

Python
import requests

API_KEY = 'YOUR_API_KEY_HERE'
BASE_URL = 'https://portal.smage.my.id/api/v1'

headers = {
    'X-API-Key': API_KEY,
}

response = requests.get(
    f'{BASE_URL}/members',
    headers=headers,
    params={'role': 'guru', 'per_page': 50}
)

if response.status_code == 200:
    data = response.json()
    for member in data['data']:
        print(f"{member['nama']} - {member['role']}")
else:
    print(f"Error {response.status_code}: {response.text}")