> ## Documentation Index > Fetch the complete documentation index at: https://docs.metronome.com/llms.txt > Use this file to discover all available pages before exploring further. # Démarrage rapide de l'API > Obtenez votre première facture avec l'API Metronome Ce guide vous accompagne dans l'API de Metronome pour configurer la facturation par programmation — depuis la création de votre première métrique facturable jusqu'à la visualisation d'une facture fonctionnelle. **Vous cherchez le guide de l'interface utilisateur ?** Si vous préférez configurer la facturation via le tableau de bord Metronome, consultez le [démarrage rapide de l'interface utilisateur](/fr/guides/get-started/metronome-dashboard-quickstart). ## Prérequis * Un compte sandbox Metronome ([inscrivez-vous ici](https://signup.metronome.com/)) * Votre jeton d'API sandbox Metronome (**Connexions → Jetons d'API et webhooks** dans le tableau de bord) ### Environnements et authentification L'environnement est entièrement déterminé par votre jeton d'API. Un jeton sandbox ne fonctionne qu'avec les données sandbox ; un jeton de production ne fonctionne qu'avec les données de production. Toutes les requêtes nécessitent un jeton Bearer. ## Étape 1 : Comprendre comment les pièces s'assemblent Avant de construire quoi que ce soit, voici comment les objets centraux de Metronome se connectent : Objets centraux de Metronome Metronome sépare la *mesure* (ce que vous mesurez) de la *tarification* (ce que vous facturez). Vous pouvez changer la tarification sans changer votre instrumentation d'événements, et vice versa. Voici ce que fait chaque objet : * **Événements d'utilisation** — Enregistrements bruts de l'activité du client envoyés à Metronome (par exemple, « le client X a utilisé 1 500 tokens d'entrée sur le modèle gpt-5 à l'horodatage Z ») * **Métriques facturables** — Règles qui agrègent vos événements en quantités facturables (par exemple, « somme de la propriété `input_tokens` pour les événements de type `llm_request` »). C'est également là où vous définissez les **clés de groupe** — les propriétés que vous utiliserez pour tarifer ou afficher sur les factures. * **Produits** — Postes nommés sur une facture. * **Cartes tarifaires** — Un livre de prix centralisé attribuant un prix à chaque produit. Une seule carte tarifaire peut être partagée entre de nombreux clients, ce qui facilite le déploiement des mises à jour de tarification. * **Contrats** — Accords spécifiques au client référençant une carte tarifaire, définissant la période de facturation et incluant optionnellement des crédits, engagements ou remplacements. * **Packages** — Encode votre carte tarifaire et les détails du contrat dans un seul package à appliquer à de nouveaux clients. * **Factures** — Générées automatiquement à chaque période de facturation en fonction des frais récurrents et de l'utilisation d'un client, tarifées par rapport au contrat. **Ce que vous devez créer (dans cet ordre) :** 1. Une métrique facturable 2. Un produit 3. Une carte tarifaire avec des taux pour chaque produit 4. Un client 5. Un contrat reliant le client à la carte tarifaire Ensuite, vous envoyez des événements et Metronome s'occupe du reste. ## Étape 2 : Concevoir votre schéma d'événements Avant de créer quoi que ce soit, décidez à quoi ressemblent vos événements d'utilisation. Chaque événement envoyé à Metronome a cette structure : ```json theme={null} { "transaction_id": "2026-03-09T14:30:00Z_req_abc123", "customer_id": "your-customer-uuid-in-metronome", "event_type": "llm_request", "timestamp": "2026-03-09T14:30:00Z", "properties": { "model": "gpt-5", "input_tokens": "1500", "output_tokens": "350", "provider": "openai", "region": "us-east-1", "user_id": "user_8f3a", "cost": "0.0042" } } ``` ### Champs requis * **`transaction_id`** — Unique par événement pour l'idempotence. Si le même `transaction_id` est envoyé deux fois, Metronome déduplique. Conseil : combinez horodatage + ID de requête. * **`customer_id`** — UUID du client Metronome, ou un `ingest_alias` configuré sur le client (afin que vous puissiez utiliser votre propre ID interne). * **`event_type`** — Chaîne reliant cet événement à une métrique facturable. Doit correspondre exactement aux `in_values` du `event_type_filter` de la métrique facturable. * **`timestamp`** — Format ISO 8601. Doit être dans les **34 derniers jours** (fenêtre de rétrodatation de Metronome). Les événements futurs sont rejetés. ### Propriétés (dépendantes de la métrique) * **`properties`** — Paires clé-valeur. **Toutes les valeurs doivent être des chaînes** (même les nombres) — Metronome utilise des décimales de précision arbitraire en interne pour éviter les problèmes de virgule flottante. Metronome prend également en charge jusqu'à **2 000 propriétés** par événement. Les propriétés servent à trois fins : 1. **Agrégation** — La valeur que vous additionnez, comptez ou maximisez (par exemple, `input_tokens`, `duration_seconds`) 2. **Clés de groupe** — Dimensions pour la tarification (par exemple, `model`, `region`) ou l'affichage de facture (par exemple, `user_id`, `project_id`). **Doivent être définies sur la métrique facturable au préalable.** 3. **Métadonnées** — Contexte pour les clients, analyse COGS, ou anticipation (par exemple, `provider`, `cost`, `endpoint`) **Envoyez plus de propriétés que vous ne pensez en avoir besoin.** Vous pouvez toujours ignorer les propriétés inutilisées, mais vous ne pouvez pas ajouter rétroactivement des clés de groupe à une métrique facturable. ### Schémas d'événements courants | Cas d'usage | `event_type` | Propriétés clés | | --------------- | ------------------ | ----------------------------------------------------------------------- | | API IA/LLM | `llm_request` | `model`, `input_tokens`, `output_tokens`, `provider`, `user_id`, `cost` | | API générique | `api_call` | `endpoint`, `method`, `response_code`, `user_id` | | Calcul | `compute_usage` | `instance_type`, `duration_seconds`, `region`, `user_id` | | Stockage | `storage_snapshot` | `storage_gb`, `tier`, `user_id` | | Sièges/Licences | `active_seat` | `user_id`, `role`, `plan` | Pour plus de schémas, consultez [Schémas de conception d'événements](/fr/guides/events/design-usage-events). ## Étape 3 : Créer une métrique facturable Référence API : [Créer une métrique facturable](/fr/api-reference/billable-metrics/create-a-billable-metric) ### Exemple — Compter les appels API (simple) : ```bash theme={null} curl -X POST https://api.metronome.com/v1/billable-metrics/create \ -H "Authorization: Bearer $METRONOME_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "API Calls", "aggregation_type": "count", "event_type_filter": { "in_values": ["api_call"] } }' ``` ### Exemple — Somme des tokens avec clés de groupe : ```bash theme={null} curl -X POST https://api.metronome.com/v1/billable-metrics/create \ -H "Authorization: Bearer $METRONOME_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "Input Tokens", "aggregation_type": "sum", "aggregation_key": "input_tokens", "event_type_filter": { "in_values": ["llm_request"] }, "property_filters": [ { "name": "model", "exists": true }, { "name": "input_tokens", "exists": true }, { "name": "user_id", "exists": true } ], "group_keys": [["model"], ["user_id"]] }' ``` ### Types d'agrégation `count` | `sum` | `unique` | `max` | `latest` * **`count`** — Nombre d'événements correspondants (appels API, requêtes) * **`sum`** — Somme d'une propriété numérique (tokens, octets, secondes) * **`max`** — Valeur maximale dans une fenêtre (stockage de pointe, connexions simultanées) ### Clés de groupe Les clés de groupe déterminent ce que vous tarifez et affichez sur les factures. Elles fonctionnent comme `GROUP BY` en SQL. **Définissez-les ici — elles ne peuvent pas être ajoutées plus tard.** Pour les métriques facturables streaming, les propriétés utilisées comme clés de groupe doivent apparaître dans `property_filters` avec `"exists": true`. | Clé de groupe | Utilisation en aval | Exemple | | --------------- | ----------------------------- | --------------------------------------- | | `model` | Clé de groupe de tarification | Prix différent par modèle IA | | `region` | Clé de groupe de tarification | Prix différent par région | | `instance_type` | Clé de groupe de tarification | Prix différent par GPU | | `user_id` | Clé de groupe de présentation | Ventilations de facture par utilisateur | | `project_id` | Clé de groupe de présentation | Ventilations de facture par projet | ### Métriques facturables SQL Pour des calculs complexes (moyennes quotidiennes, facturation basée sur des percentiles, formules pondérées), utilisez des métriques facturables SQL. Toute colonne renvoyée par votre requête SQL en dehors de `value` peut être utilisée comme clé de groupe. [En savoir plus →](/fr/guides/implement-metronome/core-concepts/billable-metrics-sql-editor) **Les métriques facturables sont immuables après la création** Vous ne pouvez pas ajouter ou modifier les clés de groupe, les filtres de propriétés ou les paramètres d'agrégation. Incluez les clés de groupe pour toute dimension par laquelle vous pourriez tarifer ou afficher à l'avenir. Exemple — utilisateurs uniques par région : ```sql theme={null} SELECT count(DISTINCT properties.user_id) as value, properties.region FROM events WHERE event_type = 'api_request' GROUP BY properties.region ``` Ici, `region` est renvoyé comme colonne et peut être utilisé comme clé de groupe de tarification sur le produit. ## Étape 4 : Créer un produit Référence API : [Créer un produit](/fr/api-reference/products/create-a-product) ### Exemple — Produit d'utilisation avec clés de groupe : ```bash theme={null} curl -X POST https://api.metronome.com/v1/contract-pricing/products/create \ -H "Authorization: Bearer $METRONOME_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "Input Tokens", "type": "usage", "billable_metric_id": "", "pricing_group_key": ["model"], "presentation_group_key": ["user_id"] }' ``` ### Types de produits * **`usage`** — Tarifé de manière variable en fonction de l'utilisation du client (nécessite une métrique facturable) * **`subscription`** — Frais récurrents selon un calendrier (frais de plateforme, licences de sièges) * **`composite`** — Frais en pourcentage sur un produit d'utilisation * **`fixed`** — Frais ponctuels ou planifiés (engagements, crédits, frais ponctuels) ### Attribution des clés de groupe | Je veux... | Champ | Notes | | ------------------------------------------------- | -------------------------------- | --------------------------------------------------------------------- | | Prix différents par valeur de dimension | `pricing_group_key` | Chaque valeur obtient sa propre entrée de taux sur la carte tarifaire | | Ventilations par poste sur la facture (même taux) | `presentation_group_key` | Regroupe les postes par cette dimension | | Un prix fixe | Ne définissez ni l'un ni l'autre | Facturation simple | Les clés de groupe sur le produit doivent être un sous-ensemble des clés de groupe sur la métrique facturable sous-jacente. *(Conversions optionnelles)* Ajoutez une **conversion de quantité** — par exemple, envoyez des tokens individuels mais affichez et tarifez par million de tokens sur la facture. Ajoutez une **conversion d'arrondi** — par exemple, envoyez des secondes mais arrondissez et affichez à la minute la plus proche sur la facture. ## Étape 5 : Créer une carte tarifaire Référence API : [Créer une carte tarifaire](/fr/api-reference/rate-cards/create-a-rate-card) **Bonne pratique :** utilisez une carte tarifaire centralisée partagée entre les clients. Les mises à jour de taux se propagent à tous les contrats référents. ### Créer la carte tarifaire : ```bash theme={null} curl -X POST https://api.metronome.com/v1/contract-pricing/rate-cards/create \ -H "Authorization: Bearer $METRONOME_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{"name": "Standard Pricing"}' ``` ### Ajouter des taux : ```bash theme={null} curl --request POST \ --url https://api.metronome.com/v1/contract-pricing/rate-cards/addRates \ --header 'Authorization: Bearer $METRONOME_API_TOKEN' \ --header 'Content-Type: application/json' \ --data ' { "rate_card_id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc", "rates": [ { "product_id": "13117714-3f05-48e5-a6e9-a66093f13b4d", "starting_at": "2020-01-01T00:00:00.000Z", "entitled": true, "rate_type": "FLAT", "price": 100, "pricing_group_values": { "region": "us-west-2", "cloud": "aws" } }, { "product_id": "13117714-3f05-48e5-a6e9-a66093f13b4d", "starting_at": "2020-01-01T00:00:00.000Z", "entitled": true, "rate_type": "FLAT", "price": 120, "pricing_group_values": { "region": "us-east-2", "cloud": "aws" } } ] } ' ``` ### Ajouter une tarification dimensionnelle (une entrée par valeur) : ```bash theme={null} curl -X POST https://api.metronome.com/v1/contract-pricing/rate-cards/rates/add \ -H "Authorization: Bearer $METRONOME_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "rate_card_id": "", "product_id": "", "starting_at": "2026-03-01T00:00:00Z", "rate_type": "flat", "price": 1.50, "entitled": true, "pricing_group_values": { "model": "gpt-5" } }' ``` Répétez avec différentes `pricing_group_values` pour chaque valeur de dimension (par exemple, `gpt-5-mini` à \$0,30). ### Fonctionnalités supplémentaires * **Tarification par paliers** — Paliers basés sur le volume via le champ `tiers` sur une entrée de taux * **Unités de tarification personnalisées** — Créez sous **Offre → Unités de tarification** dans l'interface utilisateur, puis référencez le `credit_type_id` sur la carte tarifaire pour la facturation basée sur les crédits. [En savoir plus →](/fr/guides/pricing-packaging/make-pricing-changes/use-currency-custompricingunits) * **Taux d'engagement** — Taux qui s'appliquent spécifiquement au tirage sur les engagements prépayés ## Étape 6 : Créer un client et un contrat ### Créer un client : Référence API : [Créer un client](/fr/api-reference/customers/create-a-customer) ```bash theme={null} curl -X POST https://api.metronome.com/v1/customers/create \ -H "Authorization: Bearer $METRONOME_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "Test Customer", "ingest_aliases": ["my-internal-customer-id"] }' ``` Le champ `ingest_aliases` vous permet d'envoyer des événements indexés sur votre propre identifiant interne de client au lieu de l'UUID de Metronome. Vous pouvez mapper des sous-organisations à un seul client en utilisant plusieurs alias. ### Créer un contrat : Référence API : [Créer un contrat](/fr/api-reference/contracts/create-a-contract) ```bash theme={null} curl -X POST https://api.metronome.com/v1/contracts/create \ -H "Authorization: Bearer $METRONOME_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "customer_id": "", "rate_card_id": "", "starting_at": "2026-03-01T00:00:00Z", "usage_statement_schedule": { "frequency": "MONTHLY" } }' ``` Cela crée un contrat **sans fournisseur de facturation** — les factures seront générées dans Metronome et visibles dans le tableau de bord. Pour que les factures soient automatiquement envoyées à Stripe, ajoutez `billing_provider_configuration` : ```json theme={null} "billing_provider_configuration": { "billing_provider": "stripe", "delivery_method": "direct_to_billing_provider" } ``` Pour la configuration complète de Stripe (connexion au niveau du compte, configuration de facturation client, etc.), consultez le [guide d'intégration Stripe](/fr/integrations/invoice-integrations/stripe). ## Étape 7 : Envoyer vos premiers événements Référence API : [Ingérer des événements](/fr/api-reference/usage/ingest-events) Regroupez jusqu'à **100 événements** par requête. Metronome prend en charge environ **6,6 millions d'événements par minute** avec le batching. ```bash theme={null} curl -X POST https://api.metronome.com/v1/ingest \ -H "Authorization: Bearer $METRONOME_API_TOKEN" \ -H "Content-Type: application/json" \ -d '[{ "transaction_id": "test-001", "customer_id": "", "event_type": "llm_request", "timestamp": "2026-03-09T12:00:00Z", "properties": { "model": "gpt-5", "input_tokens": "1500", "user_id": "user_1" } }, { "transaction_id": "test-002", "customer_id": "", "event_type": "llm_request", "timestamp": "2026-03-09T12:01:00Z", "properties": { "model": "gpt-5-mini", "input_tokens": "800", "user_id": "user_2" } }]' ``` ### Comportements importants * Une **réponse `200`** signifie que les événements ont été acceptés pour ingestion. Vérifiez le corps de la réponse pour les erreurs par événement. * Notez que s'il n'y a pas de métrique facturable correspondante pour l'`event_type` ou si les propriétés requises ne sont pas incluses, les événements sont stockés mais peuvent ne pas apparaître dans les calculs d'utilisation. Assurez-vous de créer les métriques facturables avant d'envoyer des événements s'ils sont nécessaires pour la tarification. * Les événements peuvent être **rétrodatés jusqu'à 34 jours**. Les événements avec des horodatages futurs sont rejetés. * **`transaction_id`** est utilisé pour la déduplication. Envoyer le même ID deux fois ne facturera pas deux fois. * **Seuls les événements du point de terminaison ingest sont mesurés.** Les appels API pour gérer les clients, contrats, etc. ne sont pas facturables. ### Vérifier vos événements Accédez à **Connexions → Événements** dans le tableau de bord. Recherchez par `transaction_id`. Cliquez sur un événement individuel pour voir s'il correspond à une métrique facturable et à un client — c'est le diagnostic le plus rapide. Actualisez la page si les événements n'apparaissent pas immédiatement. Le « nombre total d'événements » agrégé peut être en retard. ### Dépannage 1. **Cliquez sur l'événement** sur la page Événements — vérifiez qu'il correspond à une BM et à un client. 2. **Vérifiez la réponse de l'API** de votre appel ingest pour les erreurs par événement. 3. Si les événements correspondent à une BM + client **mais n'apparaissent pas sur la facture :** les valeurs de clés de groupe de tarification dans l'événement ne correspondent probablement à aucun taux sur la carte tarifaire. Par exemple, `"model": "gpt-5"` vs `"model": "gpt5"` (trait d'union manquant) échouera silencieusement à la tarification. 4. **Vérifiez votre jeton d'API** est pour le sandbox (pas la production, ou vice versa). ## Étape 8 : Vérifier votre facture Accédez à **Clients → \[Votre client] → Factures** dans le tableau de bord. La facture brouillon devrait montrer votre utilisation et vos frais. **Cycle de vie de la facture :** 1. **Brouillon** — Accumule l'utilisation tout au long de la période de facturation (visible dans Metronome) 2. **Finalisé** — Verrouillé à la fin de la période de facturation. Il y a une **période de grâce de 24 heures** à la fin de la période de facturation avant que les factures ne soient finalisées pour apporter toute modification nécessaire à une facture. 3. **Envoyé au fournisseur de facturation** — Si Stripe est connecté, poussé dans environ une heure après la finalisation. Statut de paiement géré dans le tableau de bord de Stripe. 4. **Payé / Échoué** — Recouvrement géré par votre fournisseur de facturation Vérifiez que la facture brouillon affiche des quantités et des frais d'utilisation corrects en fonction de votre ingestion d'événements et de la tarification de la carte tarifaire. Si vous voyez de l'utilisation (sous Connexions) mais aucun frais sur la facture, vérifiez que vos événements correspondent aux valeurs de clés de groupe de tarification sur votre carte tarifaire. ## Prêt pour plus ? * [**Tableaux de bord client intégrables**](/fr/guides/customers-billing/optimize-customer-experience/customer-dashboards-and-reporting) — Visibilité en libre-service de l'utilisation pour vos clients * [**Webhooks**](/fr/guides/platform-configuration/setup-webhooks) — Cycle de vie des factures, alertes de solde, événements de paiement * [**Alertes et notifications**](/fr/guides/customers-billing/set-up-notifications/create-and-manage-notifications) — Seuils de dépense, notifications de solde * [**Crédits et engagements**](/fr/guides/pricing-packaging/apply-credits-and-commits/create-a-pre-paid-commit) — Soldes prépayés, engagements entreprise * [**Intégration Stripe**](/fr/integrations/invoice-integrations/stripe) — Recouvrement automatisé des paiements * [**Reconnaissance des revenus**](/fr/guides/reporting-insights/financial-reporting/revenue-recognition) — ASC 606 / IFRS 15 * [**Liste de vérification de production**](/fr/guides/implement-metronome/production-checklist) — Quand vous êtes prêt à passer en production (nouveau jeton d'API, même URL de base, clés Stripe live)