# Expandir respostas Saiba como reduzir o número de solicitações feitas por você à API Stripe ao expandir objetos em respostas. Este guia descreve como solicitar propriedades adicionais da API. Você aprenderá a modificar suas solicitações 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](https://docs.stripe.com/api/checkout/sessions/object.md), por exemplo, vincula a um [Cliente](https://docs.stripe.com/api/customers/object.md) pelo [ID do cliente](https://docs.stripe.com/api/checkout/sessions/object.md#checkout_session_object-customer). > Se você modelar os clientes como objetos [Account](https://docs.stripe.com/api/v2/core/accounts/object.md) configurados pelo cliente em vez de objetos [Customer](https://docs.stripe.com/api/customers/object.md), use o parâmetro [include](https://docs.stripe.com/api/v2/core/accounts/create.md#v2_create_accounts-include) em vez de `expand`. ```json { "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 curl -G https://api.stripe.com/v1/checkout/sessions/{{CHECKOUTSESSION_ID}} \ -u "<>:" \ -d "expand[]=customer" ``` Isso retorna a Sessão do Checkout com todo o objeto Customer em vez de seu ID: ```json { "id": "cs_test_KdjLtDPfAjT1gq374DMZ3rHmZ9OoSlGRhyz8yTypH76KpN4JXkQpD2G0", "object": "checkout.session", ..."customer": { "id": "cus_HQmikpKnGHkNwW", "object": "customer", ... "metadata": { "user_id": "user_xyz" }, ... } } ``` > Nem todas as propriedades podem ser expandidas. A referência da API marca as propriedades expansíveis com a etiqueta “Expansível”. ## Expandir várias propriedades Para expandir várias propriedades em uma chamada, adicione itens à matriz Expand. Por exemplo, se você desejar expandir o [cliente](https://docs.stripe.com/api/checkout/sessions/object.md#checkout_session_object-customer) e o [payment_intent](https://docs.stripe.com/api/checkout/sessions/object.md#checkout_session_object-payment_intent) para uma determinada Sessão do Checkout, passe `expand` uma matriz com as strings `customer` e `payment_intent`: ```curl curl -G https://api.stripe.com/v1/checkout/sessions/{{CHECKOUTSESSION_ID}} \ -u "<>:" \ -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 curl -G https://api.stripe.com/v1/checkout/sessions/{{CHECKOUTSESSION_ID}} \ -u "<>:" \ -d "expand[]=payment_intent.payment_method" ``` Isso retorna a Sessão do Checkout com os objetos [PaymentIntent](https://docs.stripe.com/api/payment_intents/object.md) e [PaymentMethod](https://docs.stripe.com/api/payment_methods/object.md) completos em vez de seus IDs: ```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" } ``` > As expansões têm uma profundidade máxima de quatro níveis. Isso significa que uma string `expand` pode conter no máximo quatro propriedades: `property1.property2.property3.property4`. ## 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](https://docs.stripe.com/api/payment_intents/list.md#list_payment_intents-customer), que retorna um objeto com a seguinte estrutura: ```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" } ``` > Todas as listas retornadas na API têm a estrutura acima, onde a propriedade `data` contém a matriz de objetos que estão sendo listados. Você pode usar a palavra-chave `data` em qualquer posição em uma string Expand para mover o cursor de expansão para a lista. 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 curl -G https://api.stripe.com/v1/payment_intents \ -u "<>:" \ -d "customer={{CUSTOMER_ID}}" \ -d "expand[]=data.payment_method" ``` A lista incluirá o objeto completo da forma de pagamento em cada Payment Intent: ```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" } ``` > Expandir respostas têm implicações de desempenho. Para manter as solicitações ágeis, tente limitar a quantidade de expansões aninhadas nas solicitações de lista. ## 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](https://docs.stripe.com/api/checkout/sessions/object.md#checkout_session_object-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 curl -G https://api.stripe.com/v1/checkout/sessions/{{CHECKOUTSESSION_ID}} \ -u "<>:" \ -d "expand[]=line_items" ``` > Assim como outras propriedades expansíveis, a referência da API marca as propriedades que podem ser incluídas com a etiqueta “Expansível”. ## Usar expansão com webhooks Não é possível receber eventos de *webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) 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.