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 se vincula con un objeto Customer mediante el ID de cliente.
{ "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:
Esto devuelve la sesión de Checkout con el objeto Customer completo en lugar de su ID:
{ "id": "cs_test_KdjLtDPfAjT1gq374DMZ3rHmZ9OoSlGRhyz8yTypH76KpN4JXkQpD2G0", "object": "checkout.session", ... "customer": { "id": "cus_HQmikpKnGHkNwW", "object": "customer", ... "metadata": { "user_id": "user_xyz" }, ... } }
Nota
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 y payment_intent para una determinada sesión de Checkout, debes especificar expand una matriz con las cadenas customer y payment_:
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:
Esto devuelve la sesión de Checkout con los objetos PaymentIntent y PaymentMethod completos en lugar de sus ID:
{ "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": {...},
Nota
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..
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. Obtendrás un objeto con la siguiente estructura:
{ "object": "list", "data": [ { "id": "pi_1GrvBKLHughnNhxy6N28q8gt", "object": "payment_intent", "amount": 1000, ... "payment_method": "pm_1GrvBxLHughnNhxyJjtBtHcc", ... },
Nota
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 dataen 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:
La lista incluirá el objeto completo del método de pago en 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", ...
Nota
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 de la sesión de Checkout solo se incluye en las respuestas si se solicita usando el parámetro expand. Veamos un ejemplo:
Nota
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 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.