Cómo expandir las respuestas
Descubre cómo reducir el número 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 recuperarlos, actualizarlos o eliminarlos. La API también utiliza estos ID para agrupar objetos relacionados. Por ejemplo, una Checkout Session 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 planteamiento 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 añadirá 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 la API señala las propiedades que pueden expandirse con la etiqueta “Expandible”.
Cómo expandir varias propiedades
Para expandir varias propiedades en una llamada, añade objetos adicionales a la matriz de expansión. Por ejemplo, si quieres expandir customer y payment_intent para una determinada Checkout Session, 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 las propiedades dentro de 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 necesitases información sobre los métodos de pago utilizados por uno de tus clientes, tendrías que incluir en una lista 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 las respuestas afectan al funcionamiento. Para que las solicitudes sean rápidas, intenta limitar el número 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 incluidas de manera predeterminada. Por ejemplo, la propiedad line_items de la Checkout Session 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 la 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 webhooks 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.