Kontrak API FPDP (Bahasa Indonesia)

1. Cakupan dan status

Dokumen ini mendefinisikan kontrak HTTP target untuk MVP FPDP. Ini adalah kontrak desain; repository saat ini belum mengimplementasikan sebagian besar route. Sumber machine-readable tersedia pada <code>openapi.yaml</code>.

Base path: /api/v1

Autentikasi:

- pembacaan data publik tidak membutuhkan autentikasi;

- operasi owner/admin memakai Authorization: Bearer <token>;

- webhook pembayaran memakai signature khusus provider dan tidak memakai bearer token pengguna.

Content type: application/json, kecuali body webhook dapat mengikuti format JSON provider.

2. Konvensi umum

- ID yang diekspos API berupa UUID string.

- Timestamp memakai RFC 3339 UTC.

- Nilai uang berupa decimal string dan kode currency ISO 4217 untuk mencegah kesalahan floating point.

- Collection memakai cursor pagination: data, meta.next_cursor, dan meta.has_more.

- Resource mutable mengembalikan ETag ketika optimistic concurrency tersedia.

- Setiap konten mengidentifikasi source_type, source_provider, dan canonical_url.

- Retry pembuatan pembayaran harus memakai header Idempotency-Key yang sama.

Envelope sukses standar:

{"data": {}, "meta": {"request_id": "req_..."}}

Envelope error standar:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Permintaan tidak valid.",
    "details": [{"field": "email", "reason": "invalid_format"}],
    "request_id": "req_..."
  }
}

3. Daftar endpoint

Sistem dan autentikasi

| Method | Path | Auth | Kegunaan |

|---|---|---|---|

| GET | /health | Publik | Status hidup aplikasi dan ringkasan dependency |

| POST | /auth/register | Publik | Mendaftarkan owner dan node awal |

| POST | /auth/login | Publik | Menukar credential dengan access token. Bila 2FA aktif: {mfa_required: true, mfa_token, expires_in: 300} sebagai gantinya, tanpa token |

| POST | /auth/login/verify | Publik | {mfa_token, code} (kode 6 digit atau kode pemulihan) → respons sama seperti login tanpa 2FA. 5 kode salah mengakhiri tantangan (401) |

| POST | /auth/logout | Bearer | Mencabut token aktif |

| GET | /me | Bearer | Mengambil user dan konteks node aktif |

| GET | /me/sessions | Bearer | Perangkat yang sedang masuk (id, perangkat, IP terpotong, waktu masuk/terakhir aktif, current) |

| DELETE | /me/sessions/{id} | Bearer | Keluarkan satu perangkat lain (perangkat ini: pakai logout) |

| POST | /me/sessions/revoke-others | Bearer | Keluarkan semua perangkat lain; mengembalikan revoked |

| POST | /me/password | Bearer | {current_password, new_password}; mengeluarkan semua perangkat lain |

| GET | /me/2fa | Bearer | {enabled, enabled_at, recovery_codes_remaining} |

| POST | /me/2fa/setup | Bearer | Secret sementara baru: {secret, otpauth_uri} untuk kode QR (409 bila sudah aktif) |

| POST | /me/2fa/confirm | Bearer | {code} → mengaktifkan 2FA; {recovery_codes[10], other_sessions_revoked}, hanya ditampilkan di sini |

| POST | /me/2fa/disable | Bearer | {password, code} (kode atau kode pemulihan) → status |

| POST | /me/2fa/recovery-codes | Bearer | {code} (hanya kode aplikasi) → {recovery_codes[10]}; set lama tidak berlaku |

Profil dan konten

| Method | Path | Auth | Kegunaan |

|---|---|---|---|

| GET | /profiles/{handle} | Publik | Membaca profil publik |

| PATCH | /me/profile | Bearer | Memperbarui profil owner |

| GET | /posts | Publik | Daftar post dengan filter sumber/visibility |

| POST | /posts | Bearer | Membuat post lokal |

| GET | /posts/{postId} | Publik | Membaca post yang dapat dilihat |

| PATCH | /posts/{postId} | Bearer | Memperbarui post lokal milik user |

| DELETE | /posts/{postId} | Bearer | Soft-delete post lokal milik user |

Penulisan post menerima maksimal 10 metadata media terurut (IMAGE, VIDEO, AUDIO, atau FILE). URL media wajib berupa URL HTTPS absolut tanpa credential tertanam; alternative text dibatasi 500 karakter. Mengirim media melalui PATCH mengganti seluruh daftar media secara atomik.

| GET | /timeline | Publik/Bearer opsional | Timeline normalisasi local, external, dan federated |

Sumber eksternal

| Method | Path | Auth | Kegunaan |

|---|---|---|---|

| GET | /external-sources | Bearer | Daftar koneksi dan kondisi sinkronisasi |

| POST | /external-sources/test | Bearer | Validasi dan preview tanpa menyimpan sumber |

| POST | /external-sources | Bearer | Menyimpan dan menjadwalkan sumber |

| GET | /external-sources/{sourceId} | Bearer | Membaca konfigurasi dan kondisi sumber |

| PATCH | /external-sources/{sourceId} | Bearer | Mengubah interval, visibility, atau status enabled |

| DELETE | /external-sources/{sourceId} | Bearer | Memutus sumber |

| POST | /external-sources/{sourceId}/sync | Bearer | Memasukkan sinkronisasi manual ke antrean |

Produk, order, dan pembayaran

| Method | Path | Auth | Kegunaan |

|---|---|---|---|

| GET | /products | Publik | Daftar produk tersedia |

| POST | /products | Bearer | Membuat produk lokal |

| GET | /products/{productId} | Publik | Membaca detail produk |

| PATCH | /products/{productId} | Bearer | Memperbarui produk milik user |

| GET | /products/{productId}/download | Visitor Bearer (order sudah dibayar) | Daftar unduhan: digital_asset_url dan file, masing-masing dengan download_url berlaku 15 menit |

| GET | /products/{productId}/digital-assets/{kind}/file | ?visitor=&expires=&token= (15 menit) | File-nya sendiri, untuk link biasa; pembelian diperiksa ulang |

| POST | /orders | Publik/Bearer opsional | Membuat order dan snapshot total immutable |

| GET | /orders/{orderId} | Bearer/order token | Membaca order |

| POST | /orders/{orderId}/payments | Bearer/order token | Membuat payment attempt; wajib Idempotency-Key |

| GET | /payments/{paymentId} | Bearer/order token | Membaca status pembayaran ternormalisasi |

| POST | /payments/{paymentId}/cancel | Bearer/order token | Membatalkan pembayaran pending |

| POST | /payments/{paymentId}/refunds | Admin Bearer | Meminta refund penuh atau sebagian |

| POST | /webhooks/payments/{gatewayCode} | Signature | Menerima dan menormalisasi event provider |

Yang sudah diimplementasikan untuk pengelolaan pembayaran oleh owner (Bearer owner) memakai path berikut:

| Method | Path | Kegunaan |

|---|---|---|

| GET | /me/payments/pending | Daftar pembayaran PENDING untuk dikonfirmasi manual |

| POST | /me/payments/{uuid}/confirm | Tandai PENDING sebagai PAID dan jalankan fulfillment |

| POST | /me/payments/{uuid}/cancel | Batalkan PENDING di gateway (bila ada API-nya) lalu lokal; menutup order terkait |

| POST | /me/payments/{uuid}/refund | Body {"amount"?: number, "manual"?: bool}; tanpa amount = refund penuh; manual: true mencatat refund yang dilakukan di luar gateway; refund penuh membatalkan fulfillment |

| POST | /me/payments/reconcile | Cek status PENDING lama ke provider dan pembayaran yang dibatalkan tapi ternyata dibayar |

| POST | /payments/webhook/{gateway} | Webhook provider (menggantikan /webhooks/payments/{gatewayCode} di atas) |

Administrasi dan federasi

| Method | Path | Auth | Kegunaan |

|---|---|---|---|

| GET | /admin/payment-gateways | Admin Bearer | Daftar kapabilitas dan status konfigurasi gateway |

| PUT | /admin/payment-gateways/{gatewayCode} | Admin Bearer | Mengatur dan mengaktifkan gateway |

| GET | /admin/integration-jobs | Admin Bearer | Memeriksa queue sinkronisasi dan kegagalan |

| POST | /admin/integration-jobs/{jobId}/retry | Admin Bearer | Mengulang job gagal |

| GET | /.well-known/fpdp | Publik | Discovery identitas dan kapabilitas node |

Order antar-node (FEDERATION-CONCEPT §11b)

| Method | Path | Auth | Kegunaan |

|---|---|---|---|

| POST | /federation/orders | HTTP Signature (actor pembeli) | fpdp:OrderRequest → 201 {order} (200 untuk pengiriman ulang dengan clientReference yang sama) |

| GET | /federation/orders/{orderId} | HTTP Signature (actor yang memesan) | Status order, item, dan — setelah dibayar — link unduhan |

| GET | /federation/orders/{orderId}/downloads/{productId}/{kind} | ?expires=&token= (15 menit) | File digital dari order yang sudah dibayar |

| GET | /me/fediverse-shop | Bearer | Produk dari akun yang diikuti; orderable bila penjual menerima order antar-node |

| GET | /me/purchases | Bearer | Pesanan owner di node lain |

| POST | /me/purchases | Bearer | {post_id, quantity, buyer_name, buyer_email, shipping_address, notes} → pembelian dengan payment_url; 409 beserta alasan penjual bila ditolak |

| POST | /me/purchases/{id}/refresh | Bearer | Membaca ulang status dari penjual (atau mengirim ulang order yang belum sampai) |

4. Perilaku penting

Pengujian dan penyimpanan sumber

POST /external-sources/test melakukan fetch server-side yang dibatasi, memblokir target network privat/reserved, menerapkan timeout dan batas ukuran, kemudian memberikan preview yang sudah dinormalisasi. Penyimpanan sumber merupakan aksi eksplisit yang terpisah.

Asal-usul timeline

Setiap item memuat:

- source_type: LOCAL, EXTERNAL, atau FEDERATED;

- source_provider: misalnya FPDP, RSS, ATOM, CUSTOM_API;

- canonical_url: URL original yang otoritatif;

- identitas author dan waktu publikasi.

Idempotency pembayaran dan webhook

- Client menggunakan satu Idempotency-Key untuk retry permintaan pembayaran logis yang sama.

- Server mengembalikan hasil pertama ketika key dan payload sama.

- Key yang sama dengan payload berbeda menghasilkan 409 IDEMPOTENCY_CONFLICT.

- Webhook diverifikasi sebelum diproses dan dideduplikasi berdasarkan provider + event ID.

- Webhook duplikat yang valid menghasilkan 200 tanpa menjalankan transisi dua kali.

Status code yang disarankan

| Status | Arti |

|---|---|

| 200 | Pembacaan/update berhasil atau webhook duplikat diterima |

| 201 | Resource berhasil dibuat |

| 202 | Sinkronisasi/refund async diterima |

| 204 | Logout atau penghapusan selesai |

| 400 | Request malformed |

| 401 | Autentikasi atau signature webhook tidak ada/tidak valid |

| 403 | Terautentikasi tetapi tidak memiliki izin |

| 404 | Resource tidak ada atau tidak dapat dilihat |

| 409 | Konflik state atau idempotency |

| 422 | Validasi semantik gagal |

| 429 | Rate limit terlampaui |

| 502 | Provider upstream gagal |