Dokumentasi Production API

RINGKASAN

Kontrak data read-only untuk sistem pemerintah

API ini dirancang untuk konsumsi server-ke-server. Sistem Gubernur dapat mengambil data yang telah diizinkan melalui scope tanpa memperoleh akses ke akun pengguna, password, konfigurasi server, private key, atau data pribadi pelapor.

Government integrationClient ID khusus dan audit request.

Read-onlyTidak menyediakan operasi create, update, atau delete.

JSON & GeoJSONData tabel dan geometri untuk dashboard serta peta.

Scope minimumSetiap endpoint hanya terbuka sesuai izin client.

QUICK START

Uji kredensial dalam tiga langkah

Siapkan Client ID dan API key.API key hanya ditampilkan sekali saat dibuat atau dirotasi.
Simpan sebagai server secret.Jangan menaruh API key di browser, frontend, URL, atau repositori.
Panggil endpoint ping.Respons 200 menandakan kredensial dan status client valid.

cURL

Client ID bersifat tetap. API key dapat tetap digunakan setelah admin logout atau login ulang. API key hanya berhenti berlaku apabila dicabut, kedaluwarsa, atau dirotasi.

AUTENTIKASI

Header wajib pada setiap request

Header	Wajib	Keterangan
`X-Client-ID`	Ya	Identitas client yang terdaftar, misalnya `gov-sulteng-satria-prod`.
`X-API-Key`	Ya	Secret production yang disimpan pada server Sistem Gubernur.
`Accept`	Disarankan	Gunakan `application/json`.

HTTP headers

X-Client-ID: gov-sulteng-satria-prod
X-API-Key: <API_KEY_PRODUCTION>
Accept: application/json

Header lama X-Client-Secret tetap didukung untuk kompatibilitas, tetapi implementasi baru sebaiknya menggunakan X-API-Key.

SCOPE AKSES

Hak akses yang tersedia

read:irrigationProfil D.I dan inventaris aset

Membuka metadata, daftar Daerah Irigasi, aset, jaringan yang tercatat sebagai inventaris, dan GeoJSON titik aset.

read:iksiNilai IKSI

Membuka nilai terbaru atau histori IKSI, kategori, status verifikasi, serta komponen penilaian.

read:areasLuas dan polygon

Membuka luas baku, fungsional, potensial, data geometri, jumlah fitur, serta GeoJSON polygon.

read:incidentsInsiden dan laporan

Membuka data kejadian, prioritas, status penanganan, luas terdampak, dan lokasi.

Scope harus diperbarui melalui menu API Key. Menambah scope tidak mengganti Client ID maupun API key selama menggunakan fungsi Perbarui scope tanpa mengganti key.

ENDPOINT

Endpoint Production API

Semua path di bawah ditambahkan setelah Base URL .

Memastikan Client ID, API key, status client, scope, dan masa berlaku kredensial dapat diterima SATRIA.

Request

Response 200

{
  "ok": true,
  "data": {
    "status": "ok",
    "service": "SATRIA Government Integration API",
    "clientId": "gov-sulteng-satria-prod",
    "scopes": ["read:irrigation", "read:iksi", "read:areas", "read:incidents"]
  }
}

Menampilkan identitas D.I, jumlah aset, dan luas layanan berdasarkan inventaris operasional aktif.

Request

Contoh elemen data

{
  "irrigation_area_id": "DI-001",
  "name": "D.I Air Terang",
  "asset_count": 227,
  "service_area_ha": 802.34
}

Menampilkan kode, nama, tipe, kondisi, kritikalitas, koordinat, dan waktu pembaruan aset.

format=geojsonOpsional. Mengubah respons menjadi FeatureCollection titik aset.

Request GeoJSON

Secara default mengembalikan penilaian terbaru setiap D.I. Gunakan filter untuk D.I, tahun, atau seluruh histori.

diNama, ID, atau kode D.I.

yearTahun penilaian, misalnya 2025.

history=trueMenyertakan seluruh histori penilaian.

Request

Contoh elemen data

{
  "irrigation_area_code": "72000001",
  "irrigation_area_name": "D.I Air Terang",
  "assessment_year": 2025,
  "total_score": 60.31,
  "category": "Sedang",
  "verification_status": "verified",
  "components": []
}

Menampilkan luas baku, fungsional, potensial, luas geometri, jumlah fitur, sumber data, dan ketersediaan polygon.

diNama, ID, atau kode D.I.

format=geojsonMengembalikan seluruh polygon kategori yang tersedia.

Request data luas

Request GeoJSON

STRUKTUR RESPONS

Envelope JSON standar

Respons JSON normal menggunakan struktur ok, meta, dan data. Respons GeoJSON menggunakan FeatureCollection dengan metadata tambahan.

JSON envelope

{
  "ok": true,
  "meta": {
    "apiVersion": "v17",
    "requestId": "uuid-request",
    "tenant": {
      "code": "UPT1-CIKASDA",
      "level": "uptd"
    },
    "generatedAt": "2026-08-02T13:00:00.000Z"
  },
  "data": []
}

KODE ERROR

Respons yang perlu ditangani client

HTTP	Makna	Tindakan
`400`	Parameter request tidak valid.	Periksa query dan format nilai.
`401`	Client ID atau API key tidak valid, tidak aktif, atau kedaluwarsa.	Uji endpoint ping dan periksa kredensial server.
`403`	Scope client tidak mengizinkan endpoint.	Tambahkan scope melalui menu API Key tanpa mengganti key.
`404`	Route API tidak ditemukan.	Gunakan endpoint lengkap, bukan hanya `/api/v17`.
`429`	Batas request terlampaui.	Terapkan retry dengan exponential backoff.
`500`	Gangguan internal SATRIA.	Simpan request ID dan hubungi administrator.
`503`	Layanan sedang belum siap.	Coba ulang setelah jeda dan periksa health SATRIA.

Contoh error

{
  "ok": false,
  "message": "Scope API tidak mencukupi: read:iksi"
}

KEAMANAN

Ketentuan penggunaan production

Simpan API key pada environment variable atau secret manager milik server Sistem Gubernur.
Gunakan HTTPS dan jangan menempatkan secret di query string.
Gunakan scope minimum dan endpoint read-only.
Jangan mencatat API key ke log aplikasi.
Rotasi key apabila terindikasi bocor. Client ID dapat tetap sama.
Simpan requestId untuk penelusuran insiden integrasi.

UNDUHAN

Berkas integrasi

OpenAPI runtimeKontrak yang mengikuti domain aktif. OpenAPI statisUntuk import ke generator client. Postman CollectionRequest siap konfigurasi. Panduan MarkdownDokumentasi teknis portabel.