Enregistrer l’utilisation pour la facturation à l’aide d’Amazon S3

Découvrez comment enregistrer des événements d’utilisation en masse à l’aide d’un compartiment de stockage Amazon S3.

Vous devez enregistrer l’utilisation dans Stripe pour facturer à vos clients les montants corrects à chaque période de facturation. Pour enregistrer l’utilisation, vous pouvez envoyer des événements de mesure de l’utilisation à Stripe à partir de votre compartiment de stockage Amazon S3. Stripe analyse, valide et transforme les données d’utilisation en événements de mesure.

Une fois les événements chargés avec succès, vous pouvez les voir sur votre facture d’abonnement.

Avant de commencer

Assurez-vous de disposer des éléments suivants :

Accès du compte administrateur au Dashboard Stripe
Accès du compte AWS à la console de gestion AWS et à votre compartiment S3

Importer les événements de mesure de l’utilisation

Vous pouvez charger les événements de mesure de l’utilisation sous la forme d’un fichier CSV, JSON ou JSON Lines.

Vous avez besoin d'aide pour un autre format de fichier ?

Si vous souhaitez charger des fichiers avec une structure différente ou dans un format personnalisé, contactez-nous.

Format du fichier et champs

Assurez-vous que votre fichier respecte le format de fichier en exemple :

Format de fichier CSV

Suivez le modèle de l’événement de mesure lorsque vous incluez les champs suivants dans votre fichier :

Champ	Description
`identifier`	Un identifiant unique de l’événement. Si vous n’en fournissez pas, Stripe peut générer l’identifiant unique. Nous vous recommandons d’utiliser un identifiant global unique.
`timestamp`	L’heure à laquelle l’événement s’est produit, mesurée en secondes depuis l’époque Unix.
`event_name`	Le nom de l’événement de mesure.
`payload_columns`	L’ensemble des colonnes contenant les noms de clé pour les clients et les valeurs d’utilisation numériques : `payload_stripe_customer_id` : L’ID client pour lequel l’événement est créé. `payload_value` : La valeur d’utilisation numérique de l’événement de mesure. Par défaut, le nom de la colonne est `payload_value`. Si vous avez indiqué un nom de champ différent lors de la création de l’événement de mesure, vous devez mettre à jour le nom de la colonne pour qu’il corresponde à la valeur de la clé. Par exemple, si vous indiquez des tokens dans `value_settings`, modifiez le nom de la colonne en conséquence : `payload_tokens`.

Préparer vos fichiers dans Amazon S3

Vous pouvez valider la configuration de votre connexion à l’aide de données bien formatées dans votre compartiment S3. Le processus de configuration affiche les fichiers disponibles et effectue une synchronisation initiale lors de la configuration de la connexion.

Accédez à votre console Amazon S3.
Assurez-vous de stocker vos fichiers dans un compartiment S3 désigné, organisé en fonction de vos préférences d’importation. Si nécessaire, suivez les instructions AWS pour créer un compartiment S3.
Pour une récupération réussie, Stripe exige que les noms de fichiers respectent les conventions d’appelation des objets S3 et que les fichiers aient une taille maximale de 1 Go.
Notez bien le nom et la région du compartiment, car vous en aurez besoin lors des étapes suivantes.
Gardez votre console de gestion AWS ouverte pour configurer un rôle IAM ultérieurement.

Configurer le connecteur Amazon S3 pour importer des fichiers

Tout d’abord, utilisez le Dashboard Stripe pour ajouter le connecteur Amazon S3.

Dans le Dashboard Stripe, sous l’onglet Gestion des données > Connecteurs, cliquez sur Ajouter un connecteur.
Dans la boîte de dialogue Choisir un connecteur, sélectionnez Amazon S3.
Dans la boîte de dialogue Exigences, saisissez un nom unique pour le Nom du connecteur, puis cliquez sur Suivant.
Suivez les étapes de la boîte de dialogue Autorisations.

Ensuite, configurez les autorisations appropriées pour le connecteur Amazon S3.

Dans la console de gestion AWS, accédez à la console IAM.
Créez une politique d’autorisation personnalisée :
- Dans le volet de navigation, cliquez sur Politiques > Créer une politique.
- Sélectionnez JSON, puis remplacez le texte de la politique existante en copiant et collant le bloc de code fourni dans le Dashboard Stripe.
- Dans la section Resource du bloc de code de l’éditeur de politique, remplacez USER_TARGET_BUCKET par le nom de compartiment que vous souhaitez utiliser.
- Cliquez sur Suivant.
- Sous Détails de la politique, ajoutez un nom. Vous pouvez également ajouter des balises.
- Cliquez sur Créer une politique.
Créez un rôle :
- Dans le volet de navigation, cliquez sur Rôles > Créer un rôle.
- Sélectionnez Politique d’autorisation personnalisée, puis copiez et collez le bloc de code fourni dans le Dashboard Stripe.
- Cliquez sur Suivant.
- Recherchez et sélectionnez la politique d’autorisation nouvellement créée pour l’activer, puis cliquez sur Suivant.
- Copiez et collez le nom de rôle fourni, puis cliquez sur Créer un rôle pour créer un nom de rôle.

Ensuite, assurez-vous d’établir une connexion entre Stripe et votre compartiment Amazon S3.

Dans la console de gestion AWS, procédez comme suit :
- Indiquez l’ID de votre compte AWS.
- Indiquez le nom et la région du compartiment.
- Si vous utilisez des dossiers pour organiser vos fichiers dans votre compartiment Amazon S3, indiquez un dossier dans le compartiment ci-dessus. Nous récupérons uniquement les données du dossier indiqué, et non de l’ensemble du compartiment.
Une fois que vous avez configuré un nouveau connecteur, l’aperçu du fichier confirme que vos informations d’identification connectent Stripe au compartiment et au dossier Amazon S3 attendus. Stripe récupère toutes les données modifiées au cours des 90 derniers jours. Cela se produit toutes les 5 minutes pour les objets dont la date LastModified est postérieure à la dernière synchronisation.
Prévisualisez les fichiers disponibles dans le compartiment Amazon S3 connecté :
- Les noms de fichiers doivent comporter moins de 255 caractères et inclure l’extension appropriée, par exemple .csv, .json ou .jsonl.
- Les importations initiales et récurrentes ont un format de fichier prédéfini :
  - Les fichiers JSON ont un modèle de transaction d’événement de mesure pour facturation - JSON.
  - Les fichiers JSON Lines ont un modèle de transaction d’événement de mesure pour facturation - JSONLINE.
  - Les fichiers CSV ont un modèle de transaction d’événement de mesure pour facturation - CSV.
Pour créer une connexion de données active et lancer l’importation de données, cliquez sur Terminé.

Une fois que vous avez chargé un fichier sur le connecteur Amazon S3, les événements d’utilisation sont mis à jour dans les 5 minutes. Cela peut prendre plus de temps si votre compartiment contient un grand nombre de fichiers non traités.

Vous pouvez vérifier l’état et les détails des fichiers traités dans l’onglet Ensemble de fichiers importés du Dashboard Stripe.

Limites de débit

Vous pouvez charger autant de fichiers et d’enregistrements que vous le souhaitez dans votre compartiment Amazon S3. Chargez un fichier toutes les 10 secondes ou lorsque le fichier en cours atteint le million d’enregistrements, selon la première éventualité. Après le chargement, vous pouvez ajouter des événements dans un nouveau fichier.

Évitez de créer des fichiers vides, tels que :

Fichiers CSV qui contiennent uniquement la ligne d’en-tête
Fichiers JSON qui contiennent uniquement [](crochets vides)
Fichiers JSON Lines qui contiennent uniquement {}(accolades vides)

Bien qu’Amazon S3 accepte les fichiers à octets non nuls, ils augmentent le nombre d’objets et de fichiers, ce qui peut entraîner des retards dans l’interrogation des fichiers.

Amazon S3 interroge un maximum de 50 fichiers ou jusqu’à 10 Go de données et traite vos données chargées à une cadence de 10 000 événements par seconde. Si vous téléchargez des fichiers volumineux ou un volume élevé de fichiers, Stripe interroge et traite les données pour maintenir ce débit.

Par exemple, si vous téléchargez 100 fichiers contenant chacun 100 000 enregistrements par jour, le traitement de l’ensemble du jeu de données (10 millions d’événements) peut prendre environ 17 minutes.

Signaler et gérer les erreurs

Stripe interroge les fichiers que vous chargez dans le compartiment Amazon S3, puis traite ces fichiers de manière asynchrone. Si nous détectons des erreurs pendant le traitement, Stripe vous en informe par des événements.

Problèmes de format

Des erreurs de format de fichier ou d’enregistrement non valides se produisent lorsque le contenu du fichier téléchargé présente des problèmes de formatage ou de données.

Vous pouvez vous abonner à ces événements à l’aide d’un endpoint de webhook. En fonction du type d’événement, vous pouvez implémenter votre propre logique pour gérer ces erreurs.

Event Description Type de charge utile

data_management.import_set.failed Stripe crée un événement data_management.import_set.failed lorsque le traitement échoue pour un fichier entier. Par exemple, en cas d’omission d’une colonne obligatoire, telle que event_name. Vous pouvez trouver la raison de l’échec dans le paramètre failed_reason de l’événement et corriger le fichier avant de le télécharger à nouveau. Snapshot

Event	Description	Type de charge utile
`data_management.import_set.failed`	Stripe crée un événement data_management.import_set.failed lorsque le traitement échoue pour un fichier entier. Par exemple, en cas d’omission d’une colonne obligatoire, telle que `event_name`. Vous pouvez trouver la raison de l’échec dans le paramètre `failed_reason` de l’événement et corriger le fichier avant de le télécharger à nouveau.	`Snapshot`
`data_management.import_set.succeeded`	Stripe crée un événement data_management.import_set.succeeded lorsque des enregistrements individuels échouent dans un fichier partiellement traité. Par exemple, en cas d’omisson d’une valeur pour un champ obligatoire, tel que `stripe_customer_id` ou `event_name`. Vous pouvez trouver les détails des enregistrements ayant échoué dans le paramètre `status` de l’événement. Un état `succeeded_with_errors` indique qu’au moins un enregistrement a échoué en raison d’une mise en forme non valide. L’état `result.errors` indique le nombre d’enregistrements qui ont échoué et l’identification `file_id` du fichier contenant les enregistrements qui ont échoué. Utilisez l’API Files pour télécharger la liste complète des enregistrements ayant échoué et les descriptions détaillées des erreurs.	`Snapshot`

data_management.import_set.succeeded

Stripe crée un événement data_management.import_set.succeeded lorsque des enregistrements individuels échouent dans un fichier partiellement traité. Par exemple, en cas d’omisson d’une valeur pour un champ obligatoire, tel que stripe_customer_id ou event_name.

Vous pouvez trouver les détails des enregistrements ayant échoué dans le paramètre status de l’événement. Un état succeeded_with_errors indique qu’au moins un enregistrement a échoué en raison d’une mise en forme non valide. L’état result.errors indique le nombre d’enregistrements qui ont échoué et l’identification file_id du fichier contenant les enregistrements qui ont échoué.

Utilisez l’API Files pour télécharger la liste complète des enregistrements ayant échoué et les descriptions détaillées des erreurs.

Snapshot

Problèmes liés aux données

Le traitement des fichiers dont la mise en forme est correcte peut échouer en raison de données non valides, telles que des valeurs incorrectes pour event_name ou stripe_customer_id.

Pour obtenir des informations détaillées sur ces échecs, vous pouvez vous abonner aux événements suivants à l’aide d’un endpoint de webhook.

Event	Description	Type de charge utile
`v1.billing.meter.error_report_triggered`	Cet événement se produit quand une mesure compte des événements d’usage non valide.	`thin`
`v1.billing.meter.no_meter_found`	Cet événement se produit quand des événements d’usage comptent des ID de mesure manquants ou non valide.	`thin`

Avertissement

Pour créer une destination d’événement abonnée aux événements légers, activez Workbench dans vos paramètres de développement.

Exemples de charges utiles

Voici un exemple de charge utile pour un événement v1.billing.meter.error_report_triggered.

{
  "id": "evt_test_65R2GpwDsnmpzihMjdT16R2GDhI4SQdXJGRbvn7JA8mPEm",
  "object": "v2.core.event",
  "created": "2024-08-28T20:54:12.051Z",
  "data": {
    "developer_message_summary": "There is 1 invalid event",
    "reason": {
      "error_count": 1,
      "error_types": [
        {

Codes d’erreur

reason.error_types.code : indique la catégorie d’erreur déclenchée. Les codes d’erreur possibles sont les suivants :

meter_event_customer_not_found
meter_event_no_customer_defined
meter_event_dimension_count_too_high
archived_meter
timestamp_too_far_in_past
timestamp_in_future
meter_event_value_not_found
meter_event_invalid_value
no_meter (pris en charge uniquement pour le type d’événement v1.billing.meter.no_meter_found)

Écouter les événements

Vous pouvez écouter des événements en configurant une destination d’événement.

Ouvrez l’onglet Destinations d’événements dans Workbench, puis cliquez sur Créer une nouvelle destination. Vous pouvez également utiliser ce modèle pour configurer une nouvelle destination dans Workbench avec ces deux types d’événements présélectionnés.
Cliquez sur Afficher les options avancées, puis sélectionnez le style de charge utile Léger.
Sélectionnezv1.billing.meter.error_report_triggered et v1.billing.meter.no_meter_found dans la liste des événements.

Créez un gestionnaire pour traiter l’événement.

Testez votre gestionnaire en configurant un écouteur local avec l’interface de ligne de commande Stripe pour envoyer des événements à votre ordinateur local à des fins de test avant de déployer le gestionnaire en production. Utilisez l’indicateur --forward-thin-to pour préciser l’URL vers laquelle transférer les événements thin et l’indicateur --thin-events pour préciser les événements légers à transférer à votre application. Vous pouvez transférer tous les événements légers marqués d’un astérisque (*) ou un sous-ensemble d’événements.
```
$ stripe listen --forward-thin-to localhost:4242/webhooks --thin-events "*"
```
Déclenchez des événements de test dans votre gestionnaire. Utilisez la fonction de déclenchement pour exécuter les commandes suivantes, qui simulent les événements respectifs dans votre compte à des fins de test.
```
$ stripe trigger v1.billing.meter.error_report_triggered --api-key <your-secret-key>
$ stripe trigger v1.billing.meter.no_meter_found --api-key <your-secret-key>
```
Si vous traitez des événements avec un endpoint de webhook, vérifiez les signatures de webhook pour sécuriser votre endpoint et vous assurer que toutes les requêtes proviennent de Stripe.
Corrigez les événements non valides et enregistrez-les dans un nouveau fichier. Ensuite, chargez le fichier dans votre compartiment Amazon S3 pour qu’il soit traité.