# Cómo expandir respuestas Descubre cómo reducir la cantidad de solicitudes que haces a la API de Stripe expandiendo los objetos en las respuestas. Esta guía describe cómo solicitar propiedades adicionales desde la API. Aprenderás a modificar tus solicitudes para incluir lo siguiente: - propiedades de objetos relacionados - propiedades de objetos relacionados de manera distante - propiedades adicionales de todos los objetos de una lista - propiedades no incluidas de manera predeterminada en una respuesta ## Cómo funciona La API de Stripe se organiza conforme a recursos representados por objetos con un estado, una configuración y propiedades contextuales. Estos objetos tienen un único ID que puedes utilizar para recuperar, actualizar o eliminarlos. La API también utiliza estos ID para agrupar objetos relacionados. Por ejemplo, una [sesión de Checkout](https://docs.stripe.com/api/checkout/sessions/object.md) se vincula con un objeto [Customer](https://docs.stripe.com/api/customers/object.md) mediante el [ID de cliente](https://docs.stripe.com/api/checkout/sessions/object.md#checkout_session_object-customer). ```json { "id": "cs_test_KdjLtDPfAjT1gq374DMZ3rHmZ9OoSlGRhyz8yTypH76KpN4JXkQpD2G0", "object": "checkout.session", ..."customer": "cus_HQmikpKnGHkNwW", ... } ``` En caso de que necesites información de un objeto vinculado, puedes recuperarlo en una nueva llamada usando su ID. Sin embargo, este enfoque requiere que las dos solicitudes de API accedan a un solo valor. Si necesitas información de varios objetos vinculados, cada uno requerirá una solicitud separada, lo que le agregará tiempo de espera y complejidad a tu aplicación. La API tiene una función Expandir que te permite recuperar los objetos vinculados mediante una sola llamada, reemplazando el ID del objeto por todas sus propiedades y valores. Por ejemplo, si quieres acceder a datos de un cliente vinculado a una determinada sesión de Checkout, debes recuperar la sesión de Checkout y especificar la propiedad `customer` en la matriz `expand`, con lo que se le indica a Stripe que incluya todo el objeto Customer en la respuesta: ```curl curl -G https://api.stripe.com/v1/checkout/sessions/{{CHECKOUTSESSION_ID}} \ -u "<>:" \ -d "expand[]=customer" ``` Esto devuelve la sesión de Checkout con el objeto Customer completo en lugar de su ID: ```json { "id": "cs_test_KdjLtDPfAjT1gq374DMZ3rHmZ9OoSlGRhyz8yTypH76KpN4JXkQpD2G0", "object": "checkout.session", ..."customer": { "id": "cus_HQmikpKnGHkNwW", "object": "customer", ... "metadata": { "user_id": "user_xyz" }, ... } } ``` > No todas las propiedades se pueden expandir. La referencia de API señala las propiedades que pueden ser expandidas con la etiqueta “Expandible” . ## Expansión de varias propiedades Para expandir varias propiedades en una llamada, agrega ítems adicionales a la matriz de expansión. Por ejemplo, si quieres expandir [customer](https://docs.stripe.com/api/checkout/sessions/object.md#checkout_session_object-customer) y [payment_intent](https://docs.stripe.com/api/checkout/sessions/object.md#checkout_session_object-payment_intent) para una determinada sesión de Checkout, debes especificar `expand` una matriz con las cadenas `customer` y `payment_intent`: ```curl curl -G https://api.stripe.com/v1/checkout/sessions/{{CHECKOUTSESSION_ID}} \ -u "<>:" \ -d "expand[]=customer" \ -d "expand[]=payment_intent" ``` ## Cómo expandir varios niveles Si el valor que necesitas está anidado a mucha profundidad en varios recursos vinculados, puedes acceder a él por medio de una expansión recursiva usando una notación de puntos. Por ejemplo, si necesitas conocer el tipo de método de pago que se utilizó en una determinada sesión de Checkout, primero tienes que recuperar el intento de pago de la sesión de Checkout y luego el método de pago vinculado con ese intento de pago. Con `expand`, puedes hacer esto en una sola llamada: ```curl curl -G https://api.stripe.com/v1/checkout/sessions/{{CHECKOUTSESSION_ID}} \ -u "<>:" \ -d "expand[]=payment_intent.payment_method" ``` Esto devuelve la sesión de Checkout con los objetos [PaymentIntent](https://docs.stripe.com/api/payment_intents/object.md) y [PaymentMethod](https://docs.stripe.com/api/payment_methods/object.md) completos en lugar de sus ID: ```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" } ``` > Las expansiones tienen un máximo de profundidad de cuatro niveles. Esto significa que una cadena `expand` no puede contener más de 4 propiedades: `property1.property2.property3.property4`. ## Cómo expandir propiedades en listas Cuando la API devuelve una lista de objetos, puedes usar la palabra clave `data` para expandir una determinada propiedad de cada objeto de la lista. Por ejemplo, si necesitas información sobre los métodos de pago utilizados por uno de tus clientes, debes hacer una [lista de los PaymentIntents del cliente](https://docs.stripe.com/api/payment_intents/list.md#list_payment_intents-customer). Obtendrás un objeto con la siguiente estructura: ```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 las listas que devuelve la API tienen la estructura que aparece arriba, en la cual la propiedad `data` contiene la matriz de los objetos enumerados. Puedes utilizar la palabra clave `data`en cualquier posición en una cadena Expand para mover el cursor de expansión a la lista. En lugar de recorrer cada Payment Intent de la lista y recuperar los métodos de pago vinculados en llamadas separadas, puedes expandir todos los métodos de pago al mismo tiempo utilizando la palabra clave `data`: ```curl curl -G https://api.stripe.com/v1/payment_intents \ -u "<>:" \ -d "customer={{CUSTOMER_ID}}" \ -d "expand[]=data.payment_method" ``` La lista incluirá el objeto completo del método de pago en 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" } ``` > La expansión de respuestas tiene implicancias de funcionamiento. Para hacer que las solicitudes sigan siendo rápidas, intenta limitar la cantidad de expansiones anidadas en las solicitudes de listas. ## Uso de la expansión para solicitar propiedades que se pueden incluir En algunos casos, los recursos tienen propiedades que no están incluidos de manera predeterminada. Por ejemplo, la propiedad [line_items](https://docs.stripe.com/api/checkout/sessions/object.md#checkout_session_object-line_items) de la sesión de Checkout solo se incluye en las respuestas si se solicita usando el parámetro `expand`. Veamos un ejemplo: ```curl curl -G https://api.stripe.com/v1/checkout/sessions/{{CHECKOUTSESSION_ID}} \ -u "<>:" \ -d "expand[]=line_items" ``` > Tal como ocurre con otras propiedades expandibles, la referencia de API señala las propiedades que pueden ser incluidas con la etiqueta “Expandible”. ## Cómo usar la expansión con webhooks No puedes recibir eventos de *webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) con propiedades expandidas automáticamente. Los objetos enviados en eventos están siempre en su mínima expresión. Para acceder a valores anidados en propiedades expandibles, debes recuperar el objeto mediante una llamada separada dentro de tu controlador de webhooks.