# Développement des réponses Découvrez comment réduire le nombre de requêtes envoyées à l'API Stripe en développant les objets dans les réponses. Ce guide décrit la marche à suivre pour demander des propriétés supplémentaires à l’API. Vous y découvrirez comment modifier vos requêtes pour que les réponses incluent les éléments suivants : - Propriétés d’objets associés - Propriétés d’objets partageant une association lointaine - Propriétés supplémentaires de tous les objets d’une liste - Propriétés non incluses par défaut dans une réponse ## Fonctionnement L’API Stripe est organisée en ressources représentées par des objets disposant de propriétés d’état, de configuration et contextuelles. Ces objets disposent chacun d’un ID unique que vous pouvez utiliser pour les récupérer, les mettre à jour et les supprimer. L’API s’appuie aussi sur ces ID pour lier des objets associés. Par exemple, une [session Checkout](https://docs.stripe.com/api/checkout/sessions/object.md) est liée à un [client](https://docs.stripe.com/api/customers/object.md) à l’aide de son [ID client](https://docs.stripe.com/api/checkout/sessions/object.md#checkout_session_object-customer). ```json { "id": "cs_test_KdjLtDPfAjT1gq374DMZ3rHmZ9OoSlGRhyz8yTypH76KpN4JXkQpD2G0", "object": "checkout.session", ..."customer": "cus_HQmikpKnGHkNwW", ... } ``` Lorsque vous avez besoin d’informations provenant d’un objet associé, vous pouvez récupérer celui-ci par le biais d’un nouvel appel utilisant son ID. Toutefois, cette approche impose d’envoyer à l’API deux requêtes pour n’accéder qu’à une seule valeur. Si vous avez besoin d’informations provenant de plusieurs objets associés, vous devez envoyer une requête pour chacun d’eux, ce qui augmente la latence et la complexité de votre application. Pour résoudre ce problème, l’API propose la fonction Expand, qui vous permet de récupérer des objets associés en un seul appel et remplace l’ID de l’objet par l’ensemble de ses propriétés et valeurs. Imaginons par exemple que vous souhaitiez consulter les détails d’un client lié à une session Checkout donnée. Il vous suffit de récupérer cette session et de transmettre la propriété `customer` au tableau `expand`pour obtenir une réponse incluant l’intégralité de l’objet Customer : ```curl curl -G https://api.stripe.com/v1/checkout/sessions/{{CHECKOUTSESSION_ID}} \ -u "<>:" \ -d "expand[]=customer" ``` L’exemple ci-dessus renvoie la session Checkout avec l’objet Customer complet au lieu de son seul ID : ```json { "id": "cs_test_KdjLtDPfAjT1gq374DMZ3rHmZ9OoSlGRhyz8yTypH76KpN4JXkQpD2G0", "object": "checkout.session", ..."customer": { "id": "cus_HQmikpKnGHkNwW", "object": "customer", ... "metadata": { "user_id": "user_xyz" }, ... } } ``` > Toutes les propriétés ne peuvent pas être développées. La documentation sur les API signale celles qui peuvent l’être par le libellé « Peut être développée » (Expandable). ## Développement de plusieurs propriétés Pour développer plusieurs propriétés en un seul appel, ajoutez les éléments supplémentaires au tableau de développement. Par exemple, pour développer les objets [customer](https://docs.stripe.com/api/checkout/sessions/object.md#checkout_session_object-customer) et [payment_intent](https://docs.stripe.com/api/checkout/sessions/object.md#checkout_session_object-payment_intent) pour une session Checkout donnée, vous devez transmettre au tableau `expand` les chaînes `customer` et `payment_intent` : ```curl curl -G https://api.stripe.com/v1/checkout/sessions/{{CHECKOUTSESSION_ID}} \ -u "<>:" \ -d "expand[]=customer" \ -d "expand[]=payment_intent" ``` ## Développement de plusieurs niveaux Si la valeur qui vous intéresse est imbriquée profondément dans plusieurs ressources associées, vous pouvez l’atteindre par le biais d’un développement récursif en utilisant une notation par points. Par exemple, pour connaître le type du moyen de paiement utilisé pour une session Checkout, vous devez d’abord récupérer le Payment Intent de la session Checkout, puis le moyen de paiement qui lui est associé. Le mot-clé `expand` vous permet de le faire en un seul appel : ```curl curl -G https://api.stripe.com/v1/checkout/sessions/{{CHECKOUTSESSION_ID}} \ -u "<>:" \ -d "expand[]=payment_intent.payment_method" ``` L’exemple ci-dessus renvoie la session Checkout avec les objets complets[PaymentIntent](https://docs.stripe.com/api/payment_intents/object.md) et [PaymentMethod](https://docs.stripe.com/api/payment_methods/object.md) plutôt que leurs 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" } ``` > La profondeur maximale des développements est de 4 niveaux. Ainsi, une chaîne `expand` ne peut pas contenir plus de 4 propriétés : `property1.property2.property3.property4`. ## Développement de propriétés dans des listes Lorsque l’API renvoie une liste d’objets, vous pouvez utiliser le mot-clé `data` afin de développer une propriété donnée pour chaque objet de la liste. Imaginons par exemple que vous avez besoin d’informations sur les moyens de paiement utilisés par l’un de vos clients. Pour obtenir ces informations, vous devez [répertorier les PaymentIntents du client](https://docs.stripe.com/api/payment_intents/list.md#list_payment_intents-customer), ce qui renvoie un objet qui présente la structure suivante : ```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" } ``` > Toutes les listes renvoyées par l’API disposent de la structure ci-dessus, où la propriété `data` contient le tableau des objets de la liste. Vous pouvez utiliser le mot-clé `data` n’importe où dans une chaîne Expand pour déplacer le curseur de développement dans la liste. Plutôt que de traiter chaque Payment Intent de la liste et de récupérer les moyens de paiement associés dans des appels distincts, vous pouvez développer tous les moyens de paiement en une fois à l’aide du mot-clé `data` : ```curl curl -G https://api.stripe.com/v1/payment_intents \ -u "<>:" \ -d "customer={{CUSTOMER_ID}}" \ -d "expand[]=data.payment_method" ``` La liste inclut alors l’objet de moyen de paiement complet pour chaque 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" } ``` > Le développement des réponses a un impact sur les performances. Pour préserver la vitesse des requêtes, limitez le nombre de développements fortement imbriqués dans les requêtes de listes. ## Utilisation de l’expansion pour demander des propriétés pouvant être incluses Dans certains cas, les ressources disposent de propriétés qui ne sont pas incluses par défaut. La propriété [line_items](https://docs.stripe.com/api/checkout/sessions/object.md#checkout_session_object-line_items) des sessions Checkout en constitue un bon exemple : elle n’est incluse dans les réponses que si elle est explicitement demandée à l’aide du paramètre `expand`, par exemple : ```curl curl -G https://api.stripe.com/v1/checkout/sessions/{{CHECKOUTSESSION_ID}} \ -u "<>:" \ -d "expand[]=line_items" ``` > Comme les autres propriétés pouvant être développées, les propriétés pouvant être incluses sont signalées dans la documentation sur les API par l’étiquette « Peut être développée » (Expandable). ## Utilisation de l’expansion avec les webhooks Vous ne pouvez pas recevoir d’événements *webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) avec des propriétés développées automatiquement. Les objets envoyés dans les événements sont toujours présentés sous leur forme minimale. Pour accéder aux valeurs imbriquées dans des propriétés pouvant être développées, vous devez récupérer l’objet via un appel distinct au sein de votre gestionnaire de webhooks.