# Mapping d'intégration Chargebee ### Connexion à Chargebee [Suivez ce guide ](https://help.fincome.co/guide/sources/connecter-mon-compte-chargebee)pour établir la connexion avec l'API Chargebee. ### Données synchronisées | **Entité** | **Champs clés synchronisés** | | ---------------------------------- | ------------------------------------------------------------------------------------------- | | Clients | id, nom, email, pays, code\_postal | | Produits (Products) | id, nom | | Prix (Prices) | id, nom, durée, période, type, montant, devise, type\_d’item | | Abonnements (Subscriptions) | id, client\_id, statut, dates\_d’essai, début\_abonnement, annulation, fin\_d’engagement | | Factures (Invoices) | id, statut, client, date | | Lignes de facture (Invoice Lines) | prix\_lié, description, montants\_HT, remises (temp/perm), taxes, quantité, période, devise | | Avoirs (Credit Notes) | id, statut, facture\_d’origine | | Lignes d’avoir (Credit Note Lines) | même structure que la facture (avec inversion des montants) | *** ### Fonctionnement détaillé de l'intégration * Mapping champ à champ : chaque entité Chargebee est traduite finement selon le mapping fourni par l’API * Multi-lignes d’abonnement : Fincome analyse les subscription.subscription\_items unitairement * Annulations interprétées : cancelled\_at, cancel\_schedule\_created\_at sont pris en compte * MRR reconstitué : à partir des prix associés à chaque item\_price actif, ajusté selon la période * Remises différenciées : temporaires et permanentes traitées séparément, par ligne * Conversion devise : basée sur currency\_code + created\_at (ou date) selon le type d'objet *** ### À savoir * Synchronisation initiale : dépend de l’historique, peut prendre quelques heures * Mise à jour automatique : toutes les nuits + mise à jour via webhook * Champs personnalisés : disponibles via metadata dans les objets customer et subscription * Remontée des lignes annulées : via deleted\_at * Avoirs non “voided” uniquement : les avoirs annulés ne sont pas importés * Suppression manuelle dans Chargebee : non propagée *** ### Vue d'ensemble de l'intégration | **Élément** | **Détail** | | -------------------------------- | ------------------------------------------------------ | | Méthode d’intégration | OAuth 2.0 (connexion directe via App Store) | | Entités prises en charge | Clients, Produits, Prix, Abonnements, Factures, Avoirs | | Fréquence de synchronisation | Quotidienne + Webhooks temps réel | | Portée de l’import initial | Toutes les données disponibles via API | | Méthode de synchronisation | API REST Chargebee avec pagination | | Suppression de données Chargebee | Gérée via deleted ou IdPathOrResourceDeleted | *** ### Paramètres de données | **Réglage ou champ** | **Fonctionnement dans Fincome** | | ---------------------------- | ----------------------------------------------------------------- | | subscription\_items | Chaque ligne est suivie individuellement | | Détection des essais | Champs trial\_start et trial\_end | | Dates d’abonnement | started\_at ou start\_date | | Fin d’engagement contractuel | Reconstituée via méthode dédiée (GetContractualCommitmentEndDate) | | Remises ligne à ligne | temporary\_discount\_amount vs discount\_amount | | Conversion de devise | Via currency\_code + created\_at ou invoice.date | | Abonnements supprimés | deleted\_at est valorisé si l’abonnement a disparu | *** ### Mapping technique (Chargebee → Fincome) #### Clients | **Champ Chargebee** | **Champ Fincome** | | --------------------------------- | ------------------- | | customer.id | original\_id | | customer.relationship.root\_id | root\_parent\_id | | customer.email | email | | customer.billing\_address.country | country | | customer.billing\_address.zip | zip\_code | | customer.metadata | custom\_axis\_field | #### Produits & Prix | **Champ Chargebee** | **Champ Fincome** | | -------------------------- | ----------------------------- | | item.id | original\_id (produit) | | item.name | name (produit) | | item\_family\_id | chargebee\_item\_family (axe) | | item\_price.id | original\_id (prix) | | item\_price.name | name (prix) | | item\_price.period\_unit | period\_unit | | item\_price.period | period\_length | | item\_price.amount | amount | | item\_price.currency\_code | currency\_code | | item\_price.item\_type | chargebee\_item\_type (axe) | #### Abonnements | **Champ Chargebee** | **Champ Fincome** | | ---------------------------------------------------------- | ------------------------------------ | | subscription.id | original\_id | | subscription.status | status | | subscription.customer\_id | customer\_id | | subscription.subscription\_items\[].item\_price\_id | price\_id | | subscription.started\_at / start\_date | subscription\_start\_date | | subscription.trial\_start | trial\_start | | subscription.trial\_end | trial\_end | | subscription.cancel\_schedule\_created\_at / cancelled\_at | canceled\_at | | subscription.cancelled\_at | effective\_cancellation\_date | | subscription.created\_at | deal\_closed\_date | | calculé | monthly\_value, monthly\_value\_main | | subscription.metadata | custom\_axis\_field | #### Factures & Lignes | **Champ Chargebee** | **Champ Fincome** | | ---------------------------- | --------------------------------------- | | invoice.id | original\_id | | invoice.date | date | | invoice.status | status | | invoice.customer\_id | customer\_id | | invoice.line\_items\[].id | original\_id (ligne) | | item\_price\_id | price\_id | | subscription\_id | subscription\_id | | quantity | quantity | | amount\_after\_discount | amount\_excluding\_tax\_after\_discount | | tax\_amount | tax\_amount | | line\_item\_discounts (perm) | discount\_amount | | line\_item\_discounts (temp) | temporary\_discount\_amount | | description | description | | date\_from, date\_to | period\_start, period\_end | | invoice.currency\_code | currency\_code | #### Avoirs | **Champ Chargebee** | **Champ Fincome** | | --------------------------------- | --------------------------------------- | | credit\_note.id | original\_id | | credit\_note.line\_items | lignes d’avoir | | credit\_note.status != voided | filtre d’import | | amount | amount\_excluding\_tax\_after\_discount | | discount\_amount | discount\_amount | | temporary\_discount\_amount | temporary\_discount\_amount | | description, date\_from, date\_to | description, period\_start, period\_end | *** ### 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