USD Coin (USDC) telah muncul sebagai landasan stabilitas dan keandalan. Sebagai stablecoin yang didukung dolar dan dicadangkan penuh, USDC menjembatani kesenjangan antara mata uang fiat tradisional dan dunia aset digital yang berkembang pesat. Ini menawarkan kecepatan dan jangkauan global mata uang kripto sambil mempertahankan stabilitas harga dolar AS, menjadikannya media yang ideal untuk perdagangan, jual beli, dan pengiriman uang di internet.
Inti dari ekosistem USDC adalah Circle, pengembang utama stablecoin. Circle menyediakan serangkaian API yang memberdayakan pengembang dan bisnis untuk mengintegrasikan USDC ke dalam aplikasi mereka dengan mulus. Circle Mint API, khususnya, menawarkan gerbang yang kuat untuk mencetak USDC baru, menukarkannya dengan mata uang fiat, dan mentransfernya ke berbagai blockchain yang didukung. Ini bukanlah "perdagangan" dalam arti berspekulasi pada fluktuasi harga di bursa pasar terbuka, melainkan sesuatu yang lebih mendasar: kemampuan untuk memindahkan nilai secara terprogram, memasukkan dana dari sistem keuangan tradisional ke dunia digital, dan menariknya kembali.
Artikel ini adalah panduan komprehensif Anda untuk menguasai API Circle untuk transaksi USDC. Kita akan memulai perjalanan terperinci, mulai dari pengaturan awal akun pengembang Anda hingga pelaksanaan transfer dan pembayaran yang kompleks. Kita akan membahas:
- Memulai: Mengatur akun Anda dan memahami perbedaan krusial antara lingkungan sandbox dan produksi.
- Autentikasi: Menghubungkan dengan aman ke API Circle menggunakan kredensial Anda.
- Konsep Inti: Pembahasan mendalam tentang model data dan sumber daya penting yang membentuk blok bangunan API, seperti Pembayaran, Penarikan, dan Transfer.
- Melaksanakan Transaksi: Instruksi langkah demi langkah untuk memasukkan dana fiat, mengelola dompet USDC Anda, mentransfer USDC antar blockchain, dan menariknya kembali ke fiat.
- Fitur Lanjutan & Praktik Terbaik: Memanfaatkan fitur-fitur canggih seperti permintaan idempoten untuk mencegah kesalahan, menggunakan webhook untuk notifikasi real-time, menangani set data besar dengan paginasi, dan menerapkan penanganan kesalahan yang tangguh.
Pada akhir panduan ini, Anda akan memiliki pengetahuan dan contoh praktis yang dibutuhkan untuk membangun aplikasi canggih yang memanfaatkan kekuatan dolar digital yang stabil, global, dan dapat diprogram.
Ingin platform All-in-One yang terintegrasi untuk Tim Pengembang Anda agar dapat bekerja sama dengan produktivitas maksimum?
Apidog memenuhi semua permintaan Anda, dan menggantikan Postman dengan harga yang jauh lebih terjangkau!
button
Memulai dengan Circle
Sebelum Anda dapat menulis satu baris kode pun, Anda perlu menyiapkan lingkungan pengembangan Anda dan mendapatkan kredensial Anda. Langkah dasar ini sangat penting untuk proses integrasi yang lancar.
Lingkungan Sandbox vs. Produksi
Circle menyediakan dua lingkungan berbeda untuk API-nya: Sandbox dan Produksi. Memahami peran keduanya adalah langkah pertama menuju integrasi yang sukses dan aman.
- Lingkungan Sandbox: Ini adalah tempat bermain pengembangan pribadi Anda. Sandbox dirancang untuk pengujian, pembuatan prototipe, dan integrasi tanpa konsekuensi finansial dunia nyata. Ini mencerminkan fungsionalitas API produksi, memungkinkan Anda untuk membangun dan menyempurnakan aplikasi Anda dengan keyakinan penuh. Transaksi di sandbox menggunakan jaringan uji dan tidak melibatkan uang atau USDC sungguhan. Semua data dalam sandbox terpisah dari lingkungan produksi.
- Lingkungan Produksi: Ini adalah lingkungan langsung di mana transaksi keuangan nyata terjadi. Setelah kode Anda diuji secara menyeluruh dan disempurnakan di sandbox, Anda dapat beralih ke produksi hanya dengan menukar host API dan menggunakan kunci API langsung Anda.
Host API untuk setiap lingkungan adalah sebagai berikut:
| Lingkungan | URL Host API |
|---|---|
| Sandbox | https://api-sandbox.circle.com |
| Produksi | https://api.circle.com |
Sepanjang panduan ini, semua contoh akan menggunakan URL sandbox. Ini adalah praktik terbaik yang krusial: selalu kembangkan dan uji di lingkungan sandbox terlebih dahulu.
Membuat Akun Sandbox Anda
Perjalanan Anda dimulai dengan membuat akun pengembang Circle, yang akan memberi Anda akses ke lingkungan sandbox.
- Navigasi ke Situs Web Circle: Kunjungi halaman pengembang resmi Circle.
- Daftar: Cari opsi untuk mendaftar akun pengembang atau sandbox. Anda perlu memberikan beberapa informasi dasar, seperti alamat email dan kata sandi yang aman.
- Verifikasi Email Anda: Setelah mengirimkan formulir pendaftaran, Anda akan menerima email verifikasi. Klik tautan dalam email ini untuk mengaktifkan akun Anda.
- Akses Dashboard: Setelah akun Anda diverifikasi, Anda dapat masuk ke dashboard pengembang. Dashboard ini adalah pusat utama Anda untuk mengelola aplikasi, kunci API, dan melihat aktivitas sandbox Anda.
Membuat Kunci API Pertama Anda
Kunci API adalah token rahasia unik yang mengautentikasi permintaan aplikasi Anda ke API Circle. Ini membuktikan bahwa permintaan berasal dari Anda dan bukan dari pihak ketiga yang tidak berwenang.
Berikut cara membuat kunci API dari dashboard sandbox baru Anda:
- Masuk ke akun sandbox pengembang Circle Anda.
- Navigasi ke Bagian Kunci API: Di dashboard, temukan bagian berlabel "Kunci API" atau "Pengaturan Pengembang".
- Buat Kunci Baru: Akan ada opsi "Buat Kunci API Baru". Klik itu.
- Beri Nama Kunci Anda: Beri nama deskriptif pada kunci Anda (misalnya, "Aplikasi Perdagangan Saya - Uji"). Ini membantu Anda mengidentifikasi tujuan kunci nanti, terutama jika Anda memiliki beberapa kunci untuk aplikasi yang berbeda.
- Salin dan Amankan Kunci Anda: Setelah dibuat, kunci API Anda akan ditampilkan di layar. Ini adalah satu-satunya waktu kunci lengkap akan ditampilkan. Anda harus segera menyalinnya dan menyimpannya di lokasi yang aman, seperti pengelola kata sandi atau file variabel lingkungan untuk proyek Anda. Jangan menyandikan kunci API Anda langsung di kode sumber Anda.
Kunci API Anda adalah informasi sensitif. Siapa pun yang memilikinya dapat membuat permintaan atas nama akun Anda. Perlakukan dengan tingkat keamanan yang sama seperti Anda memperlakukan kata sandi.
Autentikasi dan Pengaturan Awal
Dengan kunci API di tangan, Anda sekarang siap untuk melakukan panggilan pertama Anda ke API Circle. Langkah pertama adalah menguasai proses autentikasi dan menguji koneksi Anda untuk memastikan semuanya dikonfigurasi dengan benar.
Autentikasi API: Token Bearer
API Circle menggunakan skema autentikasi Token Bearer. Ini adalah metode autentikasi HTTP standar di mana setiap permintaan API harus menyertakan header Authorization yang berisi kunci API Anda.
Format header adalah: Authorization: Bearer YOUR_API_KEY
Anda harus mengganti YOUR_API_KEY dengan kunci rahasia aktual yang Anda buat di bab sebelumnya.
Menguji Koneksi Anda
Sebelum menyelami transaksi yang kompleks, penting untuk melakukan dua tes sederhana: satu untuk memeriksa konektivitas jaringan dasar ke server API Circle dan yang lainnya untuk memverifikasi bahwa kunci API Anda dikonfigurasi dengan benar.
Menguji Konektivitas Mentah dengan /ping
Endpoint /ping adalah pemeriksaan kesehatan sederhana. Ini tidak memerlukan autentikasi dan digunakan untuk mengonfirmasi bahwa Anda dapat mencapai server API Circle.
Berikut cara memanggilnya menggunakan cURL, alat baris perintah umum untuk membuat permintaan HTTP:
curl -H 'Accept: application/json' \
-X GET --url https://api-sandbox.circle.com/ping
Respons Berhasil:
Jika koneksi Anda berhasil, API akan mengembalikan objek JSON sederhana:
{
"message": "pong"
}
Jika Anda menerima respons ini, Anda telah berhasil membangun koneksi ke lingkungan sandbox. Jika tidak, periksa koneksi jaringan Anda, firewall, atau kesalahan penulisan di URL.
Menguji Kunci API Anda dengan /v1/configuration
Sekarang, mari kita uji apakah kunci API Anda valid dan diformat dengan benar. Endpoint /v1/configuration mengambil informasi konfigurasi dasar untuk akun Anda dan memerlukan autentikasi.
Berikut adalah perintah cURL. Ingatlah untuk mengganti ${YOUR_API_KEY} dengan kunci API aktual Anda. Untuk keamanan, sebaiknya gunakan variabel lingkungan.
# Sebaiknya simpan kunci API Anda dalam variabel lingkungan
# export YOUR_API_KEY='YOUR_KEY_HERE'
curl -H 'Accept: application/json' \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-X GET --url https://api-sandbox.circle.com/v1/configuration
Respons Berhasil:
Permintaan yang berhasil akan mengembalikan objek JSON yang berisi ID dompet master Anda. masterWalletId adalah pengidentifikasi unik untuk dompet utama yang terkait dengan akun Anda tempat dana Anda disimpan.
{
"data": {
"payments": {
"masterWalletId": "1234567890"
}
}
}
Respons Kesalahan:
Jika ada masalah dengan kunci API Anda atau cara Anda memformat header Authorization, Anda akan menerima kesalahan 401 Unauthorized.
{
"code": 401,
"message": "Malformed authorization. Are the credentials properly encoded?"
}
Jika Anda melihat kesalahan ini, periksa kembali hal berikut:
- Apakah Anda menyertakan kata
Bearerdiikuti dengan spasi sebelum kunci? - Apakah Anda menyalin seluruh kunci API dengan benar, tanpa karakter atau spasi tambahan?
- Apakah Anda yakin menggunakan kunci API yang valid dan aktif dari dashboard Anda?
Menggunakan SDK Circle untuk Integrasi yang Lebih Sederhana
Meskipun Anda selalu dapat berinteraksi dengan API secara langsung menggunakan permintaan HTTP, Circle menyediakan Software Development Kits (SDK) untuk bahasa pemrograman populer seperti Node.js, Python, dan Java. SDK ini menangani kode boilerplate untuk autentikasi, pemformatan permintaan, dan penguraian respons, membuat proses pengembangan Anda lebih cepat dan kurang rentan terhadap kesalahan.
Berikut adalah contoh singkat bagaimana Anda dapat menginisialisasi SDK Node.js Circle:
// Instal SDK terlebih dahulu: npm install @circle-fin/circle-sdk
import { Circle, CircleEnvironments } from "@circle-fin/circle-sdk";
const circle = new Circle(
process.env.CIRCLE_API_KEY, // Kunci API dari variabel lingkungan
CircleEnvironments.sandbox // Menunjuk ke lingkungan sandbox
);
async function getConfiguration() {
try {
const response = await circle.core.getConfiguration();
console.log(response.data.payments.masterWalletId);
} catch (error) {
console.error(error.response.data);
}
}
getConfiguration();
Menggunakan SDK mengabstraksi detail tingkat rendah, memungkinkan Anda untuk fokus pada logika bisnis aplikasi Anda. Kami merekomendasikan penggunaan SDK untuk proyek serius apa pun.
Konsep Inti dan Sumber Daya API
Untuk menggunakan API Circle secara efektif, Anda harus memahami model data dasarnya. API dibangun di sekitar serangkaian sumber daya—objek JSON yang mewakili entitas inti dalam sistem, seperti pembayaran, dompet, dan transfer.
Ikhtisar Sumber Daya API
Sumber daya Circle dapat dikategorikan ke dalam beberapa kelompok:
Sumber Daya Utama: Ini mewakili tindakan keuangan utama yang dapat Anda lakukan.
Payment Object: Mewakili pembayaran dari pelanggan, berfungsi sebagai cara utama untuk memasukkan dana ke ekosistem Circle.Payout Object: Mewakili penarikan ke pihak eksternal (misalnya, rekening bank), berfungsi sebagai cara utama untuk menarik dana.Transfer Object: Mewakili pergerakan dana, baik antar dompet Circle Anda sendiri atau ke alamat blockchain eksternal.
Metode dan Instrumen:
Wallet Object: Mewakili penyimpanan dana (saldo) yang dikelola oleh Circle. Anda memiliki dompet master, dan dapat membuat yang lain.Wire Account Object: Mewakili rekening bank yang terhubung untuk menerima penarikan.
Sumber Daya Bersarang: Ini adalah objek yang sering disematkan dalam sumber daya lain untuk memberikan informasi terperinci.
Money Object: Objek standar untuk mewakili jumlah moneter dan mata uangnya (misalnya,{ "amount": "100.00", "currency": "USD" }).SourcedanDestination Objects: Ini menentukan dari mana dana untuk transaksi berasal dan ke mana tujuannya.Blockchain Address Object: Mewakili alamat tertentu pada blockchain yang didukung.
Pembahasan Mendalam: Objek Payment
Sebuah payment adalah cara Anda menerima dana. Meskipun API mendukung pembayaran kartu, untuk kasus penggunaan USDC, Anda akan sering berurusan dengan pembayaran yang mendanai dompet Circle Anda.
Contoh Objek Payment:
{
"id": "e665ea6e-3a53-4f93-a85e-45178d48d9ea",
"type": "payment",
"merchantId": "c680d087-7b41-40aa-95a2-68febcdddb22",
"merchantWalletId": "1000002853",
"amount": {
"amount": "10.00",
"currency": "USD"
},
"source": {
"id": "86461e9f-db1a-487f-915b-641138062e7c",
"type": "card"
},
"description": "New customer payment",
"status": "confirmed",
"fees": {
"amount": "0.58",
"currency": "USD"
},
"createDate": "2024-01-10T02:29:53.888Z",
"updateDate": "2024-01-10T02:32:19.421Z"
}
Atribut Kunci:
id(string): Pengidentifikasi unik untuk pembayaran ini.amount(Objek Money): Jumlah dan mata uang pembayaran.source(Objek Source): Detail dari mana uang berasal (misalnya, kartu atau transfer kawat).status(string): Status pembayaran saat ini. Dapat berupapending,confirmed,paid, ataufailed. Ini adalah bidang penting untuk dipantau.fees(Objek Money): Biaya yang dikenakan oleh Circle untuk memproses pembayaran.
Pembahasan Mendalam: Objek Transfer
Sebuah transfer bisa dibilang objek terpenting untuk "berdagang" atau memindahkan USDC. Ini mewakili pergerakan mata uang digital.
Contoh Objek Transfer:
{
"id": "c332d75a-3870-410c-b26a-93e5a3ab90e8",
"source": {
"type": "wallet",
"id": "1000002853"
},
"destination": {
"type": "blockchain",
"address": "0x8381470ED67C3802402dbbFa0058E8871F017A6F",
"chain": "ETH"
},
"amount": {
"amount": "150.50",
"currency": "USD"
},
"status": "pending",
"createDate": "2024-05-15T18:44:03.484Z",
"updateDate": "2024-05-15T18:44:03.484Z"
}
Atribut Kunci:
id(string): Pengidentifikasi unik untuk transfer ini.source(Objek Source): Dari mana dana berasal. Untuk transfer keluar, ini hampir selalu akan menjadiwalletAnda.destination(Objek Destination): Ke mana dana akan pergi. Ini bisa berupawalletCircle lain atau, lebih umum, alamatblockchaineksternal.amount(Objek Money): Jumlah USDC yang akan ditransfer.status(string): Status transfer. Ini akan dimulai sebagaipendingdan beralih kecompleteataufailed.
Objek Sumber dan Tujuan
Objek-objek bersarang ini sangat penting karena mereka mendefinisikan aliran dana dalam transaksi apa pun.
Bidang type mereka menentukan jenis sumber atau tujuan:
wallet: Dompet Circle, diidentifikasi olehid-nya.blockchain: Alamat eksternal pada blockchain, ditentukan olehaddressdanchain(misalnya,ETH,SOL,MATIC).wire: Rekening bank, digunakan untuk penarikan.card: Kartu kredit/debit, digunakan untuk pembayaran.
Rantai dan Mata Uang yang Didukung
Circle tidak bergantung pada rantai dan terus memperluas dukungannya. Hingga akhir 2024, USDC tersedia di banyak blockchain utama, termasuk:
- Ethereum (ETH)
- Solana (SOL)
- Polygon PoS (MATIC)
- TRON (TRX)
- Avalanche (AVAX)
- Stellar (XLM)
- Algorand (ALGO)
- Flow (FLOW)
Anda harus menentukan pengidentifikasi chain yang benar saat melakukan transfer. Untuk mata uang fiat, API terutama mendukung USD dan EUR. currency dalam objek Money harus selalu diatur ke USD saat berurusan dengan transfer USDC.
Melaksanakan Transaksi: Siklus Hidup Penuh
Sekarang kita sampai pada inti masalah: menggunakan API untuk memindahkan uang. Kita akan membahas siklus hidup lengkap: memasukkan dana fiat untuk mendapatkan USDC, mentransfer USDC tersebut ke alamat eksternal, dan akhirnya menariknya kembali ke rekening bank fiat.
Langkah 1: Memasukkan Dana Fiat dengan Payment
Untuk banyak aplikasi, langkah pertama adalah mengubah mata uang fiat dari pelanggan menjadi USDC di dompet Circle Anda. Endpoint API Create Payment digunakan untuk ini. Meskipun API mendukung berbagai sumber pembayaran, kita akan fokus pada konsepnya.
Misalkan seorang pelanggan membayar Anda $500. Anda akan membuat permintaan POST ke /v1/payments.
Permintaan API untuk Membuat Pembayaran:
curl -X POST \
https://api-sandbox.circle.com/v1/payments \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
"idempotencyKey": "your-unique-uuid-here-for-payment",
"source": {
"id": "some-card-or-bank-id",
"type": "card"
},
"amount": {
"amount": "500.00",
"currency": "USD"
},
"description": "Payment for services rendered"
}'
Catatan Penting: idempotencyKey sangat penting di sini. Ini adalah ID unik (dalam format UUID) yang Anda buat untuk permintaan ini. Jika Anda mengirim permintaan yang sama dua kali (misalnya, karena kesalahan jaringan), Circle akan mengenali kunci tersebut dan hanya memproses pembayaran sekali. Kita akan membahas ini lebih detail di bab berikutnya.
Setelah pembayaran ini diproses dan status-nya menjadi confirmed atau paid, jumlah USDC yang setara (dikurangi biaya) akan dikreditkan ke merchantWalletId Anda.
Langkah 2: Memeriksa Saldo Dompet Anda
Setelah menerima pembayaran, Anda ingin memverifikasi bahwa dana telah tiba. Anda dapat memeriksa saldo dompet mana pun milik Anda, tetapi paling umum dompet master Anda.
Permintaan API untuk Mendapatkan Saldo:
curl -X GET \
https://api-sandbox.circle.com/v1/wallets/${YOUR_WALLET_ID}/balances \
-H "Authorization: Bearer ${YOUR_API_KEY}"
Ganti ${YOUR_WALLET_ID} dengan masterWalletId yang Anda ambil sebelumnya.
Respons API:
Respons akan berupa daftar saldo, satu untuk setiap mata uang yang Anda pegang.
{
"data": {
"available": [
{
"amount": "495.50",
"currency": "USD"
}
],
"unsettled": [
{
"amount": "0.00",
"currency": "USD"
}
]
}
}
Saldo available adalah apa yang dapat segera Anda transfer atau tarik.
Langkah 3: Mentransfer USDC On-Chain
Ini adalah inti dari penggunaan USDC. Anda dapat mentransfer dana dari dompet Anda ke alamat eksternal mana pun di blockchain yang didukung. Ini sempurna untuk membayar pemasok, memindahkan dana ke protokol DeFi, atau mengirim nilai ke pengguna.
Misalkan Anda ingin mengirim 100 USDC ke alamat Ethereum.
Permintaan API untuk Membuat Transfer:
curl -X POST \
https://api-sandbox.circle.com/v1/transfers \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
"idempotencyKey": "another-unique-uuid-for-transfer",
"source": {
"type": "wallet",
"id": "1000002853"
},
"destination": {
"type": "blockchain",
"address": "0x8381470ED67C3802402dbbFa0058E8871F017A6F",
"chain": "ETH"
},
"amount": {
"amount": "100.00",
"currency": "USD"
}
}'
Rincian Badan Permintaan:
idempotencyKey: UUID baru yang unik untuk operasi transfer spesifik ini.source: Dompet Circle Anda, ditentukan olehid-nya.destination: Alamat blockchain eksternal.typeadalahblockchain.addressadalah alamat dompet penerima.chainadalah pengidentifikasi untuk blockchain (ETHuntuk Ethereum).amount: Jumlah USDC yang akan dikirim.
API akan merespons dengan objek Transfer, awalnya dengan status pending.
Memahami Konfirmasi Blockchain
Transaksi on-chain tidak instan. Transfer harus disiarkan ke jaringan dan kemudian dikonfirmasi oleh penambang atau validator. status transfer Anda hanya akan berubah menjadi complete setelah menerima jumlah konfirmasi yang cukup di blockchain. Circle mengelola kompleksitas ini untuk Anda. Anda dapat melacak statusnya dengan melakukan polling endpoint GET /v1/transfers/{id} atau, lebih disukai, dengan menggunakan webhook (dibahas di bab berikutnya) untuk menerima notifikasi setelah transfer selesai.
Langkah 4: Menarik USDC ke Fiat dengan Payout
Langkah terakhir dalam siklus hidup adalah mengubah USDC Anda kembali menjadi mata uang fiat di rekening bank. Ini dilakukan melalui payout. Sebelum Anda dapat membuat penarikan, Anda harus terlebih dahulu menautkan dan memverifikasi rekening bank, yang akan membuat objek Wire Account.
Setelah Anda menyiapkan rekening bank tujuan (dengan id-nya sendiri), Anda dapat membuat penarikan.
Permintaan API untuk Membuat Penarikan:
curl -X POST \
https://api-sandbox.circle.com/v1/payouts \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
"idempotencyKey": "yet-another-unique-uuid-for-payout",
"destination": {
"type": "wire",
"id": "your-bank-account-uuid-here"
},
"amount": {
"amount": "250.00",
"currency": "USD"
}
}'
API akan merespons dengan objek Payout. status awalnya akan pending dan akan beralih ke complete setelah dana berhasil dikirim ke bank tujuan.
Fitur Lanjutan dan Praktik Terbaik
Untuk membangun aplikasi yang benar-benar tangguh dan skalabel, Anda perlu melampaui panggilan API dasar dan memanfaatkan fitur-fitur canggih yang disediakan Circle. Fitur-fitur ini dirancang untuk memastikan integritas data, memberikan pembaruan real-time, dan membuat aplikasi Anda tangguh.
Permintaan Idempoten: Mencegah Pengeluaran Ganda
Kita telah menyebutkan idempotencyKey beberapa kali, tetapi kepentingannya tidak dapat dilebih-lebihkan. Dalam sistem keuangan, secara tidak sengaja melakukan operasi dua kali (seperti mengirim pembayaran atau transfer) dapat menjadi bencana. Masalah jaringan dapat menyebabkan permintaan habis waktu, meskipun server berhasil memprosesnya. Tanpa idempoten, aplikasi Anda mungkin secara otomatis mencoba kembali permintaan tersebut, menyebabkan transaksi duplikat.
Cara kerjanya:
- Untuk setiap permintaan
POSTyang membuat sumber daya (pembayaran, transfer, penarikan), Anda harus membuat UUID versi 4 (Universally Unique Identifier) yang unik dan menyertakannya dalam bidangidempotencyKeydari badan permintaan. - Ketika server Circle menerima permintaan, ia memeriksa apakah ia pernah melihat kunci ini sebelumnya.
- Jika kunci baru, ia memproses permintaan dan menyimpan kunci bersama dengan hasilnya.
- Jika kunci telah terlihat sebelumnya, ia tidak memproses ulang permintaan. Sebaliknya, ia hanya mengembalikan hasil dari permintaan asli.
Ini menjamin bahwa permintaan tertentu hanya dapat dieksekusi sekali, tidak peduli berapa kali itu dikirim.
Praktik Terbaik: Selalu buat dan kirim idempotencyKey untuk setiap operasi POST.
Pembaruan Real-Time dengan Webhook
Melakukan polling API berulang kali untuk memeriksa status transaksi (GET /v1/transfers/{id}) tidak efisien dan lambat. Pendekatan yang benar dan modern adalah menggunakan webhook.
Webhook adalah pesan otomatis yang dikirim dari suatu aplikasi (Circle) ke aplikasi lain (milik Anda) ketika suatu peristiwa tertentu terjadi. Anda dapat mengonfigurasi URL di dashboard Circle Anda di mana Anda ingin menerima notifikasi ini.
Ketika status pembayaran, transfer, atau penarikan berubah, Circle akan mengirimkan permintaan POST ke URL yang Anda konfigurasikan dengan payload notifikasi yang berisi objek yang diperbarui.
Contoh Payload Notifikasi untuk Transfer yang Selesai:
{
"notification": {
"id": "notification-uuid",
"type": "transfers",
"subscriptionId": "your-subscription-id"
},
"transfer": {
"id": "c332d75a-3870-410c-b26a-93e5a3ab90e8",
"source": { ... },
"destination": { ... },
"amount": {
"amount": "100.00",
"currency": "USD"
},
"status": "complete",
"transactionHash": "0x123abc...",
"createDate": "2024-05-15T18:44:03.484Z",
"updateDate": "2024-05-15T18:48:12.123Z"
}
}
Dengan mendengarkan notifikasi ini, aplikasi Anda dapat bereaksi secara instan terhadap peristiwa seperti transfer yang selesai atau pembayaran yang gagal, memberikan pengalaman pengguna yang jauh lebih baik dan memungkinkan otomatisasi real-time.
Paginasi dan Pemfilteran: Menangani Set Data Besar
Seiring pertumbuhan aplikasi Anda, Anda akan mengumpulkan ribuan pembayaran, transfer, dan catatan lainnya. Meminta semuanya sekaligus menggunakan endpoint GET seperti /v1/transfers akan lambat dan tidak praktis.
API Circle menggunakan paginasi berbasis kursor untuk mengatasi masalah ini. Ketika Anda mencantumkan sumber daya, respons hanya akan berisi sejumlah item terbatas ("halaman"). Anda dapat mengontrol ukuran halaman ini dengan parameter pageSize. Untuk mendapatkan halaman hasil berikutnya atau sebelumnya, Anda menggunakan parameter pageAfter atau pageBefore, meneruskan ID item terakhir atau pertama yang Anda lihat.
Contoh: Mendapatkan halaman pertama dari 20 transfer:GET /v1/transfers?pageSize=20
Contoh: Mendapatkan halaman berikutnya dari 20 transfer:GET /v1/transfers?pageSize=20&pageAfter={id_of_last_transfer_from_previous_page}
Anda juga dapat memfilter hasil berdasarkan rentang waktu (timestamp from dan to) dan atribut spesifik sumber daya lainnya.
Penanganan Kesalahan: Membangun Aplikasi yang Tangguh
Hal-hal bisa dan pasti akan salah. Permintaan API mungkin gagal karena input tidak valid, dana tidak mencukupi, atau masalah server sementara. Aplikasi yang tangguh harus mengantisipasi dan menangani kesalahan ini dengan anggun.
API Circle menggunakan kode status HTTP standar untuk menunjukkan hasil permintaan.
2xx(misalnya,200 OK,201 Created): Berhasil.4xx(misalnya,400 Bad Request,401 Unauthorized,404 Not Found): Kesalahan sisi klien. Anda mengirim sesuatu yang salah.5xx(misalnya,500 Internal Server Error): Kesalahan sisi server. Ada yang salah di pihak Circle.
Ketika terjadi kesalahan, badan respons API akan berisi objek JSON dengan detail lebih lanjut.
Contoh Respons Kesalahan (400 Bad Request):
{
"code": 2,
"message": "Invalid or missing parameter. See details for more information.",
"errors": [
{
"location": "body",
"message": "destination address is invalid",
"param": "destination.address"
}
]
}
Kode Anda harus selalu dibungkus dalam blok try/catch (atau yang setara untuk bahasa Anda) untuk menangani potensi pengecualian dari panggilan API. Anda harus mencatat detail kesalahan dan, jika sesuai, menyajikan pesan yang membantu kepada pengguna.
Kesimpulan: Memberdayakan Masa Depan Keuangan
Kita telah menempuh seluruh proses penggunaan API Circle untuk bertransaksi dengan USDC. Mulai dari pengaturan sandbox awal dan autentikasi hingga pelaksanaan pembayaran, transfer, dan penarikan, Anda kini memiliki pengetahuan dasar untuk membangun aplikasi keuangan yang kuat. Kita juga telah menjelajahi fitur-fitur canggih seperti idempoten, webhook, dan penanganan kesalahan yang penting untuk menciptakan sistem yang profesional dan siap produksi.
API Circle melakukan lebih dari sekadar memungkinkan Anda memindahkan mata uang digital; ia menyediakan jalur yang dapat diprogram untuk sistem keuangan baru yang bersifat asli internet. Dengan mengabstraksi kompleksitas teknologi blockchain dan menyediakan API yang bersih serta berorientasi sumber daya, Circle memberdayakan pengembang untuk berinovasi dan membangun generasi berikutnya dari perdagangan global, layanan keuangan, dan pembayaran peer-to-peer.
Kemungkinannya sangat luas. Alat-alat ada di tangan Anda. Sekarang, bangunlah sesuatu yang luar biasa.
Ingin platform All-in-One yang terintegrasi untuk Tim Pengembang Anda agar dapat bekerja sama dengan produktivitas maksimum?
Apidog memenuhi semua permintaan Anda, dan menggantikan Postman dengan harga yang jauh lebih terjangkau!
button
