# Upgrade API Pelajari cara mengelola versi API dan menangani perubahan mendasar dalam rilis mayor. Periksa [Changelog Pengembang](https://docs.stripe.com/changelog.md) untuk catatan lengkap perubahan pada API Stripe. Versi API menentukan perilaku API dan webhook yang Anda lihat (misalnya, parameter apa yang dapat Anda sertakan dalam permintaan, properti apa yang Anda lihat dalam respons, dan sebagainya). Versi Anda ditetapkan saat pertama kali membuat permintaan API. Setiap rilis utama, seperti [Basil](https://docs.stripe.com/changelog/basil.md), mencakup perubahan yang tidak kompatibel dengan versi sebelumnya. Memperbarui ke rilis utama baru dapat memerlukan pembaruan pada kode yang ada. Setiap rilis bulanan hanya mencakup perubahan yang kompatibel dengan versi sebelumnya, serta menggunakan nama yang sama dengan rilis utama terakhir. Anda dapat memperbarui ke rilis bulanan baru secara aman tanpa merusak kode yang ada. Untuk memperbarui versi API Anda, ikuti [langkah-langkah berikut](https://docs.stripe.com/upgrades.md#how-can-i-upgrade-my-api). Bila platform [Connect](https://stripe.com/connect) membuat permintaan atas nama akun terhubung tanpa menentukan versi API, Stripe selalu menggunakan versi API platform tersebut. Terlepas dari versi API akun terhubung, permintaan platform atas namanya selalu mengembalikan respons yang cocok dengan versi API permintaan. ## Perubahan yang kompatibel dengan rilis sebelumnya Stripe menganggap perubahan berikut kompatibel dengan rilis sebelumnya: - Menambahkan sumber daya API baru. - Menambahkan parameter permintaan opsional baru ke metode API yang sudah ada. - Menambahkan properti baru ke respons API yang sudah ada. - Mengubah urutan properti pada respons API yang sudah ada. - Mengubah panjang atau format string yang tidak transparan, seperti identifikasi objek, pesan kesalahan, dan string lain yang dapat dibaca manusia. - Hal ini termasuk menambahkan atau menghapus awalan tetap (seperti `ch_` pada identifikasi charge). - Pastikan bahwa integrasi Anda dapat menangani identifikasi objek yang dihasilkan Stripe, yang dapat berisi hingga 255 karakter. Misalnya, jika Anda menggunakan MySQL, simpan identifikasi di kolom `VARCHAR(255) COLLATE utf8_bin` (konfigurasi `COLLATE` memberikan kepekaan jenis huruf selama pencarian). - Menambahkan tipe kejadian baru. - Pastikan listener webhook Anda dengan baik menangani tipe kejadian yang tidak dikenal. ## Tingkatkan versi API Anda Jika Anda menjalankan API versi lama, upgrade ke versi terbaru untuk memanfaatkan fitur baru dan meningkatkan fungsionalitas. Meningkatkan versi API Anda akan memengaruhi: - Panggilan API yang Anda buat tanpa header `Stripe-Version`: parameter yang dapat Anda kirim dan struktur objek yang dikembalikan. - Struktur objek yang diterima dengan metode [Stripe.js](https://docs.stripe.com/payments/elements.md) seperti [confirmCardPayment](https://docs.stripe.com/js.md#stripe-confirm-card-payment). - Struktur objek yang dikirim ke endpoint webhook Anda (endpoint Akun maupun [Connect](https://docs.stripe.com/connect/webhooks.md)). Namun, jika endpoint memiliki versi eksplisit yang diatur, maka akan selalu menggunakan versi tersebut. - Operasi Tagihan Otomatis yang dilakukan oleh Stripe (misalnya, pembuatan *invoice* (Invoices are statements of amounts owed by a customer. They track the status of payments from draft through paid or otherwise finalized. Subscriptions automatically generate invoices, or you can manually create a one-off invoice) untuk periode langganan baru) menggunakan versi API default akun Anda. Lihat log perubahan API untuk detail tentang cara versi API default Anda memengaruhi operasi ini. ### Tampilkan versi API Anda dan upgrade terbaru yang tersedia di Workbench Lihat [versi API yang digunakan oleh permintaan terkini](https://docs.stripe.com/workbench/guides.md#view-api-versions) pada akun Anda dan upgrade terbaru yang tersedia dari tab [Gambaran umum](https://dashboard.stripe.com/workbench/overview) di Workbench. Ketika melakukan upgrade API, pastikan untuk menentukan versi API yang ingin Anda integrasikan dalam kode, bukan mengandalkan versi API default akun Anda. Untuk mencoba versi yang lebih baru bagi panggilan API, atur header `Stripe-Version` (di lingkungan live atau percobaan). Pelajari cara mengelola pembuatan versi di [SDK sisi server](https://docs.stripe.com/sdks.md#server-side-libraries) kami. ### Tingkatkan dan coba webhook Anda > [Thin event](https://docs.stripe.com/event-destinations.md#thin-events) untuk sumber daya API v1 tersedia dalam pratinjau pribadi. Anda dapat menggunakannya untuk menyederhanakan peningkatan integrasi tanpa mengubah konfigurasi webhook Anda. Sebelumnya, thin event hanya mendukung sumber daya API v2. [Pelajari selengkapnya dan buat permintaan akses](https://docs.google.com/forms/d/e/1FAIpQLSeEkqzB02afvlklMkqwA6wsBH90eW8gxmc-hBOvqe2N6TRujQ/viewform?usp=dialog). Baca panduan kami tentang [cara menangani pembuatan versi webhook](https://docs.stripe.com/webhooks/versioning.md). ### Lakukan upgrade Bila sudah yakin bahwa kode Anda dapat menangani versi API terbaru, lakukan upgrade menggunakan Workbench: 1. Buka tab [Gambaran umum](https://dashboard.stripe.com/workbench/overview) tab in Workbench. 2. Di bagian **versi API**, klik **Upgrade tersedia**, yang akan terlihat jika tersedia versi API yang lebih baru. 3. Tinjau versi API mana yang akan ditetapkan ke akun Anda, dan klik **Upgrade.** Hal ini mengganti versi yang digunakan oleh panggilan API yang tidak memiliki header `Stripe-Version` dan juga mengganti versi yang digunakan untuk membentuk objek yang dikirim ke webhook Anda. > Sumber daya di dalam [peristiwa yang diambil dari API](https://docs.stripe.com/api/events.md) ditentukan oleh versi API default akun Anda pada saat peristiwa tersebut terjadi. Jika kode Anda mengambil peristiwa yang dibuat saat versi API default Anda berbeda, kode tersebut harus memperhitungkan setiap perbedaan dalam versi peristiwa. ### Mundurkan versi API Anda Selama 72 jam setelah meng-upgrade versi API, Anda dapat mengembalikan ke versi sebelum di-upgrade dengan aman di Workbench. Setelah Anda mengembalikan ke versi sebelumnya, webhook yang dikirim dengan struktur objek baru dan gagal akan dicoba ulang dengan struktur lama. ## Ikuti informasi terbaru [Changelog pengembang](https://docs.stripe.com/changelog.md): Catatan lengkap perubahan pada API Stripe [Peta jalan Stripe](https://stripe.com/roadmap): Pratinjau rilis produk Stripe yang akan datang