Rechercher

Recherchez des objets dans vos données Stripe.

Certaines ressources API de niveau supérieur prennent en charge la récupération d’informations via des méthodes de recherche sur l’API . Vous pouvez utiliser les API de recherche pour récupérer vos objets Stripe comme bon vous semble. Cette méthode s’avère plus efficace que de parcourir page par page l’ensemble des ressources. Pour créer une requête de recherche, vérifiez le langage de requête de recherche et référencez les champs de requête de la ressource :

Limitations

Version minimale de l’API

La version minimale de l’API prise en charge pour utiliser la recherche est 2020-08-27. Pour en savoir plus sur les mises à niveau, consultez notre guide consacré aux mises à niveau de l’API. Pour utiliser la fonction de recherche sans mettre à niveau la version de l’API de votre compte, vous pouvez remplacer cette dernière via une unique requête en définissant un en-tête de requête Stripe-Version :

Command Line

-H "Stripe-Version: 2024-11-20.acacia"

Consultez notre guide sur les SDK pour savoir comment remplacer une version d’API lors de l’utilisation d’une bibliothèque.

Actualisation des données

N’utilisez pas la recherche pour les flux de lecture après écriture (par exemple, effectuer une recherche immédiatement après un paiement) car les données ne seront pas immédiatement disponibles pour la recherche. Dans des conditions de fonctionnement normales, les données sont consultables en moins d’1 minute. En cas de panne, la propagation de nouvelles données ou de données mises à jour peut prendre plus de temps.

For read-after-write flows that require immediate data availability, use the various list APIs, such as List invoices). These APIs aren’t subject to the availability delays mentioned above.

Limites de débit

Nous appliquons une limite de débit de 20 opérations par seconde en lecture qui s’applique à tous les endpoints de recherche, en mode production comme en mode test. Ces deux modes ont des limites distinctes. Compte tenu de la limite de débit, pour les charges de travail pour lesquelles vous devez exécuter des analyses sur une ou plusieurs ressources d’API, Sigma est beaucoup plus efficace. Pour les charges de travail pour lesquelles vous devez exporter une grande partie de vos ressources d’API, notre produit Data Pipeline est à privilégier.

Disponibilité régionale

La fonction de recherche n’est pas disponible pour les marchands établis en Inde.

Objets de l’horloge de simulation omis dans la liste de tous les résultats

Les API de liste de Stripe (telles que Liste de factures) omettent les résultats générés par les horloges de simulation pour toutes les requêtes de liste. Pour voir les résultats générés par les horloges de simulation dans ces cas, vous devez demander des résultats dans un parent spécifique, tel que test_clock, customer ou subscription.

Par exemple, GET /v1/invoices ne renverra pas les factures générées par l’horloge de simulation, mais GET {customer_id} renverra toutes les factures pour ce client, y compris celles qui sont générées par l’horloge de simulation.

De même, vous pouvez spécifier un identifiant d’horloge de simulation dans cet exemple pour obtenir toutes les factures liées à cette horloge, ou spécifier un identifiant d’abonnement pour obtenir toutes les factures relatives à cet abonnement, y compris les factures générées par l’horloge de simulation.

Exemples

Voici quelques exemples de ce que vous pouvez faire avec l’API Search Charges et l’API Search PaymentIntents :

Recherche des paiements en fonction de métadonnées

Recherchez les paiements correspondant à une valeur des métadonnées personnalisée.

Recherche des paiements en fonction des 4 derniers chiffres

Recherchez les paiements correspondant aux 4 derniers chiffres de la carte bancaire utilisée pour le paiement.

Recherche de clients en fonction de leur adresse e-mail

Recherchez des clients correspondant à une adresse e-mail.

Filtre d’exclusion

Recherchez les PaymentIntents pour lesquels la devise n’est pas USD.

Filtre numérique

Filtrez les objets Invoice dont le total est supérieur à 1000.

Combinaison de plusieurs filtres

Recherchez les paiements correspondant à une combinaison de métadonnées et de devises.

Langage de requête de recherche

Structure et terminologie des requêtes

Une clause de requête est composée d’un champ field suivi d’un opérateur operator, lui-même suivi d’une valeur value :

clause	`email:"amy@rocketrides.io"`
champ	`email`
opérateur	`:`
valeur	`amy@rocketrides.io`

Vous pouvez combiner plusieurs clauses de requête dans une recherche en les séparant par une espace ou en utilisant les mots-clés AND ou OR (insensibles à la casse). Vous ne pouvez pas combiner AND et OR dans la même requête. En outre, il n’est pas possible d’utiliser des parenthèses pour donner la priorité à certains opérateurs logiques. Par défaut, l’API combine les clauses avec la logique AND.

L’exemple de requête email:"amy@rocketrides.io" metadata["key"]:"value" renvoie les enregistrements pour lesquels l’adresse e-mail est amy@rocketrides.io et les métadonnées de l’enregistrement comprennent key avec une valeur égale à value.

Création d’une requête qui ne correspond pas à une clause

Vous pouvez exclure des clauses d’une requête en utilisant le caractère -. Par exemple, la recherche suivante renvoie les enregistrements qui ne correspondent pas à l’adresse e-mail amy@rocketrides.io.

-email:"amy@rocketrides.io"

Types de champs, correspondance de sous-chaînes et comparateurs numériques

Le caractère : permet à chaque champ de recherche de prendre en charge la correspondance exacte. Certains champs, tels que email et name, prennent en charge la correspondance de sous-chaîne. Certains autres champs, tels que amount, prennent en charge les comparateurs numériques comme > et <.

Le type d’un champ détermine les opérations que vous pouvez utiliser sur ce champ. Pour obtenir la liste complète des champs disponibles, consultez la section Champs de requête pris en charge pour chaque ressource.

L’utilisation d’un opérateur non pris en charge, comme le fait de spécifier supérieur à (>) sur une chaîne, renvoie une erreur.

type opérateurs

token correspondance exacte (sans distinction de casse)

type	opérateurs
token	correspondance exacte (sans distinction de casse)
chaîne	correspondance exacte, sous-chaîne (sans distinction de casse) Une correspondance exacte du type de chaîne renvoie tous les enregistrements contenant l’ensemble des mots de la requête dans le même ordre. Par exemple, la requête `name:"one two three"` afficherait les enregistrements contenant “one two three” et “one two three four”.
numérique	correspondance exacte, supérieur à et inférieur à

chaîne

correspondance exacte, sous-chaîne (sans distinction de casse)

Une correspondance exacte du type de chaîne renvoie tous les enregistrements contenant l’ensemble des mots de la requête dans le même ordre. Par exemple, la requête name:"one two three" afficherait les enregistrements contenant “one two three” et “one two three four”.

numérique correspondance exacte, supérieur à et inférieur à

Guillemets

Vous devez placer les valeurs de type chaîne entre guillemets. Les guillemets sont facultatifs pour les valeurs numériques. Par exemple :

currency:"usd" signifie que les guillemets sont obligatoires.
payment_method_details.card.last4:1234 indique que les guillemets sont facultatifs.

Vous pouvez échapper les guillemets à l’intérieur de guillemets avec une barre oblique inverse (\).

description:"l'histoire s'intitule \"Le ciel et la mer.\""

Métadonnées

Vous pouvez effectuer des recherches sur des métadonnées que vous avez ajoutées aux objets qui les prennent en charge.

Utilisez le format suivant pour créer une clause pour une recherche de métadonnées : metadata["<field>"]:"<value>".

La clause suivante montre comment créer une clause qui recherche les enregistrements ayant un numéro de don de “asdf-jkl”: metadata["id-don"]:"asdf-jkl".

Vous pouvez rechercher une clé de métadonnées sur un objet. La clause suivante renvoie tous les enregistrements pour lesquels donation-id est une clé de métadonnées. -metadata["donation-id"]:null

Syntaxe de Search

Le tableau suivant répertorie la syntaxe que vous pouvez utiliser pour créer une requête.

Syntaxe	Utilisation	Description	Exemples
`:`	`field:value`	Opérateur de correspondance exacte (insensible à la casse)	`currency:"eur"` renvoie les enregistrements dont la devise est exactement « EUR » (la comparaison ne tient pas compte de la casse)
`AND`, `and`	`field:value1 AND field:value2`	La requête renvoie uniquement les enregistrements qui correspondent aux deux clauses (sans distinction de casse)	`status:"active" AND amount:500`
`OR`, `or`	`field:value1 OR field:value2`	La requête renvoie les enregistrements qui correspondent à l’une ou l’autre des clauses (sans distinction de casse)	`currency:"usd" OR currency:"eur"`
`-`	`-field:value`	Renvoie les enregistrements qui ne correspondent pas à la clause	`-currency:"jpy"` renvoie les enregistrements dont la devise n’est pas le JPY
`NULL`, `null`	`field:null`	Token spécifique utilisé pour la présence du champ (sans distinction de casse).	`url:null` renvoie les enregistrements pour lesquels le champ URL est vide
`\`	`" \"\""`	Échapper des guillemets au sein de guillemets	`description:"l'histoire s'intitule \"Le ciel et la mer.\""`
`~`	`field~value`	Opérateur de correspondance des sous-chaînes (les sous-chaînes doivent comporter au moins 3 caractères)	`email~"amy"` renvoie des correspondances pour amy@rocketrides.io et xamy
`>`, `<`, `=`	`field<value` `field>value` `field>=value` `field<=value`	Opérateurs supérieur à/inférieur à	`amount>="10"` renvoie les objets dont le montant est supérieur ou égal à 10

Champs de requête pris en charge pour chaque ressource

Champs de requête pour les paiements

Champ	usage	Type (token, chaîne, valeur numérique)
amount	`amount>1000`	numérique
billing_details.address.postal_code	`billing_details.address.postal_code:12345`	token
created	`created>1620310503`	numérique
currency	`currency:"usd"`	token
customer	`customer:"cus_123"`	token
disputed	`disputed:"true"`	token
metadata	`metadata["key"]:"value"`	token
payment_method_details.{{SOURCE}}.last4	`payment_method_details.card.last4:1234`	token
payment_method_details.{{SOURCE}}.exp_month	`payment_method_details.card_present.exp_month:12`	token
payment_method_details.{{SOURCE}}.exp_year	`payment_method_details.interac_present.exp_year:2022`	token
payment_method_details.{{SOURCE}}.brand	`payment_method_details.card.brand:"visa"`	token
payment_method_details.{{SOURCE}}.fingerprint	`payment_method_details.card.fingerprint:"fp"`	token
refunded	`refunded:"true"`	token
status	`status:"succeeded"`	token

Pour SOURCE, utilisez card , card_present ou interac_present . Utilisez card pour les paiements en ligne, interac_present pour les paiements Terminal par carte sur le réseau Interac et card_present pour les autres paiements Terminal par carte.

Le champ disputed accepte uniquement les tokens « true » et « false » et indique la présence de litiges.

Filtres refunded:"true" pour les paiements intégralement remboursés, filtres refunded:"false" pour les paiements partiellement remboursés et filtres refunded:null pour les paiements non remboursés.

Champs de requête pour les clients

Champ	usage	Type (token, chaîne, valeur numérique)
created	`created>1620310503`	numérique
email	`email~"amyt"`	chaîne
metadata	`metadata["key"]:"value"`	token
name	`name~"amy"`	chaîne
phone	`phone:"+19999999999"`	chaîne

Champs de requête pour les factures

Champ	usage	Type (token, chaîne, valeur numérique)
created	`created>1620310503`	numérique
currency	`currency:"usd"`	token
customer	`customer:"cus_123"`	token
last_finalization_error_code	`last_finalization_error_code:"customer_tax_location_invalid"`	token
last_finalization_error_type	`last_finalization_error_type:"invalid_request_error"`	token
metadata	`metadata["key"]:"value"`	token
number	`number:"MYSHOP-123"`	chaîne
receipt_number	`receipt_number:"RECEIPT-123"`	chaîne
status	`status:"open"`	chaîne
subscription	`subscription:"SUBS-123"`	chaîne
total	`total>1000`	numérique

Champs de requête pour les PaymentIntents

Champ	usage	Type (token, chaîne, valeur numérique)
amount	`amount>1000`	numérique
created	`created>1620310503`	numérique
currency	`currency:"usd"`	token
customer	`customer:"cus_123"`	token
metadata	`metadata["key"]:"value"`	token
status	`status:"succeeded"`	token

Champs de requête pour les tarifs

Champ	usage	Type (token, chaîne, valeur numérique)
active	`active:"true"`	token
currency	`currency:"usd"`	token
lookup_key	`lookup_key:"standard_monthly"`	chaîne
metadata	`metadata["key"]:"value"`	token
product	`product:"prod_123"`	chaîne
type	`type:"recurring"`	token

Champs de requête pour les produits

Champ	usage	Type (token, chaîne, valeur numérique)
active	`active:"true"`	token
description	`description~"t-shirts"`	chaîne
metadata	`metadata["key"]:"value"`	token
name	`name~"amy"`	chaîne
shippable	`shippable:"true"`	token
url	`url~"/dinosaur_swag"`	chaîne

Champs de requête pour les abonnements

Champ	usage	Type (token, chaîne, valeur numérique)
created	`created>1620310503`	numérique
metadata	`metadata["key"]:"value"`	token
status	`status:"active"`	token
canceled_at	`canceled_at>1721521117`	numérique