Panduan Migrasi Laravel → Go

Backbone Sarana sedang dipindah dari Laravel ke Go. Integrasi lama (mis. app Smart/Sekolah) yang memanggil backbone Laravel bisa cutover tanpa mengubah kode endpoint — cukup arahkan base URL ke surface Go, karena semua path lama dipertahankan sebagai alias kompatibilitas.

Ada satu perubahan yang wajib diperhatikan: beberapa endpoint mutasi yang di Laravel dulu terbuka tanpa autentikasi, kini wajib API key (lihat §3).

1. Perubahan base URL

Surface publik/legacy Go berada di /api/v3. Path setelah base tetap sama seperti Laravel /api/v1.

	Lama (Laravel)	Baru (Go)
Base URL	`…/api/v1`	`…/api/v3`
Contoh	`…/api/v1/withdrawal`	`…/api/v3/withdrawal`

Base URL baru (production): https://api.internal.saranatechnology.com/api/v3
Sandbox (uji coba, tanpa uang nyata): https://api.internal-go.saranatechnology.com/api/v3
Health check: GET /api/v3/health

Integrasi server-to-server baru sebaiknya langsung pakai surface developer /api/v2 (lihat Dokumentasi Developer). /api/v3 fokus untuk cutover integrasi lama agar tidak perlu refactor path.

2. Pemetaan path legacy (alias)

Semua path lama tetap dilayani. Boleh dipakai apa adanya; padanan "kanonik" Go ada di kolom kanan bila nanti ingin dirapikan.

Path legacy (tetap jalan)	Padanan kanonik Go	Auth
`GET /banks`, `GET /bank`	`GET /bank-channels`	—
`GET /plan`, `GET /plan/{id}`	`GET /plans`, `/plans/{id}`	—
`GET /subsription`, `/subsription/last`	`GET /subscriptions`, `/subscriptions/last`	—
`POST /subsription`	`POST /subscriptions`	—
`GET /client/{id}`, `/client/{id}/balance`	`GET /clients/{id}`, `/clients/{id}/balance`	—
`GET /withdrawal`, `/withdrawal/{id}`	`GET /withdrawals`, `/withdrawals/{id}`	—
`POST /withdrawal`	`POST /withdrawals`	—
`POST /transaction`, `/transactions`	rekam transaksi	API key (§3)
`DELETE /withdrawal/{id}`, `/withdrawals/{id}`	hapus penarikan pending	API key (§3)
`POST /clients/{id}`	update data client sendiri	API key (§3)

Webhook Xendit tidak berubah — tetap di /api/v1/callback/* (URL sudah terdaftar di dashboard Xendit).

3. Endpoint mutasi legacy — kini wajib API key

Di Laravel endpoint mutasi ini terbuka tanpa auth. Di Go semuanya wajib API key supaya identitas client jelas dan tidak bisa dipalsukan. client_id diambil dari key — tidak dikirim di body/path, dan Anda hanya bisa menyentuh data milik sendiri.

Sertakan header di setiap request:

X-API-Key: sk_live_<key-anda>

Cara mendapatkan key: lihat Dokumentasi Developer §1.

3.1 Rekam transaksi — `POST /api/v3/transaction`

Meng-upsert transaksi berdasarkan transaction_id. Saat status berhasil (berhasil/paid), saldo client ditambah net_payment dan selisih total − net_payment dicatat sebagai fee. Idempoten: memanggil ulang dengan payload sukses yang sama tidak menambah saldo dua kali (berbeda dari perilaku Laravel lama).

curl -X POST .../api/v3/transaction \
  -H "X-API-Key: $SARANA_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "transaction_id": "TRX-2026-0001",
    "external_id": "INV-XYZ-1",
    "total": 150000,
    "net_payment": 145000,
    "status": "berhasil"
  }'

Field	Wajib	Catatan
`transaction_id`	✅	Kunci upsert
`total`	—	Nominal kotor
`net_payment`	—	Nominal bersih yang menambah saldo saat sukses
`status`	—	`berhasil`/`paid` memicu kredit saldo + catat fee
`external_id`	—	Referensi eksternal

3.2 Hapus penarikan — `DELETE /api/v3/withdrawal/{id}`

Menghapus penarikan hanya bila statusnya masih pending dan milik client Anda. Selain itu ditolak (400/403).

curl -X DELETE .../api/v3/withdrawal/123 \
  -H "X-API-Key: $SARANA_API_KEY"

Kode	Arti
`200`	Terhapus
`403`	Penarikan bukan milik client ini
`400`	Status bukan `pending` (tidak boleh dihapus)
`404`	Tidak ditemukan

3.3 Update data client — `POST /api/v3/clients/{id}`

Memperbarui data client (nama, alamat, PIC, norek/bank, dll.). {id} wajib sama dengan client pemilik API key — key hanya boleh mengubah datanya sendiri; menyasar client lain ditolak 403. Hanya field yang dikirim yang diubah; field yang dihilangkan dibiarkan apa adanya.

curl -X POST .../api/v3/clients/45 \
  -H "X-API-Key: $SARANA_API_KEY" -H "Content-Type: application/json" \
  -d '{ "no_telp_pic": "08123456789", "norek": "1234567890", "bank": "BCA" }'

Kode	Arti
`200`	Terupdate
`403`	`{id}` bukan client pemilik API key
`404`	Client tidak ditemukan

Field sensitif gateway (xendit_customer_secret, xendit_token) tidak pernah dikembalikan di response manapun.

4. Checklist cutover

Ganti base URL …/api/v1 → …/api/v3.
Terbitkan API key untuk client, pasang header X-API-Key pada POST /transaction, DELETE /withdrawal/{id}, dan POST /clients/{id}.
Uji tiap endpoint di staging — bandingkan bentuk response (bukan cuma status 200) terhadap perilaku Laravel lama.
Cutover produksi, pantau, siapkan rollback (arahkan base URL balik ke Laravel bila perlu).

Referensi lengkap request/response: Swagger /api/v3/docs dan /api/v3/docs/openapi.yaml. Untuk integrasi baru, pakai /api/v2 (Dokumentasi Developer).