Panduan API

API ini memakai JSON. Dari server Anda, Anda bisa unggah PDF, kirim undangan tanda tangan, unduh hasil, dan cek keaslian dokumen.

Alamat dasar

https://alphasign.pastibisa.app/api/v1

Format

JSON

Cara masuk

Bearer Token

Semua alamat di halaman ini ditulis relatif terhadap alamat dasar di atas. Contoh: /me artinya https://alphasign.pastibisa.app/api/v1/me.

Autentikasi

Hampir semua permintaan butuh token. Pengecualiannya hanya verifikasi publik di bawah. Token hanya untuk server ke server — jangan ditaruh di browser, aplikasi HP, atau kode yang bisa dilihat orang lain.

# Sertakan di setiap permintaan yang butuh login
Authorization: Bearer as_your_api_token_here

Cara mendapat token

Masuk ke Pengaturan → API
Klik Generate Key
Beri nama, misalnya “Backend ERP”
Salin token. Token hanya ditampilkan sekali

Token diawali as_.
Satu akun maksimal 5 key.
API tersedia mulai paket Lontar. Aksara dan Sabak tidak bisa memakai API yang butuh token.

Simpan token di tempat yang aman. Jangan taruh di chat, di GitHub, atau di kode yang bisa dibaca orang lain. Kalau bocor, cabut key itu di Pengaturan → API, lalu buat yang baru.

Batas pemakaian

Ada tiga lapisan. Yang paling ketat yang berlaku. Semua API key di akun yang sama memakai jatah yang sama.

Per menit dan per hari — supaya tidak ada lonjakan tiba-tiba.
Per bulan — kuota paket. Hanya permintaan yang berhasil yang dihitung.

Paket	Per menit	Per hari	Per bulan
Lontar	60	1.000	Tidak ada kuota bulanan
Prasasti	120	5.000	1.000
Piagam	300	10.000	5.000
Keraton	300	10.000	10.000
Nusantara	600	20.000	20.000

Lontar tetap dibatasi 60 per menit dan 1.000 per hari. Aksara dan Sabak tidak punya akses API.

Header yang dikirim server

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 298
Retry-After: 45  # hanya saat 429 karena terlalu sering

X-RateLimit-Limit mengikuti batas per menit, bukan per bulan.

Jika terjadi error

Bentuk JSON tidak selalu sama. Baca error atau message sesuai contoh di bawah.

Kode	Arti
200	Berhasil
201	Berhasil dibuat
401	Token hilang atau tidak valid
403	Paket tidak mendukung fitur ini, atau token ditangguhkan
404	Data tidak ditemukan
422	Isian tidak valid, atau langkah tidak boleh dilakukan
429	Terlalu sering, atau kuota habis — lihat isi JSON-nya

401 — belum login

{
  "message": "Unauthenticated."
}

403 — paket tidak mendukung API

{
  "success": false,
  "error": "plan_required",
  "message": "Paket Anda tidak mendukung fitur ini. Silakan upgrade."
}

422 — isian salah

{
  "message": "The title field is required.",
  "errors": {
    "title": ["The title field is required."]
  }
}

429 — terlalu sering meminta

{
  "success": false,
  "error": "Too many requests",
  "retry_after": 45
}

Tunggu sesuai retry_after (detik), atau header Retry-After.

429 — kuota dokumen atau penyimpanan habis

{
  "success": false,
  "error": "quota_exceeded",
  "message": "Kuota dokumen sudah habis."
}

Kuota API bulanan yang habis juga 429, dengan error berisi Monthly API quota exceeded.

Akun

GET/me

Profil pengguna yang terhubung dengan token, plus organisasi dan nama paket.

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://alphasign.pastibisa.app/api/v1/me

Jawaban 200

{
  "success": true,
  "data": {
    "id": "uuid",
    "name": "Budi Santoso",
    "email": "budi@contoh.co.id",
    "role": "owner",
    "tenant": { "id": "uuid", "name": "PT Contoh", "plan": "Piagam" },
    "created_at": "2026-03-01T08:00:00.000000Z"
  }
}

GET/me/quota

Pemakaian kuota yang sama dengan yang terlihat di dasbor: tanda tangan, dokumen, penyimpanan, dan permintaan API.

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://alphasign.pastibisa.app/api/v1/me/quota

Jawaban 200

{
  "success": true,
  "data": {
    "plan": "Piagam",
    "period": "2026-09",
    "resets_on": "2026-10-01T00:00:00+07:00",
    "signatures": { "used": 120, "limit": 500, "remaining": 380, "unlimited": false },
    "documents": { "used": 85, "limit": 500, "remaining": 415, "unlimited": false },
    "storage_bytes": { "used": 5368709120, "limit": 26843545600, "remaining": 21474836480, "unlimited": false },
    "api_requests": { "used": 450, "limit": 5000, "remaining": 4550, "unlimited": false }
  }
}

Jika unlimited bernilai true, limit 0 dan remaining null. Artinya jenis kuota itu tidak dibatasi. Penyimpanan tidak di-reset tiap bulan.

Dokumen

Untuk dokumen lepas (bukan file di dalam proyek massal). Owner dan admin organisasi melihat semua dokumen organisasi. Anggota hanya melihat miliknya.

GET/documents

Daftar dokumen, dibagi per halaman. Isi daftar ada di data.data — bukan langsung di data.

Parameter

status	opsional	draft, pending, atau completed
per_page	opsional	1–100, default 20

curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://alphasign.pastibisa.app/api/v1/documents?status=pending&per_page=10"

Jawaban 200 (disingkat)

{
  "success": true,
  "data": {
    "current_page": 1,
    "data": [{ "id": "uuid", "title": "Kontrak Kerja", "status": "pending" }],
    "per_page": 10,
    "total": 42,
    "last_page": 5
  }
}

POST/documents

Unggah PDF dan buat dokumen draft. Penandatangan boleh ditambahkan sekarang, atau belakangan lewat aplikasi web.

Isian (multipart/form-data)

title *	teks	Judul dokumen, maksimal 255 karakter
file *	berkas PDF	Maksimal 20 MB, harus PDF sungguhan
signing_mode	opsional	single, sequential, atau parallel. Default: parallel
signers[]	opsional	Maksimal 50 orang. Tiap orang: name dan email

curl -X POST \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "title=Kontrak Kerja" \
  -F "signing_mode=parallel" \
  -F "file=@document.pdf" \
  -F "signers[0][name]=Siti Aminah" \
  -F "signers[0][email]=siti@contoh.co.id" \
  https://alphasign.pastibisa.app/api/v1/documents

Jawaban sukses: 201. Token undangan penandatangan tidak ikut dikirim di JSON.

GET/documents/{id}

Detail satu dokumen beserta daftar penandatangan dan statusnya.

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://alphasign.pastibisa.app/api/v1/documents/uuid-dokumen

POST/documents/{id}/send

Kirim email undangan ke semua penandatangan, lalu ubah status dari draft menjadi pending. Tautan undangan berlaku 7 hari.

curl -X POST -H "Authorization: Bearer YOUR_TOKEN" \
  https://alphasign.pastibisa.app/api/v1/documents/uuid-dokumen/send

Ditolak 422 jika dokumen bukan draft, atau belum ada penandatangan.

GET/documents/{id}/download

Unduh file PDF. Kalau dokumen sudah selesai ditandatangani, yang diunduh adalah PDF yang sudah ditandatangani. Kalau masih draft, yang diunduh adalah PDF aslinya.

curl -H "Authorization: Bearer YOUR_TOKEN" \
  -o dokumen.pdf \
  https://alphasign.pastibisa.app/api/v1/documents/uuid-dokumen/download

Jawaban sukses berupa berkas PDF, bukan JSON. Kalau file tidak ada di penyimpanan: 404 dengan JSON File not found.

DELETE/documents/{id}

Hapus dokumen draft. Dokumen yang sedang berproses atau sudah selesai tidak bisa dihapus lewat API (404).

curl -X DELETE -H "Authorization: Bearer YOUR_TOKEN" \
  https://alphasign.pastibisa.app/api/v1/documents/uuid-dokumen

Kalau draft masih punya permintaan tanda tangan yang belum selesai, server menjawab 422.

GET/documents/{id}/signers

Daftar penandatangan. Token undangan tidak dikirim — jangan mengandalkan field itu untuk membangun tautan tanda tangan.

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://alphasign.pastibisa.app/api/v1/documents/uuid-dokumen/signers

Proyek

Untuk tanda tangan massal. API bisa membuat wadah proyek dan melihat isinya. Unggah file PDF ke dalam proyek tetap lewat aplikasi web. Status awal proyek: active.

GET/projects

Daftar proyek, dibagi per halaman. Parameter per_page: 1–100, default 20. Daftar ada di data.data.

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://alphasign.pastibisa.app/api/v1/projects

POST/projects

Buat proyek baru. Kirim JSON, bukan form-data.

Isian (JSON)

name *	teks	Nama proyek
description	opsional	Keterangan, maksimal 1000 karakter
signing_mode	opsional	parallel atau sequential. Default: parallel

curl -X POST \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Ijazah 2026","signing_mode":"parallel"}' \
  https://alphasign.pastibisa.app/api/v1/projects

Jawaban sukses: 201.

GET/projects/{id}

Detail proyek beserta dokumen dan penandatangannya.

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://alphasign.pastibisa.app/api/v1/projects/uuid-proyek

Kontak

Buku alamat organisasi. Fitur ini ada di paket bisnis (Prasasti ke atas). Kalau paket Anda belum punya kontak, server menjawab 403 dengan plan_required.

GET/contacts

Daftar kontak, diurutkan menurut nama. Parameter per_page: 1–100, default 50. Daftar ada di data.data.

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://alphasign.pastibisa.app/api/v1/contacts

POST/contacts

Tambah kontak. Email yang sama tidak boleh didaftarkan dua kali di organisasi Anda.

Isian (JSON)

name *	teks	Nama
email *	email	Alamat email
phone	opsional	Nomor telepon, maksimal 20 karakter
organization	opsional	Nama organisasi. Boleh juga memakai field company

curl -X POST \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Siti Aminah","email":"siti@contoh.co.id","company":"PT ABC"}' \
  https://alphasign.pastibisa.app/api/v1/contacts

Jawaban sukses: 201. Email duplikat: 422, dan kontak yang sudah ada dikirim di data.

Verifikasi

PUBLIK

Tidak perlu token. Siapa pun boleh memanggil endpoint ini.

GET/verify/{hash}

Cek dokumen yang sudah selesai ditandatangani. Isi {hash} boleh hash lengkap, potongan awal hash (paling banyak 12 karakter), atau ID dokumen (UUID).

curl https://alphasign.pastibisa.app/api/v1/verify/abc123def456

Jawaban 200 — dokumen ketemu

{
  "success": true,
  "status": "valid",
  "document": {
    "title": "Kontrak Kerja",
    "hash": "…",
    "signed_at": "2026-06-15T10:00:00+00:00",
    "status": "completed"
  },
  "signers": [{
    "name": "Budi",
    "role": "Direktur",
    "organization": "PT Contoh",
    "signed_at": "2026-06-15T10:00:00+00:00",
    "status": "signed"
  }],
  "issuer": { "name": "PT Contoh", "domain": null },
  "integrity": { "file_exists": true, "hash_matches": true, "all_signatures_valid": true }
}

status bernilai valid atau tampered (file berubah setelah ditandatangani).

Jawaban 404 — tidak ketemu

{
  "success": false,
  "status": "invalid",
  "reason": "document_not_found",
  "message": "Dokumen dengan hash ini tidak ditemukan dalam sistem."
}

Contoh kode

Jalankan di server. Jangan kirim token ke browser.

PHP

$response = Http::withToken('TOKEN')
  ->get('https://alphasign.pastibisa.app/api/v1/me');
$data = $response->json();

Python

import requests
r = requests.get(
  "https://alphasign.pastibisa.app/api/v1/me",
  headers={"Authorization": "Bearer TOKEN"}
)

Node.js

// Hanya di server — jangan kirim token ke browser
const res = await fetch(
  `https://alphasign.pastibisa.app/api/v1/me`,
  { headers: { Authorization: `Bearer TOKEN` }}
);