API mitra untuk data sekolah.

Autentikasi

Setiap permintaan membawa key-id di header dan tanda tangan HMAC-SHA256 atas timestamp + method + path + body. Secret tidak pernah dikirim. Permintaan dengan timestamp lebih dari 300 detik ditolak.

X-EduCore-Key-Id:    ak_live_7Qp2R9
X-EduCore-Signature: t=1789632650,v1=9f...
Idempotency-Key:     4f0a1b2c-...

Versi & deprekasi

Versi ada di path, bukan header. Perubahan yang memutus kontrak selalu menjadi /api/v2/ baru; penambahan field opsional bukan perubahan yang memutus. Versi lama hidup 12 bulan setelah pengganti keluar, dan mengirim header Sunset sejak hari pertama.

Konvensi

Format uang adalah string dengan mata uang di level objek yang sama. Jangan pernah menjumlahkan lintas mata uang: endpoint agregat mengembalikan array total per mata uang, bukan satu angka.

Error

Semua error adalah RFC 9457 application/problem+json. Cabangkan logika pada code — string SCREAMING_SNAKE yang stabil — bukan pada prosa detail.

{
  "type":     "/errors/scope-denied",
  "title":    "Scope not granted",
  "status":   403,
  "detail":   "Key lacks roster.pii",
  "instance": "/api/v1/partner/_",
  "code":     "SCOPE_DENIED"
}

Webhook & polling

Webhook adalah jalur utama. Daftarkan satu endpoint HTTPS per lingkungan, terima POST bertanda tangan, dan balas 2xx dalam 5 detik. Kegagalan dicoba ulang lima kali hingga 6 jam; setelahnya kejadian tetap tersedia lewat polling.

Endpoint

MCP

Endpoint POST /partner/mcp adalah server Model Context Protocol (HTTP, mode JSON tanpa sesi) di belakang autentikasi dan batas laju yang sama dengan endpoint lain. Isinya alat hanya-baca; kunci hanya melihat alat sesuai cakupannya, dan baris yang dikembalikan sama persis dengan REST: batas sekolah, batas yayasan, NIK hanya dengan roster.pii.

Persiapan

1. Python 3.8 ke atas di komputer yang menjalankan klien AI (python3 --version; di Windows gunakan python).
2. Unduh educore_mcp_bridge.py dan simpan di folder tetap, misalnya ~/sekolahos/.
3. Periksa berkas sebelum dijalankan: shasum -a 256 educore_mcp_bridge.py harus menghasilkan 177f51df1cb11dea603f32a03809fca400a4f0e5e5dfbabf378f50d3f3a0c080.
4. Minta admin yayasan menerbitkan kunci. Catat key-id dan secret; secret hanya tampil sekali.
5. Simpan secret di pengelola kata sandi atau keychain sistem operasi, bukan di berkas yang disinkronkan atau masuk ke git. Minta kunci dengan scope seperlunya dan batasi dengan daftar IP.

Panduan per klien

{
  "mcpServers": {
    "sekolahos": {
      "command": "python3",
      "args": ["/Users/anda/sekolahos/educore_mcp_bridge.py"],
      "env": {
        "EDUCORE_API_BASE": "https://schoolday.live/api/v1/",
        "EDUCORE_KEY_ID": "ak_test_...",
        "EDUCORE_KEY_SECRET": "..."
      }
    }
  }
}

claude mcp add sekolahos \
  --env EDUCORE_API_BASE=https://schoolday.live/api/v1/ \
  --env EDUCORE_KEY_ID=ak_test_... \
  --env EDUCORE_KEY_SECRET=... \
  -- python3 ~/sekolahos/educore_mcp_bridge.py

EDUCORE_API_BASE=https://schoolday.live/api/v1/ \
EDUCORE_KEY_ID=ak_test_... EDUCORE_KEY_SECRET=... \
npx @modelcontextprotocol/inspector python3 educore_mcp_bridge.py

Uji cepat dari terminal

Kirim satu pesan JSON-RPC ke jembatan; balasannya daftar alat yang boleh dipakai kunci Anda:

echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | python3 educore_mcp_bridge.py

Alat yang tersedia

Semua alat menerima limit (maksimal 200) dan before_id. Jawaban memuat next_before_id; teruskan nilainya untuk halaman berikutnya. Tidak ada alat tulis; pendaftaran webhook tetap hanya lewat REST. Satu kunci boleh memanggil alat paling banyak 120 kali per menit (di bawah batas 600 permintaan).

Jika tidak jalan

Untuk reseller dan integrator

Setiap kunci API berlaku untuk tepat satu yayasan; tidak ada kunci yang menjangkau beberapa yayasan. Jika Anda mengintegrasikan banyak sekolah, minta admin tiap yayasan menerbitkan kunci untuk Anda di konsol, menu Mitra & kunci API, dengan cakupan seminimal mungkin. Simpan tiap rahasia di brankas Anda sendiri, satu per yayasan.

Untuk membantu konfigurasi di dalam konsol, admin yayasan membuat login staf biasa dengan peran seperlunya. Reseller tidak mendapat akses lintas yayasan.

Batas laju

Melewati batas menghasilkan 429 RATE_LIMITED dengan header Retry-After.