{"openapi":"3.0.3","info":{"title":"Tako Public API","description":"Dokumentasi publik REST API Tako untuk kirim hadiah dan top up lewat API Key.","version":"1.0.0","contact":{"name":"Tako","url":"https://tako.id"},"termsOfService":"https://help.tako.id/en/article/terms-and-conditions-17g4q8/"},"servers":[{"url":"https://tako.id","description":"Current environment"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API Key dari dashboard Tako, dikirim sebagai `Authorization: Bearer <api-key>`."}},"schemas":{},"parameters":{}},"paths":{"/api/v1/gift/{username}":{"post":{"tags":["Gift"],"summary":"Mengirim Hadiah","description":"Membuat hadiah ke akun kreator {username}. Body dapat dikirim sebagai application/json atau multipart/form-data. Callback URL dan Redirect URL untuk pembayaran yang dibuat lewat endpoint ini diatur di dashboard API Key (/me/api-keys), lihat bagian \"Callback & Redirect URL\" di bawah.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"username","in":"path"},{"schema":{"type":"string","description":"Wajib. Request tanpa header ini ditolak dengan status 403. Endpoint ini juga menolak dengan status 400 di level aplikasi jika header kosong."},"required":true,"name":"User-Agent","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Nama pengirim hadiah","example":"Budi"},"email":{"type":"string","format":"email","example":"budi@email.com"},"amount":{"type":"number","nullable":true,"maximum":50000000,"example":50000},"paymentMethod":{"type":"string","enum":["qris","gopay","dana","paypal"],"description":"Metode pembayaran. Wajib, pembayaran dari saldo tidak tersedia untuk API Key."},"message":{"type":"string","maxLength":200}},"required":["name","email","amount","paymentMethod"]}}}},"responses":{"206":{"description":"Hadiah dibuat, perlu pembayaran. Arahkan pengirim ke paymentUrl untuk menyelesaikan. Pembayaran via saldo hanya untuk sesi login, bukan API Key.","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"number","enum":[206]},"result":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"giftId":{"type":"string","format":"uuid"},"transactionId":{"type":"string","format":"uuid"},"paymentUrl":{"type":"string","format":"uri"}},"required":["success","giftId","transactionId","paymentUrl"]}},"required":["statusCode","result"]}}}},"400":{"description":"Request atau data tidak valid (mis. jumlah, media, atau opsi hadiah).","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"number","enum":[400]},"error":{"type":"object","properties":{"name":{"type":"string","enum":["Error"]},"message":{"type":"string","enum":["Jumlah hadiah harus lebih dari 0"]}},"required":["name","message"]}},"required":["statusCode","error"]}}}},"401":{"description":"API Key tidak valid atau telah dicabut.","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"number","enum":[401]},"error":{"type":"object","properties":{"name":{"type":"string","enum":["Error"]},"message":{"type":"string","enum":["API Key tidak valid atau telah dicabut"]}},"required":["name","message"]}},"required":["statusCode","error"]}}}},"403":{"description":"Pengiriman ditolak (diblokir kreator, IP abuser, atau tidak diizinkan).","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"number","enum":[403]},"error":{"type":"object","properties":{"name":{"type":"string","enum":["Error"]},"message":{"type":"string","enum":["Kamu tidak dapat mengirim hadiah ke kreator ini"]}},"required":["name","message"]}},"required":["statusCode","error"]}}}},"404":{"description":"Kreator tujuan tidak ditemukan.","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"number","enum":[404]},"error":{"type":"object","properties":{"name":{"type":"string","enum":["Error"]},"message":{"type":"string","enum":["Kreator tidak ditemukan"]}},"required":["name","message"]}},"required":["statusCode","error"]}}}},"429":{"description":"Terlalu sering. Beri jeda sebelum mengirim hadiah lagi.","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"number","enum":[429]},"error":{"type":"object","properties":{"name":{"type":"string","enum":["Error"]},"message":{"type":"string","enum":["Mohon tunggu beberapa saat sebelum mengirim hadiah lagi"]}},"required":["name","message"]}},"required":["statusCode","error"]}}}},"500":{"description":"Kesalahan server saat memproses hadiah.","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"number","enum":[500]},"error":{"type":"object","properties":{"name":{"type":"string","enum":["Error"]},"message":{"type":"string","enum":["Gagal mengirim hadiah"]}},"required":["name","message"]}},"required":["statusCode","error"]}}}}}}},"/api/v1/gift/{giftId}":{"get":{"tags":["Gift"],"summary":"Status Hadiah","description":"Mengambil detail dan status hadiah berdasarkan {giftId}. API Key hanya dapat melihat hadiah yang dibuat dengan key yang sama.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"giftId","in":"path"},{"schema":{"type":"string","description":"Wajib. Request tanpa header ini ditolak dengan status 403."},"required":true,"name":"User-Agent","in":"header"}],"responses":{"200":{"description":"Detail hadiah.","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"number","enum":[200]},"result":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["pending","success","failed","reversed","on_hold"]},"type":{"type":"string"},"amount":{"type":"number"},"message":{"type":"string","nullable":true},"currency":{"type":"string","nullable":true},"gifterName":{"type":"string"},"gifterEmail":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","status","type","amount","message","currency","gifterName","gifterEmail","createdAt"]}},"required":["statusCode","result"]}}}},"401":{"description":"API Key tidak valid atau tidak diberikan.","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"number","enum":[401]},"error":{"type":"object","properties":{"name":{"type":"string","enum":["Error"]},"message":{"type":"string","enum":["Kamu tidak memiliki akses untuk melihat hadiah ini"]}},"required":["name","message"]}},"required":["statusCode","error"]}}}},"404":{"description":"Hadiah tidak ditemukan atau bukan milik key ini.","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"number","enum":[404]},"error":{"type":"object","properties":{"name":{"type":"string","enum":["Error"]},"message":{"type":"string","enum":["Hadiah tidak ditemukan"]}},"required":["name","message"]}},"required":["statusCode","error"]}}}}}}},"/api/v1/topup/{username}":{"post":{"tags":["Topup"],"summary":"Top Up","description":"Membuat transaksi top up saldo ke akun kreator {username}. Memerlukan akses keuangan (finance) atas akun tersebut. Callback URL dan Redirect URL untuk pembayaran yang dibuat lewat endpoint ini diatur di dashboard API Key (/me/api-keys), lihat bagian \"Callback & Redirect URL\" di bawah.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"username","in":"path"},{"schema":{"type":"string","description":"Wajib. Request tanpa header ini ditolak dengan status 403."},"required":true,"name":"User-Agent","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"paymentMethod":{"type":"string","enum":["qris","gopay","dana","paypal"]},"amount":{"type":"number","nullable":true,"maximum":50000000,"description":"Wajib jika tanpa productId"},"productId":{"type":"string","description":"id paket top up"},"discountCode":{"type":"string"}},"required":["paymentMethod"]}}}},"responses":{"201":{"description":"Transaksi dibuat. Arahkan ke paymentUrl untuk membayar.","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"number","enum":[201]},"result":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"transactionId":{"type":"string","format":"uuid"},"paymentUrl":{"type":"string","format":"uri"},"transaction":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["pending","success","failed","reversed","on_hold"]},"amount":{"type":"number"},"price":{"type":"number"},"paymentMethod":{"type":"string"},"paymentUrl":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"}},"required":["id","status","amount","price","paymentMethod","paymentUrl","createdAt"]}},"required":["success","transactionId","paymentUrl","transaction"]}},"required":["statusCode","result"]}}}},"400":{"description":"Request atau data tidak valid (mis. harga atau format body).","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"number","enum":[400]},"error":{"type":"object","properties":{"name":{"type":"string","enum":["Error"]},"message":{"type":"string","enum":["Data tidak valid"]}},"required":["name","message"]}},"required":["statusCode","error"]}}}},"401":{"description":"API Key tidak valid atau telah dicabut.","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"number","enum":[401]},"error":{"type":"object","properties":{"name":{"type":"string","enum":["Error"]},"message":{"type":"string","enum":["Kamu harus masuk ke akunmu untuk melakukan pengisian ulang"]}},"required":["name","message"]}},"required":["statusCode","error"]}}}},"403":{"description":"Tidak punya akses keuangan atas akun kreator tujuan, atau akun tersebut sedang diblokir.","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"number","enum":[403]},"error":{"type":"object","properties":{"name":{"type":"string","enum":["Error"]},"message":{"type":"string","enum":["Kamu tidak memiliki akses keuangan untuk akun kreator ini"]}},"required":["name","message"]}},"required":["statusCode","error"]}}}},"404":{"description":"Akun kreator atau produk top up tidak ditemukan.","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"number","enum":[404]},"error":{"type":"object","properties":{"name":{"type":"string","enum":["Error"]},"message":{"type":"string","enum":["Akun kreator tidak ditemukan"]}},"required":["name","message"]}},"required":["statusCode","error"]}}}},"429":{"description":"Terlalu sering. Beri jeda sebelum top up lagi.","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"number","enum":[429]},"error":{"type":"object","properties":{"name":{"type":"string","enum":["Error"]},"message":{"type":"string","enum":["Mohon tunggu beberapa saat sebelum melakukan pengisian ulang lagi"]}},"required":["name","message"]}},"required":["statusCode","error"]}}}},"500":{"description":"Kesalahan server saat membuat pembayaran.","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"number","enum":[500]},"error":{"type":"object","properties":{"name":{"type":"string","enum":["Error"]},"message":{"type":"string","enum":["Terjadi kesalahan saat membuat pembayaran"]}},"required":["name","message"]}},"required":["statusCode","error"]}}}}}}},"/api/v1/transactions/{transactionId}":{"get":{"tags":["Transaction"],"summary":"Status Transaksi","description":"Mengambil detail dan status transaksi pembayaran berdasarkan {transactionId}. Hanya dapat diakses oleh pembuat transaksi.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"transactionId","in":"path"},{"schema":{"type":"string","description":"Wajib. Request tanpa header ini ditolak dengan status 403."},"required":true,"name":"User-Agent","in":"header"}],"responses":{"200":{"description":"Detail transaksi.","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"number","enum":[200]},"result":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["pending","success","failed","reversed","on_hold"]},"amount":{"type":"number"},"price":{"type":"number"},"paymentMethod":{"type":"string"},"paymentUrl":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"}},"required":["id","status","amount","price","paymentMethod","paymentUrl","createdAt"]}},"required":["statusCode","result"]}}}},"401":{"description":"API Key tidak valid atau bukan milikmu.","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"number","enum":[401]},"error":{"type":"object","properties":{"name":{"type":"string","enum":["Error"]},"message":{"type":"string","enum":["Kamu tidak memiliki akses untuk melihat transaksi ini"]}},"required":["name","message"]}},"required":["statusCode","error"]}}}},"404":{"description":"Transaksi dengan id tersebut tidak ditemukan.","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"number","enum":[404]},"error":{"type":"object","properties":{"name":{"type":"string","enum":["Error"]},"message":{"type":"string","enum":["Transaksi tidak ditemukan"]}},"required":["name","message"]}},"required":["statusCode","error"]}}}}}}}}}