# Mapping d'intégration Stripe ### Connexion à Stripe [Suivez ce guide](https://help.fincome.co/guide/sources/connecter-mon-compte-stripe) 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