SDK Data — Dokumentasi API

Semua yang bisa dilakukan sistem luar terhadap SDK kependudukan. Dua pintu: API formulir (widget tempel, aplikasi pengisi) dan API mesin (cekungan tema, integrasi server-ke-server). JSON polos, kontrak /api/v1 beku — perubahan kelak berdampingan sebagai /api/v2, bukan mengubah yang ada.

Prinsip

Tak-cocok itu hasil, bukan galat. NIK yang tidak ditemukan, baris tanpa padanan, cekungan yang tidak menjawab — semuanya jawaban 200 yang jujur. Galat HTTP hanya untuk transport, token salah, atau permintaan cacat.
Semua tercatat. Setiap tanya/cocokkan/kirim/rute meninggalkan jejak di log konsol berikut asal (dari).
Kotak masuk dulu, tabel kemudian. Baris yang dikirim sistem luar mendarat sebagai klaim di kotak masuk; pemasangan ke warga terjadi di konsol, bukan otomatis.

Auth

API mesin: header X-Sdk-Token (token dibagikan per cekungan oleh pengelola SDK). Konsol: sesi login (kuki). API formulir di instance publik: terbuka + CORS; di instance login semua butuh sesi.

API mesin — suite dua arah

POST/api/tanya — verifikasi satu NIK

curl -s https://login.garudata.cloud/api/tanya \
  -H "Content-Type: application/json" -H "X-Sdk-Token: $TOKEN" \
  -d '{"dari": "perindustrian", "nik": "3174051204880001"}'

→ {"ok": true, "ada": true, "nik": "3174051204880001",
   "nama": "Muhammad Arif", "tanggal_lahir": "1988-04-12", "jenis_kelamin": "laki_laki"}
→ {"ok": true, "ada": false, "nik": "…"}        # tidak ditemukan = jawaban biasa

POST/api/cocokkan — pencocokan batch + laporan persen

Maksimal 500 baris per panggilan. Tiap baris boleh membawa nik, atau nama + tanggal_lahir untuk pencocokan kandidat (ambang skor 0.8).

curl -s …/api/cocokkan -H "X-Sdk-Token: $TOKEN" -H "Content-Type: application/json" -d '{
  "dari": "perindustrian",
  "baris": [{"ref": 1, "nik": "3174051204880001"},
            {"ref": 2, "nama": "Muhammad Arif", "tanggal_lahir": "1988-04-12"},
            {"ref": 3, "nik": "9999999999999999"}]}'

→ {"ok": true,
   "hasil": [{"ref": 1, "cocok": "31740512…", "cara": "nik"},
             {"ref": 2, "cocok": "31740512…", "cara": "nama_tanggal", "skor": 0.85},
             {"ref": 3, "cocok": null, "cara": null}],
   "ringkasan": {"total": 3, "cocok": 2, "lewat_nik": 1, "lewat_nama_tanggal": 1,
                 "tanpa_padanan": 1, "persen_cocok": 66.7}}

10% karyawan industri tidak ketemu padanan di kependudukan? Itu memang begitu. tanpa_padanan adalah angka kelas satu yang layak dilaporkan, bukan kegagalan integrasi. Baris ber-cara: "nama_tanggal" adalah kandidat, bukan kepastian: skornya ikut dikirim dan pemasangan resmi tetap lewat konfirmasi manusia di konsol.

POST/api/kirim — dorong baris klaim ke kotak masuk

curl -s …/api/kirim -H "X-Sdk-Token: $TOKEN" -H "Content-Type: application/json" -d '{
  "dari": "perindustrian",
  "baris": [{"nik": "3174051204880001", "nib_perusahaan": "8120001234567", "jabatan": "operator"}]}'

→ {"ok": true, "diterima": 1, "masukan_id": [812],
   "catatan": "baris menunggu dipasangkan di konsol"}

POST/api/rute — bertanya ke cekungan lain, SDK sebagai perantara

"Industri minta tolong verifikasi ke Dukcapil." SDK mencari cekungan tujuan di registry (defs/cekungan.json), meneruskan pertanyaan, dan mengembalikan jawabannya apa adanya.

curl -s …/api/rute -H "X-Sdk-Token: $TOKEN" -H "Content-Type: application/json" -d '{
  "dari": "perindustrian", "ke": "kependudukan", "jenis": "verifikasi",
  "isi": {"tabel": "penduduk", "kunci": "nik", "nilai": "3174051204880001"}}'

→ {"ok": true, "terjawab": true, "dari_cekungan": "kependudukan",
   "jawaban": {"ok": true, "ada": true, "jumlah": 1, "tabel": "penduduk"}}
→ {"ok": true, "terjawab": false, "sebab": "cekungan 'x' tidak menjawab"}   # juga hasil biasa

API formulir

Jalur	Apa
`POST /api/isi`	Setor isian formulir: `{aplikasi, jawaban: {wadah: {kolom: nilai}}, subjek: {nik\|rumah_id\|aset_id}}`. Isian yang tak dikenali bentuknya masuk kotak masuk (tidak dibuang).
`GET /api/defs`	Katalog hidup: wadah, formulir (dengan `tingkat`, `prasetel`), sistem.
`GET /api/snapshot`	Seluruh baris per wadah (untuk konsol/uji; di instance login butuh sesi).
`GET /embed.js`	Widget tempel evergreen: `<script src="…/embed.js" data-sistem="id"></script>`.

Semua jalur di atas juga hidup di bawah /api/v1/… — alias beku selamanya.

Klien resmi

Python (stdlib): tools/sdk_klien.py · JavaScript (Node ≥18 / browser): /sdk-klien.js

from sdk_klien import SdkData
sdk = SdkData("https://login.garudata.cloud", token="…")
lapor = sdk.cocokkan([{"ref": r["id"], "nik": r["nik_pekerja"]} for r in baris_kami])
print(lapor["ringkasan"]["persen_cocok"], "% cocok")

const { SdkData } = require("./sdk-klien.js");
const sdk = new SdkData("https://login.garudata.cloud", process.env.TOKEN);
const w = await sdk.tanya("3174051204880001");   // {ok, ada, …}

Batas dan perilaku

Badan permintaan maksimal 2 MB (413 bila lebih); cocokkan/kirim maksimal 500 baris.
Token salah → 401. API mesin belum diaktifkan (tanpa SDK_TOKEN) → 503.
rute menunggu cekungan tujuan maksimal 10 detik, lalu menjawab terjawab: false — perantara tidak pernah menggantung pemanggil. coba_lagi: true berarti gangguan sementara (silakan ulang); coba_lagi: false berarti tujuan memang tidak terdaftar.
Bila pengelola SDK memasang peta token per cekungan (data/token-cekungan.json), identitas dari diturunkan dari token — cekungan tidak bisa mengaku sebagai cekungan lain.
Instance demo memangkas kotak masuk pada 800 baris; pemasangan produksi mematikan pemangkasan itu.