Expandir respostas

Este guia descreve como solicitar propriedades adicionais da API. Você aprenderá a modificar suas respostas para incluir:

• propriedades de objetos relacionados
• propriedades de objetos distantemente relacionados
• propriedades adicionais em todos os objetos em uma lista
• propriedades que não estão incluídas por padrão em uma resposta

Como funciona

A API Stripe é organizada em recursos representados por objetos com estado, configuração e propriedades contextuais. Esses objetos têm IDs únicos que você pode usar para recuperá-los, atualizá-los e excluí-los. A API também usa esses IDs para vincular objetos relacionados. Uma Sessão do Checkout, por exemplo, vincula a um Cliente pelo ID do cliente.

{
  "id": "cs_test_KdjLtDPfAjT1gq374DMZ3rHmZ9OoSlGRhyz8yTypH76KpN4JXkQpD2G0",
  "object": "checkout.session",
  ...
  "customer": "cus_HQmikpKnGHkNwW",
  ...
}

Em casos nos quais você precisa de informações de um objeto vinculado, é possível recuperar o objeto vinculado em uma nova chamada utilizando o ID. No entanto, essa abordagem exige duas solicitações de API para acessar apenas um valor. Se você precisar de informações de vários objetos vinculados, cada um também exige solicitações separadas, o que aumenta a latência e complexidade em seu aplicativo.

A API tem um recurso Expandir que permite recuperar objetos vinculados em uma única chamada, substituindo efetivamente o ID do objeto com todas as suas propriedades e valores. Por exemplo, digamos que você deseja acessar detalhes sobre um cliente vinculado a uma determinada Sessão do Checkout. Você recuperaria a Sessão do Checkout e passaria a propriedade customer à matriz expand, que diz à Stripe para incluir todo o objeto Customer na resposta:

curl -G https://api.stripe.com/v1/checkout/sessions/
{{SESSION_ID}} \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d "expand[]"=customer

Isso retorna a Sessão do Checkout com todo o objeto Customer em vez de seu ID:

{
  "id": "cs_test_KdjLtDPfAjT1gq374DMZ3rHmZ9OoSlGRhyz8yTypH76KpN4JXkQpD2G0",
  "object": "checkout.session",
  ...
  "customer": {
    "id": "cus_HQmikpKnGHkNwW",
    "object": "customer",
    ...
    "metadata": {
      "user_id": "user_xyz"
    },
    ...
  }
}

Expandir várias propriedades

Para expandir várias propriedades em uma chamada, adicione itens à matriz Expand. Por exemplo, se você desejar expandir o cliente e o payment_intent para uma determinada Sessão do Checkout, passe expand uma matriz com as strings customer e payment_intent:

curl -G https://api.stripe.com/v1/checkout/sessions/
{{SESSION_ID}} \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d "expand[]"=customer \
  -d "expand[]"=payment_intent

Expandir vários níveis

Se o valor que você deseja estiver aninhado profundamente em diversos recursos vinculados, é possível alcançá-lo ao expandir de forma recorrente utilizando notação de pontos. Por exemplo, para saber o tipo de forma de pagamento que foi usado para uma determinada Sessão do Checkout, primeiro você recupera o Payment Intent da Sessão do Checkout e, em seguida, recupera a forma de pagamento vinculada do Payment Intent para obter seu tipo. Com expand, você pode fazer tudo isso em uma só chamada:

curl -G https://api.stripe.com/v1/checkout/sessions/
{{SESSION_ID}} \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d "expand[]"="payment_intent.payment_method"

Isso retorna a Sessão do Checkout com os objetos PaymentIntent e PaymentMethod completos em vez de seus IDs:

{
  "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": {...},

Expandir propriedades em listas

Quando a API retorna uma lista de objetos, é possível usar a palavra-chave data para expandir uma determinada propriedade em cada objeto nela. Por exemplo, digamos que você precisa de informações sobre as formas de pagamento utilizadas por um de seus clientes. Para obter essas informações, você lista o PaymentIntents do cliente, que retorna um objeto com a seguinte estrutura:

{
  "object": "list",
  "data": [
    {
      "id": "pi_1GrvBKLHughnNhxy6N28q8gt",
      "object": "payment_intent",
      "amount": 1000,
      ...
      "payment_method": "pm_1GrvBxLHughnNhxyJjtBtHcc",
      ...
    },

Em vez de buscar cada Payment Intent na lista e recuperar as formas de pagamento vinculadas em células separadas, você pode expandir todas as formas de pagamento de uma só vez utilizando a palavra-chave data:

curl -G https://api.stripe.com/v1/payment_intents \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d customer=
{{CUSTOMER_ID}} \
  -d "expand[]"="data.payment_method"

A lista incluirá o objeto completo da forma de pagamento em cada Payment Intent:

{
  "object": "list",
  "data": [
    {
      "id": "pi_1GrvBKLHughnNhxy6N28q8gt",
      "object": "payment_intent",
      "amount": 1000,
      ...
      "payment_method": {
        "id": "pm_1GrvBxLHughnNhxyJjtBtHcc",
        "object": "payment_method",
        "billing_details": {...},
        "card": {
          "brand": "visa",
          ...

Usar expansão para solicitar propriedades incluíveis

Em alguns casos, os recursos têm propriedades que não estão incluídas por padrão. Um exemplo é a propriedade line_items da Sessão do Checkout, que só é incluída nas respostas se a solicitação usar o parâmetro expand, por exemplo:

curl -G https://api.stripe.com/v1/checkout/sessions/
{{SESSION_ID}} \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d "expand[]"=line_items

Usar expansão com webhooks

Não é possível receber eventos de webhook com propriedades que se expandem automaticamente. Os objetos enviados em eventos sempre estão em sua forma mínima. Para acessar valores aninhados em propriedades expansíveis, você deve recuperar o objeto em uma chamada separada dentro do seu gerenciador de webhooks.