Logo SIPAKASIDISIPAKASIDIDevelopersPortal Mitra →

SIPAKASIDI Public API

API REST read-only berbasis OpenAPI 3.1 untuk instansi, akademisi, dan mitra — statistik pelayanan, demografi agregat, dan katalog layanan kelurahan. Autentikasi dengan API key.

Mulai cepat

  1. Masuk ke Portal Mitra dan buka menu API Keys.
  2. Buat key baru, pilih scope yang dibutuhkan, lalu simpan key di environment variable server Anda.
  3. Panggil GET /me untuk memastikan key berfungsi.

Base URL: https://sipakasidi.ssyubix.com/api/public/v1

bash
export SIPAKASIDI_API_KEY="sipk_..."
curl https://sipakasidi.ssyubix.com/api/public/v1/me -H "Authorization: Bearer $SIPAKASIDI_API_KEY"

Spesifikasi lengkap tersedia dalam format OpenAPI 3.1 di /api/public/v1/openapi.json — impor ke Postman, Insomnia, Swagger UI, atau generator SDK (mis. openapi-generator).

Autentikasi

Setiap request wajib menyertakan API key sebagai Bearer token: Authorization: Bearer sipk_…. Header alternatif X-API-Key juga diterima. Key hanya ditampilkan sekali saat dibuat; server hanya menyimpan hash-nya.

Perlakukan key seperti password: simpan di sisi server, jangan disematkan di aplikasi frontend/mobile, dan cabut segera dari portal bila bocor. Semua data yang dikembalikan bersifat agregat — tanpa NIK, nama, atau data pribadi warga.

Scope & jangkauan wilayah

Scope membatasi endpoint yang boleh dipanggil sebuah key. Scope maksimum dan jangkauan wilayah (satu kelurahan, satu kecamatan, atau semua) ditetapkan admin untuk akun mitra Anda.

ScopeAkses
wilayah:readDaftar kelurahan & kecamatan dalam jangkauan key
stats:readJumlah warga & rekap status pengajuan layanan
penduduk:readDemografi agregat (tanpa NIK/nama), sel kecil disamarkan
layanan:readKatalog jenis layanan & persyaratannya

Rate limit

Kuota dihitung per akun mitra (semua key dijumlahkan) dalam jendela 60 detik; default 60 request/menit. Setiap response menyertakan X-RateLimit-Limit dan X-RateLimit-Remaining. Saat kuota habis, API membalas 429 dengan header Retry-After — tunggu lalu ulangi dengan exponential backoff.

Error

Semua error memakai format yang sama. Sertakan request_id saat menghubungi admin.

json
{
  "error": {
    "type": "permission_error",
    "code": "insufficient_scope",
    "message": "API key ini tidak memiliki scope `penduduk:read`.",
    "request_id": "req_8f14e45fceea167a5a36dedd4bea2543"
  }
}
HTTPtypecodeArti
400invalid_request_errorinvalid_parameterParameter query tidak valid
401authentication_errormissing_api_key / invalid_api_keyKey tidak ada, salah, dicabut, kedaluwarsa, atau akun ditangguhkan
403permission_errorinsufficient_scopeKey tidak punya scope untuk endpoint ini
404invalid_request_errorkelurahan_not_foundKelurahan di luar jangkauan key
429rate_limit_errorrate_limit_exceededKuota per menit habis
500api_errorinternal_errorKesalahan di server kami
get/me— Info API keyScope: tidak perlu

Detail API key yang sedang dipakai: scope efektif, jangkauan wilayah, dan rate limit. Tidak butuh scope khusus — cocok untuk tes koneksi.

Request
cURL
curl https://sipakasidi.ssyubix.com/api/public/v1/me \
  -H "Authorization: Bearer $SIPAKASIDI_API_KEY"
Contoh response 200
json
{
  "object": "api_key",
  "data": {
    "id": "0c9b1f2e-3a4d-4e5f-8a9b-0c1d2e3f4a5b",
    "nama": "Server Produksi",
    "prefix": "sipk_3f9a1c2",
    "organisasi": "Dinas Sosial Kota",
    "scopes": [
      "wilayah:read",
      "stats:read"
    ],
    "wilayah": {
      "level": "kecamatan",
      "kelurahan_id": null,
      "kecamatan_id": "5b0c1a52-6e1f-4d59-9d4a-0d2b8c1e7f10"
    },
    "rate_limit_per_menit": 60,
    "expires_at": null
  }
}
get/wilayah— Daftar kelurahanScope: wilayah:read

Kelurahan aktif dalam jangkauan API key, beserta kecamatannya. Gunakan `id` kelurahan sebagai filter `kelurahan_id` di endpoint lain.

ParameterLokasiTipeKeterangan
kelurahan_idquerystring (uuid)Persempit hasil ke satu kelurahan (harus di dalam jangkauan API key). Kosongkan untuk semua kelurahan dalam jangkauan.
Request
cURL
curl https://sipakasidi.ssyubix.com/api/public/v1/wilayah?kelurahan_id=<UUID> \
  -H "Authorization: Bearer $SIPAKASIDI_API_KEY"
Contoh response 200
json
{
  "object": "list",
  "scope": {
    "level": "kecamatan",
    "kelurahan_id": null,
    "kecamatan_id": "5b0c1a52-6e1f-4d59-9d4a-0d2b8c1e7f10"
  },
  "data": [
    {
      "id": "a1b2c3d4-0000-4000-8000-000000000001",
      "kode": "7371011001",
      "nama": "Kelurahan Contoh",
      "kecamatan": {
        "id": "5b0c1a52-6e1f-4d59-9d4a-0d2b8c1e7f10",
        "kode": "737101",
        "nama": "Kecamatan Contoh"
      }
    }
  ]
}
get/stats— Statistik pelayananScope: stats:read

Jumlah warga terdaftar dan rekap pengajuan layanan per kelurahan, termasuk jumlah selesai & rata-rata durasi penyelesaian bulan berjalan.

ParameterLokasiTipeKeterangan
kelurahan_idquerystring (uuid)Persempit hasil ke satu kelurahan (harus di dalam jangkauan API key). Kosongkan untuk semua kelurahan dalam jangkauan.
Request
cURL
curl https://sipakasidi.ssyubix.com/api/public/v1/stats?kelurahan_id=<UUID> \
  -H "Authorization: Bearer $SIPAKASIDI_API_KEY"
Contoh response 200
json
{
  "object": "list",
  "scope": {
    "level": "kecamatan",
    "kelurahan_id": null,
    "kecamatan_id": "5b0c1a52-6e1f-4d59-9d4a-0d2b8c1e7f10"
  },
  "ringkasan": {
    "jumlah_kelurahan": 1,
    "total_warga": 1284,
    "total_pengajuan": 342
  },
  "data": [
    {
      "kelurahan": {
        "id": "a1b2c3d4-0000-4000-8000-000000000001",
        "kode": "7371011001",
        "nama": "Kelurahan Contoh"
      },
      "kecamatan": {
        "id": "5b0c1a52-6e1f-4d59-9d4a-0d2b8c1e7f10",
        "nama": "Kecamatan Contoh"
      },
      "total_warga": 1284,
      "pengajuan": {
        "total": 342,
        "per_status": {
          "SELESAI": 301,
          "MENUNGGU_RT_RW": 12,
          "MENUNGGU_LURAH": 4,
          "DITOLAK": 25
        },
        "selesai_bulan_ini": 38,
        "rata_rata_hari_penyelesaian_bulan_ini": 1.7
      }
    }
  ]
}
get/penduduk— Demografi agregatScope: penduduk:read

Distribusi warga terdaftar per jenis kelamin, kelompok umur, agama, pendidikan, pekerjaan, dan status perkawinan. Kategori dengan jumlah di bawah `ambang_penyamaran` digabung menjadi `LAINNYA_DISAMARKAN` untuk mencegah identifikasi individu.

ParameterLokasiTipeKeterangan
kelurahan_idquerystring (uuid)Persempit hasil ke satu kelurahan (harus di dalam jangkauan API key). Kosongkan untuk semua kelurahan dalam jangkauan.
Request
cURL
curl https://sipakasidi.ssyubix.com/api/public/v1/penduduk?kelurahan_id=<UUID> \
  -H "Authorization: Bearer $SIPAKASIDI_API_KEY"
Contoh response 200
json
{
  "object": "penduduk.agregat",
  "scope": {
    "level": "kecamatan",
    "kelurahan_id": null,
    "kecamatan_id": "5b0c1a52-6e1f-4d59-9d4a-0d2b8c1e7f10"
  },
  "kelurahan": [
    {
      "id": "a1b2c3d4-0000-4000-8000-000000000001",
      "nama": "Kelurahan Contoh"
    }
  ],
  "ambang_penyamaran": 5,
  "data": {
    "total_warga": 1284,
    "distribusi": {
      "jenis_kelamin": [
        {
          "nilai": "PEREMPUAN",
          "jumlah": 655
        },
        {
          "nilai": "LAKI-LAKI",
          "jumlah": 629
        }
      ],
      "kelompok_umur": [
        {
          "nilai": "25-44",
          "jumlah": 441
        },
        {
          "nilai": "45-59",
          "jumlah": 290
        },
        {
          "nilai": "LAINNYA_DISAMARKAN",
          "jumlah": 3
        }
      ]
    }
  }
}
get/layanan— Katalog jenis layananScope: layanan:read

Jenis layanan aktif beserta persyaratannya di setiap kelurahan dalam jangkauan.

ParameterLokasiTipeKeterangan
kelurahan_idquerystring (uuid)Persempit hasil ke satu kelurahan (harus di dalam jangkauan API key). Kosongkan untuk semua kelurahan dalam jangkauan.
Request
cURL
curl https://sipakasidi.ssyubix.com/api/public/v1/layanan?kelurahan_id=<UUID> \
  -H "Authorization: Bearer $SIPAKASIDI_API_KEY"
Contoh response 200
json
{
  "object": "list",
  "scope": {
    "level": "kecamatan",
    "kelurahan_id": null,
    "kecamatan_id": "5b0c1a52-6e1f-4d59-9d4a-0d2b8c1e7f10"
  },
  "data": [
    {
      "id": "f0e1d2c3-0000-4000-8000-000000000009",
      "nama": "Surat Keterangan Domisili",
      "slug": "sk-domisili",
      "deskripsi": "Keterangan tempat tinggal warga.",
      "persyaratan": [
        "Fotokopi KTP",
        "Fotokopi KK",
        "Surat pengantar RT/RW"
      ],
      "kelurahan": {
        "id": "a1b2c3d4-0000-4000-8000-000000000001",
        "nama": "Kelurahan Contoh"
      }
    }
  ]
}
SIPAKASIDI Public API — Dokumentasi Pengembang · SIPAKASIDI