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 explique comment demander des propriétés supplémentaires à l’API. Vous apprendrez à modifier vos requêtes afin d’inclure :
- 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 est liée à un client par le biais de son ID client.
Remarque
{ "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 expandpour obtenir une réponse incluant l’intégralité de l’objet Customer :
L’exemple ci-dessus renvoie la session Checkout avec l’objet Customer complet au lieu de son seul ID :
{ "id": "cs_test_KdjLtDPfAjT1gq374DMZ3rHmZ9OoSlGRhyz8yTypH76KpN4JXkQpD2G0", "object": "checkout.session", ... "customer": { "id": "cus_HQmikpKnGHkNwW", "object": "customer", ... "metadata": { "user_id": "user_xyz" }, ... } }
Remarque
Toutes les propriétés ne peuvent pas être développées. La documentation de l’API signale celles qui peuvent l’être par le libellé « Peut être développée ».
Développement de plusieurs propriétés
Pour développer plusieurs propriétés en un seul appel, ajoutez les éléments correspondants au tableau Expand. Par exemple, pour développer les objets customer et payment_intent pour une session Checkout donnée, vous devez transmettre au tableau expand les chaînes customer et payment_ :
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 :
L’exemple ci-dessus renvoie la session Checkout avec les objets PaymentIntent et PaymentMethod complets plutôt que leurs seuls 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": {...},
Remarque
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..
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 cette 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 Payment Intents du client, ce qui renvoie un objet présentant la structure suivante :
{ "object": "list", "data": [ { "id": "pi_1GrvBKLHughnNhxy6N28q8gt", "object": "payment_intent", "amount": 1000, ... "payment_method": "pm_1GrvBxLHughnNhxyJjtBtHcc", ... },
Remarque
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 :
La liste inclut alors l’objet de moyen de paiement complet pour chaque 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", ...
Remarque
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.
Utiliser le développement pour effectuer des requêtes de 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 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 :
Remarque
Comme les autres propriétés pouvant être développées, les propriétés pouvant être incluses sont signalées dans la documentation de l’API par l’étiquette « Peut être développée ».
Développement avec les webhooks
Vous ne pouvez pas recevoir d’événements webhook 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.
Développement avec TypeScript
Lorsque vous utilisez le SDK stripe-node avec TypeScript, les types des champs développés sont de la forme string | Foo (où Foo est le type de l’objet une fois le champ développé). Ce type union reflète le fait que le champ peut contenir soit un identifiant sous forme de chaîne, soit un objet entièrement développé. Après le développement d’un champ, vous devez convertir le champ vers le type d’objet approprié pour accéder à ses propriétés. Cette conversion est nécessaire car TypeScript ne peut pas déterminer au moment de la compilation si un champ contient une chaîne d’identifiant ou un objet développé complet. Sans cette conversion, TypeScript considère le champ comme string | Stripe. et empêche l’accès direct aux propriétés.
Par exemple, pour accéder à l’adresse e-mail d’un champ customer développé sur un PaymentIntent :
const paymentIntent = await stripe.paymentIntents.retrieve( 'pi_123456789', { expand: ['customer'], } ); // Cast the expanded field to the expected object type to access its properties const customerEmail: string | null = (paymentIntent.customer as Stripe.Customer).email;