Dokumentasi API Integrasi

API ini bersifat baca saja. Ia menyajikan daftar dan detail dokumen hukum beserta berkas lampirannya, sehingga aplikasi Anda tidak perlu menyalin dan memelihara datanya sendiri. Hanya dokumen yang sudah terbit di portal yang dikembalikan.

Empat koleksi disatukan di balik satu endpoint. Bidang koleksi menunjukkan asal tiap dokumen:

• puu — Peraturan perundang-undangan daerah: Perda, Perbup, Kepbup, Inbup, Surat Edaran, dan sejenisnya.
• dokumen_lain — Monografi, naskah akademik, dan dokumen langka.
• putusan — Putusan pengadilan, perkara, dan warta.
• pembentukan — Program penyusunan, rancangan PUU, dan hasil pemantauan.

Alamat dasar: /api/v1/integrasi

Ajukan permintaan ke pengelola JDIH dengan menyebutkan nama aplikasi, untuk apa datanya dipakai, dan email pengembang yang dapat dihubungi. Anda akan menerima key berbentuk jdih_<penanda>_<rahasia>.

Key hanya ditampilkan sekali saat diterbitkan dan tidak dapat dipulihkan; bila hilang, mintalah rotasi. Perlakukan seperti kata sandi: simpan di konfigurasi server, jangan ditanam di kode aplikasi mobile atau JavaScript sisi peramban, dan jangan dimasukkan ke repositori.

Kirim key pada setiap permintaan lewat header:

curl -H "X-API-Key: jdih_xxxxxxxxxxxx_yyyyyyyy" \
  "/api/v1/integrasi/dokumen?limit=10"

Anda tidak perlu mengirim informasi wilayah atau tenant apa pun — key sudah menentukan data mana yang boleh dibaca.

Mengembalikan satu halaman dokumen beserta berkasnya. Nilai parameter yang tidak dikenali diabaikan, bukan ditolak, sehingga integrasi lama tetap memperoleh hasil bila suatu filter kami pensiunkan.

Contoh respons:

{
  "data": [
    {
      "id": "3f2a…",
      "koleksi": "puu",
      "jenis": "perda",
      "jenis_label": "Peraturan Daerah",
      "judul": "Peraturan Daerah tentang Retribusi Daerah",
      "nomor": "12",
      "tahun": 2024,
      "tentang": "Retribusi Daerah",
      "status_berlaku": "berlaku",
      "tanggal": "2024-03-01",
      "url_portal": "https://jdih.kutaitimurkab.go.id/produk-hukum/3f2a…",
      "jumlah_berkas": 2,
      "berkas": [
        {
          "id": "9c11…",
          "label": "Dokumen Utama",
          "url": "https://…/uploads/2024/perda-12.pdf",
          "mime": "application/pdf",
          "ukuran_bytes": 1048576,
          "urutan": 0
        }
      ]
    }
  ],
  "total": 1234,
  "limit": 25,
  "offset": 0
}

total adalah jumlah seluruh hasil yang cocok, bukan hanya halaman ini. Setiap berkas.url sudah berbentuk URL absolut yang dapat langsung diunduh, dan url_portal menunjuk halaman detail di portal bila Anda ingin menautkan balik.

Mengembalikan bidang yang sama dengan daftar, ditambah abstrak dan objek metadata berisi kolom khas koleksi asalnya — misalnya dasar_hukum dan pemrakarsa untuk PUU, isbn untuk monografi, atau lembaga_peradilan untuk putusan.

curl -H "X-API-Key: $JDIH_API_KEY" \
  "/api/v1/integrasi/dokumen/puu/3f2a1b4c-5d6e-7f80-9a0b-1c2d3e4f5061"

Kunci di dalam metadata yang tidak terisi dihilangkan, bukan dikirim bernilai null. Perlakukan setiap kunci sebagai opsional.

Setiap key punya kuota permintaan per menit. Sisa kuota disertakan pada tiap respons lewat header X-RateLimit-Limit dan X-RateLimit-Remaining. Bila terlampaui, jawaban adalah 429 dengan header Retry-After berisi jeda dalam detik — tunggu selama itu sebelum mencoba lagi, jangan mengulang seketika.

Respons berhasil boleh disimpan sementara selama 60 detik. Karena isinya khusus untuk key Anda, simpanlah di cache milik aplikasi sendiri, bukan di cache bersama yang dapat terbaca pihak lain.

Galat selalu berbentuk {"error":"<kode>"}:

Dokumen yang tidak ada, belum terbit, dan di luar cakupan key sengaja dijawab sama-sama 404; jangan menyimpulkan keberadaan sebuah dokumen dari perbedaan jawaban.

Seluruh endpoint, parameter, dan skema respons tersedia sebagai berkas OpenAPI 3.1 yang dapat dibaca tanpa key:

curl "/api/v1/integrasi/openapi.yaml"

Buka openapi.yaml