# VERIXID REST API DOCUMENTATION

Dokumentasi resmi integrasi REST API VerixID untuk pendaftaran (*submit*) dan verifikasi *record* bukti matematis dokumen digital[cite: 8]. API ini mengusung prinsip **Zero-Custody**; hanya pemrosesan *fingerprint* (SHA-256 hash) tanpa pernah menerima atau menyimpan file fisik[cite: 8].

---

## SPESIFIKASI UMUM & AUTENTIKASI

| Parameter | Spesifikasi |
| :--- | :--- |
| **Base URL** | `https://api.verixid.com`[cite: 8] |
| **Autentikasi Header** | `X-Secure-Key: <64-karakter-api-key>`[cite: 8] |
| **Format Key** | 64 karakter alfanumerik (`A-Z`, `a-z`, `0-9`), *case-sensitive*[cite: 8] |
| **Ukuran Maksimum Payload** | 10 KB[cite: 8] |
| **Rate Limit** | 20 request / menit[cite: 8] |

---

## ENDPOINT API

### 1. Mendaftarkan File (`POST /submit`)
Mendaftarkan *fingerprint* file baru ke dalam *ledger*[cite: 8].

* **URL Path:** `/submit`[cite: 8]
* **Method:** `POST`[cite: 8]
* **Headers:**
  ```http
  Content-Type: application/json
  X-Secure-Key: <api-key>
  ```[cite: 8]

#### Request Body
| Field | Tipe | Wajib | Aturan / Deskripsi |
| :--- | :--- | :--- | :--- |
| `hash` | String | Ya | SHA-256 hex string, 64 karakter (dihitung di sisi *client*)[cite: 8]. |

**Contoh Body:**
```json
{
  "hash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"
}
```[cite: 8]

#### Response
* **`201 Created` (Berhasil):**
  ```json
  {
    "record_id": "vx202607026731ce",
    "server_timestamp": "2026-07-21T12:54:59.469Z",
    "receipt_signature": "...",
    "ownership_key": "..."
  }
  ```[cite: 8]
* **`409 Conflict`:** Terjadi jika hash sudah pernah terdaftar sebelumnya[cite: 8].

---

### 2. Verifikasi Record (`GET /verify`)
Memverifikasi keberadaan dan kepemilikan *record*[cite: 8]. Endpoint ini terbuka untuk publik yang memiliki `record_id`[cite: 8].

* **URL Path:** `/verify`[cite: 8]
* **Method:** `GET`[cite: 8]
* **Query Parameters:**
  * `id` (Wajib): Format `vx` + `YYYYMM` + 8 karakter hex (Contoh: `vx202607a1b2c3d4`)[cite: 8].
  * `ownership_key` (Opsional): 64 karakter hex untuk membuka *proof* kepemilikan[cite: 8].

#### Perilaku Response

* **Mode Public Check (Tanpa `ownership_key`):**
  Mengembalikan 16 karakter awal hash (`hash_preview`) untuk mencegah penelusuran publik secara acak (*brute-force*)[cite: 8].
  ```json
  {
    "record_id": "vx202607a1b2c3d4",
    "registered_at": 1784375908188,
    "hash_preview": "f8bd8b98730d5c19...",
    "ownership_verified": false
  }
  ```[cite: 8]

* **Mode Ownership Proof (Dengan `ownership_key` Valid):**
  Mengembalikan hash lengkap (64 karakter hex) dan `ed25519_signature` (128 karakter hex / 64 byte) yang dapat diverifikasi secara independen[cite: 8].
  ```json
  {
    "record_id": "vx202607a1b2c3d4",
    "registered_at": 1784375908188,
    "hash_preview": "d5fc7d44cb58413b2c9d9c4e66722a031080279d9c25c9bb88f6c2e0d17439fb",
    "ed25519_signature": "4b6bd41e1dc082fa02f4081374...",
    "ownership_verified": true
  }
  ```[cite: 8]

* **`404 Not Found`:** Terjadi jika `record_id` tidak ditemukan pada *ledger*[cite: 8].

---

## CONTOH IMPLEMENTASI (cURL)

### Submit File Fingerprint
```bash
curl -X POST [https://api.verixid.com/submit](https://api.verixid.com/submit) \
  -H "X-Secure-Key: <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "hash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"
  }'
```[cite: 8]

### Verifikasi Publik
```bash
curl "[https://api.verixid.com/verify?id=vx202607a1b2c3d4](https://api.verixid.com/verify?id=vx202607a1b2c3d4)" \
  -H "X-Secure-Key: <api-key>"
```[cite: 8]

### Verifikasi Kepemilikan (Ownership Proof)
```bash
curl "[https://api.verixid.com/verify?id=vx202607a1b2c3d4&ownership_key=](https://api.verixid.com/verify?id=vx202607a1b2c3d4&ownership_key=)<64-hex-key>" \
  -H "X-Secure-Key: <api-key>"
```[cite: 8]

---

## SKEMA ERROR HANDLER

Semua respon kesalahan dikembalikan dalam format JSON standar berikut[cite: 8]:

```json
{
  "code": "invalid_hash",
  "title": "Invalid Hash",
  "status": 400,
  "detail": "Hash must be a SHA-256 hex string (64 characters)."
}
```[cite: 8]

### Daftar Kode Error API

| Code | HTTP Status | Keterangan / Penyebab |
| :--- | :--- | :--- |
| `unauthorized` | 401 | API key kosong, salah format, atau tidak terdaftar[cite: 8]. |
| `billing_expired` | 402 | Akun ditangguhkan (*suspend*) atau periode *billing* berakhir[cite: 8]. |
| `invalid_json` | 400 | Format *request body* bukan JSON valid[cite: 8]. |
| `invalid_hash` | 400 | Nilai `hash` bukan SHA-256 hex 64 karakter[cite: 8]. |
| `invalid_id` | 400 | Format `id` record tidak valid[cite: 8]. |
| `invalid_key` / `invalid_ownership_key` | 400 | Nilai `ownership_key` bukan hex 64 karakter[cite: 8]. |
| `payload_too_large` | 400 | Ukuran *request body* melebihi batas 10 KB[cite: 8]. |
| `quota_exceeded` | 429 | Kuota bulanan habis[cite: 8]. |
| `rate_limit_exceeded` | 429 | Batas frekuensi melebihi 20 request / menit[cite: 8]. |
| `method_not_allowed` | 405 | Method HTTP yang digunakan salah[cite: 8]. |
| `not_found` | 404 | Endpoint / path tidak ditemukan[cite: 8]. |
| `upstream_error` | 502 | Gangguan pada layanan internal[cite: 8]. |
| `internal_error` | 500 | Kesalahan internal server[cite: 8]. |

---

## PRINSIP UTAMA SISTEM

* **Zero-Custody:** File asli tidak pernah dikirim atau disimpan di server VerixID[cite: 8].
* **Verify, Don't Trust:** Setiap hasil verifikasi bersifat deterministik dan dapat diuji secara mandiri menggunakan SHA-256 + Ed25519 Public Key resmi (`/.well-known/verixid-public-key.pem`)[cite: 8].
* **Append-Only Ledger:** *Record* yang telah berhasil terdaftar bersifat permanen dan tidak dapat diubah atau dihapus[cite: 8].

---

## METADATA DAN LEGALITAS

* **Entitas Pengelola:** PT Verix Identitas Digital (VerixID)[cite: 8]
* **Izin PSE Komdigi:** `022901.01/DJAI.PSE/04/2026`[cite: 8]
* **Landasan Hukum:** SELARAS UU ITE (jo. UU No. 1/2024), PP PSTE, UU PDP[cite: 8]

### Navigasi Terkait
* **AI Integration (MCP Server):** `/docs/mcp/`[cite: 8]
* **Cryptographic Public Key Verification:** `/docs/verification/`[cite: 8]
* **Overview Dokumentasi:** `/docs/`[cite: 8]