Belajar Technical Product Manager - APIs & Platform Products

#Pendahuluan

Setelah di episode 5 kalian menulis PRD teknis settlement T+0 dengan NFR terukur dan acceptance criteria testable, episode ini membahas wilayah kerja yang paling khas TPM: produk API. Di NusaPay, produk utama bukan aplikasi web — melainkan API yang dipakai ribuan developer merchant.

Kenapa API layak dibahas sebagai topik tersendiri? Karena aturan mainnya berbeda dari produk konsumen: user kalian adalah developer yang menghakimi produk lewat dokumentasi, konsistensi, dan pesan error. Mereka tidak bisa "dipujuk" UX visual — API yang jelek langsung terlihat jelek. Dan begitu developer terintegrasi, biaya mereka berpindah sangat tinggi: kesalahan desain hari ini menjadi beban yang mereka bawa bertahun-tahun.

#Developer Adalah User Anda

Ubah mental model: semua disiplin product management tetap berlaku, hanya objeknya berganti.

Metrik onboarding API bernama time to first call (TTFC): waktu dari daftar akun sampai request pertama berhasil di sandbox. Inilah "aha moment" produk API, dan kita bedah mendalam di episode 15 tentang DX.

#Prinsip Desain yang Menjaga Konsistensi

Konsistensi adalah fitur nomor satu produk API. Empat keputusan yang harus seragam di seluruh endpoint:

1. Penamaan resource: kata benda jamak, POST /v1/virtual-accounts, bukan /createVA.
2. Konvensi method: GET baca, POST buat, PATCH ubah parsial, DELETE hapus — tanpa kejutan.
3. Pagination: format sama di semua list endpoint (cursor-based untuk data besar).
4. Format waktu: UTC ISO 8601 di mana-mana; zona waktu lokal adalah urusan client.

Pelanggaran kecil terasa sepele saat dirancang, tetapi developer yang integrasi 20 endpoint akan merasakan setiap inkonsistensi sebagai pajak kognitif.

#Idempotency: Kebutuhan Khusus Produk Pembayaran

Di payment, jaringan bisa putus setelah request terkirim. Developer mencoba ulang — dan tanpa perlindungan, uang nasabah terpotong dua kali. Solusinya idempotency key: developer mengirim identifier unik per intent, dan server menjamin request ulang dengan key sama tidak menciptakan efek ganda.

curl -X POST https://api.nusapay.id/v1/virtual-accounts \
  -H "Authorization: Bearer $NUSAPAY_KEY" \
  -H "Idempotency-Key: order-88123-attempt-1" \
  -d '{
        "merchant_id": "MID-204",
        "amount": 150000,
        "expires_at": "2026-09-01T23:59:59Z"
      }'

Sebagai TPM, idempotency bukan detail engineering — ia janji produk: "integrasi kamu aman dari duplikasi". Ia harus muncul di docs, di SDK, di onboarding, dan di sales deck ke merchant besar.

#Kontrak Error yang Manusiawi

Pesan error adalah momen paling emosional produk API. Kontrak yang baik punya struktur stabil:

{
  "error": {
    "code": "insufficient_balance",
    "message": "Merchant balance is not enough for this payout.",
    "doc_url": "https://docs.nusapay.id/errors#insufficient_balance",
    "request_id": "req_9f2c81"
  }
}

Tiga unsur yang membuat error bisa diatasi sendiri oleh developer: kode mesin yang stabil (insufficient_balance, bukan string bebas), pesan manusia yang menyebut penyebab, dan tautan dokumentasi plus request_id untuk support. Setiap error baru yang kalian approve di PRD harus lolos uji tiga syarat itu — inilah cara TPM ikut menjaga DX tanpa menulis kode.

#Breaking Change & Versioning

Developer telah menginvestasikan waktu mengintegrasikan API kalian; mengubah kontrak sembarangan adalah pengkhianatan terhadap investasi itu. Kebijakan standar industri:

• Perubahan additive (field baru opsional, endpoint baru): boleh kapan saja tanpa naik versi.
• Breaking change (hapus field, ubah makna response): wajib versi baru, misal /v2/.
• Sunset policy: versi lama hidup minimal 12 bulan setelah pengumuman, dengan header peringatan sejak H-90 hari.

2026-09-01  v1 payout endpoints -> SUNSET announced
            v1 will keep working until at least 2027-09-01.
            Deprecation headers active from 2026-12-01.
            Migration guide: docs.nusapay.id/migrations/v1-to-v2

TPM yang baik mengelola migrasi versi sebagai proyek produk kecil: panduan migrasi, tooling diff, dan komunikasi berkala — persis pola yang kita dalami di episode 11 tentang migration initiatives.

#Platform Economics

API adalah produk dengan mekanika komersial khas. Untuk NusaPay, model pendapatan utama:

• Take rate: potongan persentase per transaksi berhasil — revenue tumbuh seiring GMV merchant.
• Biaya tetap per transaksi: flat fee untuk payout massal bernilai besar.
• Tier subscription: merchant enterprise membayar bulanan untuk SLA, support prioritas, dan fitur governance (episode 20).

Keputusan pricing API selalu menyangkut insentif perilaku: harga per call mendorong efisiensi integrasi, sedangkan harga per transaksi menyelaraskan keberhasilan merchant dengan pendapatan kalian. Pilih yang perilaku yang ingin kalian dorong.

#Praktik: API Product One-Pager

Tulis one-pager untuk endpoint baru GET /v1/settlements (merchant cek status settlement sendiri, mengurangi tiket support): persona developer yang dilayani, contoh request-response, daftar error code beserta pesannya, dampak ke metrik (target: tiket "kapan dana cair" turun 40%), dan rencana rollout beta. Simpan di 03-specs/.

#Penutup

Inti yang harus dibawa pulang:

• Produk API = produk biasa dengan developer sebagai user; TTFC adalah aha moment-nya.
• Konsistensi penamaan, method, pagination, dan format waktu adalah fitur, bukan gaya.
• Idempotency key adalah janji keamanan integrasi — kenali sebagai keputusan produk, bukan detail teknis.
• Error envelope yang baik punya kode stabil, pesan manusia, doc_url, dan request_id.
• Kelola breaking change lewat versioning + sunset policy; pricing API mengikuti perilaku yang ingin didorong.

Di episode 7 selanjutnya kita bicara Data-Informed Product Decisions — membangun metric framework yang menggabungkan metrik teknis (latency, reliability) dengan metrik produk (activation, retention), sehingga setiap keputusan roadmap NusaPay punya dasar angka. Sampai jumpa!