# Memperluas respons Pelajari cara mengurangi jumlah permintaan yang Anda buat ke Stripe API dengan memperluas objek dalam respons. Panduan ini menjelaskan cara meminta properti tambahan dari API. Anda akan belajar mengubah permintaan Anda agar menyertakan: - properti dari objek terkait - properti dari objek yang terkait jauh - properti tambahan pada semua objek dalam daftar - properti yang tidak disertakan secara default dalam respons ## Cara kerjanya Stripe API diatur ke dalam sumber daya yang diwakili oleh objek dengan properti kontekstual, konfigurasi, dan status. Semua objek ini memiliki identifikasi unik yang dapat Anda gunakan untuk mengambil, memperbarui, serta menghapusnya. API juga menggunakan identifikasi ini untuk menautkan objek terkait bersamaan. Misalnya, sebuah [Sesi Checkout](https://docs.stripe.com/api/checkout/sessions/object.md) menautkan ke [Pelanggan](https://docs.stripe.com/api/customers/object.md) dengan [Identifikasi Pelanggan](https://docs.stripe.com/api/checkout/sessions/object.md#checkout_session_object-customer). ```json { "id": "cs_test_KdjLtDPfAjT1gq374DMZ3rHmZ9OoSlGRhyz8yTypH76KpN4JXkQpD2G0", "object": "checkout.session", ..."customer": "cus_HQmikpKnGHkNwW", ... } ``` Dalam hal Anda membutuhkan informasi dari objek yang ditautkan, Anda dapat mengambil objek yang ditautkan dalam panggilan baru menggunakan identifikasinya. Namun, pendekatan ini memerlukan dua permintaan API untuk mengakses satu nilai saja. Jika Anda membutuhkan informasi dari beberapa objek yang ditautkan, masing-masing juga mengharuskan permintaan terpisah, yang semuanya menambah latensi dan kompleksitas aplikasi Anda. API memiliki fitur Perluas yang memungkinkan Anda mengambil objek yang ditautkan dalam satu panggilan, secara efektif menggantikan identifikasi objek dengan semua properti dan nilainya. Misalnya, Anda ingin mengakses detail tentang pelanggan yang dikaitkan dengan Sesi Checkout tertentu. Anda akan mengambil Sesi Checkout dan meneruskan properti `customer` ke larik `expand`, yang memberi tahu Stripe untuk menyertakan seluruh objek Customer dalam respons: ```curl curl -G https://api.stripe.com/v1/checkout/sessions/{{CHECKOUTSESSION_ID}} \ -u "<>:" \ -d "expand[]=customer" ``` Yang mengembalikan Sesi Checkout dengan objek Customer lengkap, bukan identifikasinya: ```json { "id": "cs_test_KdjLtDPfAjT1gq374DMZ3rHmZ9OoSlGRhyz8yTypH76KpN4JXkQpD2G0", "object": "checkout.session", ..."customer": { "id": "cus_HQmikpKnGHkNwW", "object": "customer", ... "metadata": { "user_id": "user_xyz" }, ... } } ``` > Tidak semua properti dapat diperluas. Referensi API menandai properti yang dapat diperluas dengan label “Dapat diperluas”. ## Memperluas beberapa properti Untuk memperluas beberapa properti dalam satu panggilan, tambahkan item tambahan ke larik perluas. Misalnya, jika Anda ingin memperluas [customer](https://docs.stripe.com/api/checkout/sessions/object.md#checkout_session_object-customer) maupun [payment_intent](https://docs.stripe.com/api/checkout/sessions/object.md#checkout_session_object-payment_intent) untuk Sesi Checkout tertentu, Anda harus meneruskan `expand` larik dengan string `customer` maupun `payment_intent`: ```curl curl -G https://api.stripe.com/v1/checkout/sessions/{{CHECKOUTSESSION_ID}} \ -u "<>:" \ -d "expand[]=customer" \ -d "expand[]=payment_intent" ``` ## Memperluas beberapa level Jika nilai yang Anda inginkan bersarang sangat dalam di beberapa sumber daya yang ditautkan, Anda dapat menjangkaunya dengan memperluas secara berulang menggunakan notasi titik. Misalnya, jika Anda perlu mengetahui tipe metode pembayaran yang digunakan untuk Sesi Checkout tertentu, pertama-tama Anda mengambil maksud pembayaran Sesi Checkout, kemudian mengambil metode pembayaran yang dikaitkan dari maksud pembayaran untuk mendapatkan tipenya. Dengan `expand`, Anda dapat melakukan hal ini dalam satu panggilan: ```curl curl -G https://api.stripe.com/v1/checkout/sessions/{{CHECKOUTSESSION_ID}} \ -u "<>:" \ -d "expand[]=payment_intent.payment_method" ``` Yang mengembalikan Sesi Checkout dengan objek [PaymentIntent](https://docs.stripe.com/api/payment_intents/object.md) dan [PaymentMethod](https://docs.stripe.com/api/payment_methods/object.md) lengkap sebagai ganti identifikasinya: ```json { "id": "cs_test_KdjLtDPfAjT1gq374DMZ3rHmZ9OoSlGRhyz8yTypH76KpN4JXkQpD2G0", "object": "checkout.session", ... "mode": "payment","payment_intent": { "id": "pi_1GkXXDLHughnNhxyLlsnvUuY", "object": "payment_intent", "amount": 100, ... "charges": {...}, "client_secret": "pi_1GkXXDLHughnNhxyLlsnvUuY_secret_oLbwpm0ME0ieJ9Aykz2SwKzj5", ... "payment_method": { "id": "pm_1GkXXuLHughnNhxy8xpAdGtf", "object": "payment_method", "billing_details": {...}, "card": {...}, "created": 1589902798, "customer": "cus_HQmikpKnGHkNwW", "livemode": false, "metadata": {}, "type": "card" }, "payment_method_options": {...}, "payment_method_types": [ "card" ], "receipt_email": "jenny.rosen@gmail.com", "review": null, "setup_future_usage": null, "shipping": null, "source": null, "statement_descriptor": null, "statement_descriptor_suffix": null, "status": "succeeded", "transfer_data": null, "transfer_group": null }, "payment_method_types": [ "card" ], "setup_intent": null, "shipping": null, "shipping_address_collection": null, "submit_type": null, "subscription": null, "success_url": "http://localhost:5000" } ``` > Perluasan memiliki kedalaman maksimum sebanyak empat level. Artinya, string `expand` tidak dapat berisi lebih dari empat properti: `property1.property2.property3.property4`. ## Memperluas properti dalam daftar Bila API mengembalikan daftar objek, Anda dapat menggunakan kata kunci `data` untuk memperluas properti tertentu pada setiap objek dalam daftar itu. Misalnya, Anda membutuhkan informasi tentang metode pembayaran yang digunakan oleh salah satu pelanggan. Untuk mendapatkan informasi ini, Anda dapat [mencantumkan PaymentIntents pelanggan](https://docs.stripe.com/api/payment_intents/list.md#list_payment_intents-customer), yang mengembalikan objek dengan struktur berikut: ```json { "object": "list","data": [ { "id": "pi_1GrvBKLHughnNhxy6N28q8gt", "object": "payment_intent", "amount": 1000, ..."payment_method": "pm_1GrvBxLHughnNhxyJjtBtHcc", ... }, { "id": "pi_1Grv8tLHughnNhxyflPG4bMG", "object": "payment_intent", "amount": 4000, ..."payment_method": "pm_1Grv9zLHughnNhxyv6uMNomv", ... } ], "has_more": false, "url": "/v1/payment_intents" } ``` > Semua daftar yang dikembalikan dalam API memiliki struktur di atas, di mana properti `data` berisi larik objek yang dicantumkan. Anda dapat menggunakan kata kunci `data` di segala posisi dalam string perluas untuk memindahkan kursor perluas ke dalam daftar. Daripada mengulang setiap maksud pembayaran dalam daftar dan mengambil metode pembayaran yang ditautkan dalam panggilan terpisah, Anda dapat memperluas semua metode pembayaran sekaligus menggunakan kata kunci `data`: ```curl curl -G https://api.stripe.com/v1/payment_intents \ -u "<>:" \ -d "customer={{CUSTOMER_ID}}" \ -d "expand[]=data.payment_method" ``` Daftar tersebut kemudian menyertakan objek metode pembayaran lengkap pada setiap maksud pembayaran: ```json { "object": "list", "data": [ { "id": "pi_1GrvBKLHughnNhxy6N28q8gt", "object": "payment_intent", "amount": 1000, ..."payment_method": { "id": "pm_1GrvBxLHughnNhxyJjtBtHcc", "object": "payment_method", "billing_details": {...}, "card": { "brand": "visa", ... "country": "US", "exp_month": 2, "exp_year": 2022, "fingerprint": "1212u2LvSFqEHu3h", "funding": "credit", "last4": "4242", ... }, "created": 1591661989, "customer": "cus_HQmikpKnGHkNwW", "livemode": false, "metadata": {...}, "type": "card" }, ... }, { "id": "pi_1Grv8tLHughnNhxyflPG4bMG", "object": "payment_intent", "amount": 4000, ..."payment_method": { "id": "pm_1Grv9zLHughnNhxyv6uMNomv", "object": "payment_method", "billing_details": {...}, "card": { "brand": "visa", "checks": {...}, "country": "US", "exp_month": 2, "exp_year": 2025, "fingerprint": "1212u2LvSFqEHu3h", "funding": "credit", "generated_from": null, "last4": "0341", "three_d_secure_usage": {...}, "wallet": null }, "created": 1591661989, "customer": "cus_HQmikpKnGHkNwW", "livemode": false, "metadata": {...}, "type": "card" }, ... } ], "has_more": false, "url": "/v1/payment_intents" } ``` > Memperluas respons berimplikasi pada kinerja. Agar permintaan tetap cepat, coba batasi banyak perluasan yang bersarang pada permintaan daftar. ## Menggunakan ekspansi untuk meminta properti yang dapat disertakan Di sebagian kasus, sumber daya memiliki properti yang tidak disertakan secara default. Salah satu contohnya adalah properti [line_items](https://docs.stripe.com/api/checkout/sessions/object.md#checkout_session_object-line_items) di Sesi Checkout, yang hanya disertakan dalam respons jika diminta menggunakan parameter `expand`, misalnya: ```curl curl -G https://api.stripe.com/v1/checkout/sessions/{{CHECKOUTSESSION_ID}} \ -u "<>:" \ -d "expand[]=line_items" ``` > Seperti properti lain yang dapat diperluas, referensi API menandai properti yang dapat disertakan dengan label “Dapat diperluas”. ## Menggunakan ekspansi dengan webhook Anda tidak dapat menerima kejadian *webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) dengan properti yang diperluas secara otomatis. Objek yang dikirim dalam kejadian selalu dalam bentuk minimalnya. Untuk mengakses nilai yang bersarang di properti yang dapat diperluas, Anda harus mengambil objek tersebut pada panggilan terpisah dalam handler webhook.