# Mapping d'intégration Stripe ### Connexion à Stripe [Suivez ce guide](/guide/sources/connecter-mon-compte-stripe.md) pour établir la connexion avec l'API Stripe. ### Données synchronisées | **Entité Stripe** | **Champs clés synchronisés** | | -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | Clients (Customers) | id, name, email, address.country, address.postal\_code | | Produits (Products) | id, name | | Tarifs (Prices) | id, nom du plan, recurring.interval, recurring.interval\_count, amount, currency | | Abonnements (Subscriptions) | id, customer\_id, status, trial\_start, trial\_end, canceled\_at, start\_date, monthly\_value | | Factures (Invoices) | id, customer\_id, date, status, number | | Lignes de facture (Invoice Line Items) | id, invoice\_id, subscription\_id, price\_id, amount\_excluding\_tax\_after\_discount, tax\_amount, discount\_amount, quantity, period\_start, period\_end | | Notes de crédit (Credit Notes) | id, invoice\_id, date, status et lignes associées (amount, discount\_amount, …) | | Événements (Events) | Gestion des mises à jour des objets et sync incrémentale via webhooks | *** ### Fonctionnement détaillé de l'intégration L’intégration Stripe avec Fincome est conçue pour garantir une lecture fidèle et granulaire de vos données de facturation. Voici les principaux mécanismes en œuvre : * **Mapping structuré des objets**\ Chaque entité Stripe (client, produit, abonnement, facture...) est traduite dans Fincome grâce à un mapping champ à champ, selon les règles définies dans notre moteur d'intégration. * **Détection des périodes d’essai**\ Les périodes d’essai sont automatiquement extraites à partir de `trial_start` et `trial_end`. * **Suivi détaillé des abonnements**\ Chaque ligne d’abonnement (`items.data`) est suivie séparément pour refléter les montées ou baisses en gamme, les réactivations, les suspensions, etc. * **Annulations & suspensions**\ Les statuts `canceled`, `unpaid`, `incomplete_expired` sont correctement interprétés. Les champs `cancel_at`, `canceled_at` et `pause_collection` permettent une restitution fidèle des fins d’engagement. * **Calcul du MRR**\ Le MRR est déterminé pour chaque ligne d’abonnement à partir du prix (avec sa périodicité) et converti en devise de base selon le taux de change applicable à la date de création. * **Analyse complète des remises**\ Fincome distingue et valorise : * les remises **temporaires** (ex : coupons avec durée limitée) * les remises **permanentes** (ex : prix réduits, coupons sans expiration) * **Conversion des devises**\ Les montants sont convertis à la volée en devise de référence (EUR, USD...) grâce au champ `currency` et à la date d’émission de chaque document (facture, avoir...). * **Synchronisation incrémentale et prioritaire**\ Les mises à jour Stripe sont automatiquement détectées via Webhooks (ex : `invoice.updated`, `customer.subscription.updated`).\ Toute modification manuelle faite dans Fincome reste prioritaire sur les données synchronisées. *** ### À savoir * **Durée de la première synchronisation**\ Elle peut prendre plusieurs heures selon le volume d’abonnés, de factures ou d’historique à importer. * **Synchronisation quotidienne**\ Fincome synchronise Stripe automatiquement **chaque nuit**, incluant les nouvelles données et mises à jour. * **Écrasement manuel**\ Toute modification faite manuellement dans Fincome (ex : réaffectation d’un abonnement) **n’est jamais écrasée** par la synchronisation Stripe. * **Ratelimit Stripe**\ Les limitations d’API imposées par Stripe sont automatiquement gérées. Fincome met en pause et reprend la synchronisation sans action manuelle. * **Expiration des tokens OAuth**\ La connexion OAuth est automatiquement rafraîchie si besoin. Aucune intervention n’est requise de votre part. *** ### Vue d'ensemble de l'intégration | **Élément** | **Détail** | | ----------------------------- | ------------------------------------------------------ | | Méthode d’intégration | OAuth 2.0 (connexion directe depuis Fincome) | | Entités prises en charge | Clients, Produits, Prix, Abonnements, Factures, Avoirs | | Fréquence de synchronisation | Quotidienne + Webhooks | | Import initial | Historique complet Stripe | | Méthode de synchronisation | API REST avec pagination starting\_after | | Suppression de données Stripe | Non supportée (non propagée dans Fincome) | *** ### Paramètres de données | **Réglage** | **Fonctionnement** | | -------------------- | ------------------------------------------- | | Détection des essais | trial\_start et trial\_end | | Calcul MRR | Périodicité + montant + devise à la date | | Fin d’engagement | cancel\_at ou canceled\_at | | Annulation | Statut + pause\_collection, cancel\_at | | Abonnements | Suivi par ligne (items.data) | | Remises | Coupons : temporaire ou permanente | | Conversion devises | currency + date facture | | Resynchronisation | Automatique (priorité aux modifs manuelles) | *** ### Mapping technique (Stripe → Fincome) #### Clients | **Stripe** | **Fincome** | | ---------------------------------------------------- | ------------ | | id | original\_id | | name | name | | email | email | | address.country / shipping.address.country | country | | address.postal\_code / shipping.address.postal\_code | zip\_code | #### Produits & Prix | **Stripe** | **Fincome** | | ------------------------- | ---------------------- | | product.id | original\_id (produit) | | product.name | name (produit) | | price.id | original\_id (prix) | | nickname / plan | name (prix) | | recurring.interval | period\_unit | | recurring.interval\_count | period\_length | | unit\_amount | amount | | currency | currency\_code | | product | product\_id | #### Abonnements | **Stripe** | **Fincome** | | ------------------------- | ----------------------------- | | id | original\_id | | customer | customer\_id | | status, pause\_collection | status | | trial\_start | trial\_start | | trial\_end | trial\_end | | created | deal\_closed\_date | | start\_date | subscription\_start\_date | | cancel\_at | effective\_cancellation\_date | | canceled\_at | canceled\_at | | price.id / plan.id | price\_id | #### Factures & Lignes | **Stripe** | **Fincome** | | --------------------------------- | --------------------------- | | id | original\_id (facture) | | customer | customer\_id | | status | status | | number | invoice\_number | | status\_transitions.finalized\_at | date | | lines\[].id | original\_id (ligne) | | subscription | subscription\_id | | quantity | quantity | | tax\_amount | tax\_amount | | discount\_amount | discount\_amount | | period.start / period.end | period\_start / period\_end | | currency | currency\_code | #### Avoirs | **Stripe** | **Fincome** | | --------------------------- | --------------------------- | | id | original\_id | | invoice | invoice\_id | | status | status | | created | date | | lines\[].id | original\_id (ligne avoir) | | invoice\_line\_item | invoice\_line\_item\_id | | amount | amount(\_main) | | discount\_amount | discount\_amount | | temporary\_discount\_amount | temporary\_discount\_amount | | currency | currency\_code | | description | description | *** ### Prochaines étapes * Consultez vos KPIs dans les vues MRR, Churn, et Cohortes * Ajoutez d’autres sources de facturation (Stripe, Chargebee, etc.) * Enrichissez vos données clients (segmentation, taille d’entreprise...) * Planifiez une session avec votre Customer Success pour aller plus loin --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://help.fincome.co/ressources/mapping-dintegration-et-api/mapping-dintegration-stripe.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.