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 est liée à un client à l’aide de son ID client.

{
  "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"
    },
    ...
  }
}

Remarques

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 et payment_intent pour une session Checkout donnée, vous devez transmettre au tableau expand les chaînes customer et 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 :

L’exemple ci-dessus renvoie la session Checkout avec les objets completsPaymentIntent et PaymentMethod plutôt que leurs 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": {...},

Remarques

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, ce qui renvoie un objet qui présente la structure suivante :

{
  "object": "list",
  "data": [
    {
      "id": "pi_1GrvBKLHughnNhxy6N28q8gt",
      "object": "payment_intent",
      "amount": 1000,
      ...
      "payment_method": "pm_1GrvBxLHughnNhxyJjtBtHcc",
      ...
    },

Remarques

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",
          ...

Remarques

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 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 :

Remarques

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 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.