# 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).

> Jika Anda merepresentasikan pengguna sebagai objek [Account](https://docs.stripe.com/api/v2/core/accounts/object.md) yang dikonfigurasi oleh pelanggan dan bukan sebagai objek [Customer](https://docs.stripe.com/api/customers/object.md), gunakan parameter [include](https://docs.stripe.com/api/v2/core/accounts/create.md#v2_create_accounts-include) bukan `expand`.

```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 "<<YOUR_SECRET_KEY>>:" \
  -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 "<<YOUR_SECRET_KEY>>:" \
  -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 "<<YOUR_SECRET_KEY>>:" \
  -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 "<<YOUR_SECRET_KEY>>:" \
  -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 "<<YOUR_SECRET_KEY>>:" \
  -d "expand[]=line_items"
```

## Ekspansi dengan webhook

Anda tidak dapat menerima kejadian *webhook* (A configurable endpoint that executes when it receives certain event notifications from an event destination) 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.

## Ekspansi dengan TypeScript

Saat menggunakan [stripe-node](https://github.com/stripe/stripe-node) SDK dengan TypeScript, tipe kolom yang dapat diekspansi adalah `string | Foo` (di mana `Foo` adalah tipe objek yang diekspansi). Tipe union ini mencerminkan fakta bahwa kolom dapat berisi string ID yang tidak diekspansi atau objek lengkap yang diekspansi. Setelah Anda mengekspansi sebuah kolom, Anda harus melakukan cast ke tipe objek yang sesuai untuk mengakses propertinya. Cast ini diperlukan karena TypeScript tidak dapat menyimpulkan pada saat kompilasi apakah sebuah kolom berisi string ID atau objek lengkap yang diekspansi. Tanpa cast, TypeScript memperlakukan kolom sebagai `string | Stripe.Customer | Stripe.DeletedCustomer | null` dan mencegah akses properti secara langsung.

Sebagai contoh, untuk mengakses alamat email dari kolom `customer` yang diekspansi pada sebuah `PaymentIntent`:

```typescript
const paymentIntent = await stripe.paymentIntents.retrieve(
  'pi_123456789',
  {
    expand: ['customer'],
  }
);

// Cast the expanded field to the expected object type to access its properties
const customerEmail: string | null = (paymentIntent.customer as Stripe.Customer).email;
```