Inclure des valeurs de réponse dépendantes dans l'API v2
Découvrez comment gérer les réponses de l'API qui renvoient null par défaut pour certaines propriétés.
Certaines réponses de l’API v2 contiennent des valeurs nulles pour certaines propriétés par défaut, quelles que soient leurs valeurs réelles. Cela réduit la taille des charges utiles de réponse tout en maintenant la structure de réponse de base. Pour récupérer les valeurs réelles de ces propriétés, spécifiez-les dans le paramètre de requête tableau include
Pour déterminer si vous devez utiliser le paramètre include dans une requête donnée, consultez la description de la requête. Les valeurs d’énumération du paramètre include représentent les propriétés de réponse qui dépendent du paramètre include.
Dépendance aux endpoints
La valeur par défaut d’une propriété de réponse sur null dépend de l’endpoint de la requête, et non de l’objet référencé par l’endpoint. Si plusieurs endpoints renvoient des données du même objet, une propriété particulière peut dépendre de include dans un endpoint et renvoyer sa valeur réelle par défaut pour un endpoint différent.
Une propriété de hachage peut dépendre d’une seule valeur d’include ou de plusieurs valeursinclude associées à ses propriétés enfants. Par exemple, lors de la mise à jour d’un compte, pour renvoyer des valeurs réelles pour l’ensemble du hachage identity, spécifiez identity dans le paramètre include. Sinon, le hachageidentity sera nul dans la réponse. Cependant, pour renvoyer des valeurs réelles pour le hachage configuration, vous devez spécifier des configurations individuelles dans la requête. Si vous en indiquez au moins une, les configurations spécifiées renverront leurs valeurs réelles, tandis que les autres resteront nulles. Si vous n’en indiquez aucune, le hachage configuration sera nul dans la réponse.
L’exemple suivant met à jour un Account pour ajouter les configurations customer et merchant, mais ne spécifie aucune propriété dans le paramètre include :
La réponse peut ressembler à ceci :
{ "id": "acct_123", "object": "v2.core.account", "applied_configurations": [ "customer", "merchant" ], "configuration": null, "contact_email": "furever@example.com", "created": "2025-06-09T21:16:03.000Z", "dashboard": "full", "defaults": null, "display_name": "Furever", "identity": null, "livemode": true, "metadata": {}, "requirements": null }
Cet exemple effectue la même requête, mais spécifie configuration. et identity dans le paramètre include :
La réponse contient des informations sur la configuration customer et suridentity, mais renvoie null pour toutes les autres configurations :
{ "id": "acct_123", "object": "v2.core.account", "applied_configurations": [ "customer", "merchant" ], "configuration": { "customer": { "automatic_indirect_tax": { ... }, "billing": { ... }, "capabilities": { ... }, ... }, "merchant": null, "recipient": null }, "contact_email": "furever@example.com", "created": "2025-06-09T21:16:03.000Z", "dashboard": "full", "defaults": null, "display_name": "Furever", "identity": { "business_details": { "doing_business_as": "FurEver", "id_numbers": [ { "type": "us_ein" } ], "product_description": "Saas pet grooming platform at furever.dev using Connect embedded components", "structure": "sole_proprietorship", "url": "http://accessible.stripe.com" }, "country": "US" }, "livemode": true, "metadata": {}, "requirements": null }