> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://help.fincome.co/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# Mapping d'intégration Stripe

![](https://storage.crisp.chat/users/helpdesk/website/-/6/2/0/e/620ea71851239000/stripe_1squotp.png =100x100)
# Connexion à Stripe

[Suivez ce guide](https://help.fincome.co/fr/article/connecter-mon-compte-stripe-a2nyul/) 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