Advanced

Referensi API Lanjutan

Dokumentasi teknis untuk tim yang ingin membangun integrasi atau automasi custom.

Base URL

Semua request API dikirim ke base URL ini. Anggap ini sebagai alamat utama tempat semua endpoint SatuKontrak tinggal.

https://api.satukontrak.com/v1

Environment staging

Gunakan `https://api-staging.satukontrak.com` untuk testing. Pisahkan API key staging dan production agar data simulasi tidak bercampur dengan transaksi nyata.

Autentikasi

API SatuKontrak menggunakan Bearer token. Setiap request harus membawa API key di header `Authorization`.

curl https://api.satukontrak.com/v1/contracts \
  -H "Authorization: Bearer sk_live_your_api_key_here" \
  -H "Content-Type: application/json"

Best practice autentikasi

Jangan kirim API key dari browser. Semua request ke API SatuKontrak sebaiknya dipanggil dari backend, route handler, atau service internal yang bisa mengelola secret dengan aman.

Konvensi request

Sebelum membahas endpoint satu per satu, pahami aturan dasar ini. Konvensi request yang rapi biasanya mencegah sebagian besar error implementasi.

Property	Type	Description
`Authorization`	`Header`	Gunakan format `Bearer <api_key>` di setiap request yang memerlukan autentikasi.
`Content-Type`	`Header`	Untuk request JSON, gunakan `application/json`.
`timestamps`	`ISO 8601`	Gunakan format tanggal standar ISO agar parsing tidak ambigu.
`idempotency`	`recommended`	Untuk action penting dari sistem Anda, simpan log internal agar request yang sama tidak menghasilkan duplikasi tak sengaja.

Pagination dan filtering

Endpoint list biasanya mendukung parameter query untuk paging, filtering, dan pencarian. Ini penting ketika volume kontrak mulai bertambah.

curl "https://api.satukontrak.com/v1/contracts?page=1&limit=20&status=DRAFT&search=vendor" \
  -H "Authorization: Bearer sk_live_your_api_key_here"

Property	Type	Description
`page`optional	`number`	Nomor halaman yang ingin Anda ambil.
`limit`optional	`number`	Jumlah item per halaman. Gunakan nilai moderat agar response tetap ringan.
`status`optional	`string`	Filter berdasarkan status kontrak seperti DRAFT, SENT, atau SIGNED.
`search`optional	`string`	Query pencarian untuk mempersempit hasil list.

Rate limiting

API menerapkan rate limit untuk menjaga stabilitas platform. Kalau traffic Anda tinggi, respons header ini penting untuk dipantau.

Property	Type	Description
`X-RateLimit-Limit`	`number`	Jumlah maksimum request pada window saat ini.
`X-RateLimit-Remaining`	`number`	Jumlah request yang masih tersisa sebelum limit tercapai.
`X-RateLimit-Reset`	`number`	Unix timestamp kapan limit akan direset.

Cara aman menangani rate limit

Kalau Anda menerima `429`, jangan langsung spam retry. Terapkan exponential backoff, simpan request yang gagal bila perlu, dan pastikan proses batch Anda punya jeda yang wajar.

Endpoint utama

Daftar ini adalah endpoint yang paling sering dipakai dalam implementasi awal sampai operasional sehari-hari.

Property	Type	Description
`GET /contracts`	`list`	Mengambil daftar kontrak milik organisasi Anda.
`POST /contracts`	`create`	Membuat draft kontrak baru.
`GET /contracts/:id`	`detail`	Mengambil detail kontrak tertentu berdasarkan identifier.
`POST /contracts/:id/send`	`action`	Mengirim kontrak ke para pihak untuk penandatanganan.

Kode error

SatuKontrak memakai kode HTTP standar dan mengembalikan detail error dalam body respons supaya tim Anda bisa membedakan error validasi, autentikasi, dan error sistem.

{
  "error": {
    "code": "CONTRACT_NOT_FOUND",
    "message": "Contract with ID ctr_xxx was not found.",
    "status": 404
  }
}

Tangani error secara eksplisit

Untuk 4xx, fokus pada data atau izin yang dikirim. Untuk 5xx, siapkan retry terbatas dan logging yang cukup agar kasusnya bisa dianalisis tanpa menebak-nebak.

Property	Type	Description
`400`	`Bad Request`	Payload atau query parameter tidak valid.
`401`	`Unauthorized`	API key tidak ada, salah, atau tidak punya akses.
`403`	`Forbidden`	Request valid tetapi resource tidak boleh diakses oleh kredensial ini.
`404`	`Not Found`	Resource yang diminta tidak ditemukan.
`429`	`Too Many Requests`	Anda melebihi rate limit yang berlaku.
`500`	`Server Error`	Terjadi kegagalan internal di sisi server.

Checklist production

Sebelum rollout penuh ke production, cek kembali beberapa hal berikut agar integrasi Anda tidak rapuh saat volume naik.

•Pisahkan secret untuk staging dan production.
•Simpan `contractId`, status, dan timestamp penting di database internal Anda.
•Tambahkan logging untuk request gagal, response 4xx, dan response 5xx.