Guide d'intégration Chargebee
Bienvenue dans le guide d’intégration de Chargebee avec Fincome. Ce document vous guide étape par étape pour connecter vos données de facturation Chargebee à Fincome.
Prérequis
Avant de commencer, assurez-vous que :
Vous êtes administrateur du compte Chargebee
Vous avez une connexion OAuth activée (via l’App Store Chargebee ou les paramètres API)
Votre compte Fincome est actif
Vous avez activé l’accès aux entités : Clients, Produits, Prix, Abonnements, Factures et Avoirs
Présentation de l'intégration
L’intégration Chargebee permet une synchronisation automatique des entités suivantes dans Fincome :
Clients
Produits & Prix
Abonnements & lignes d’abonnement
Factures & lignes de facture
Avoirs (crédit notes)
Ces données sont normalisées dans Fincome pour produire :
MRR (mensuel, net, expansion, contraction, churn)
Cohortes d’abonnement
Reconnaissance de revenus
Analyse des remises (temporaires vs permanentes)
Pilotage multi-devises
Analyse de la durée de vie client et des annulations
Étapes d'intégration
1. Connexion à Chargebee depuis Fincome
Connectez-vous à votre compte Fincome.
Accédez à l'onglet Données.
Cliquez sur Connecter un nouveau système de facturation :
Sélectionnez Chargebee.
Dans une autre page, connectez vous à votre compte Chargebee.
Allez dans Réglages > Configurer Chargebee > Clé API > Ajouter une clé en lecture seule et selectionnant "Toutes".
Copiez cette clé et collez-la sur votre page Fincome.
Sur votre page Chargebee copiez ce qui se trouve entre "https://" et ".chargebee.com" et collez-le sur la page Fincome.
Validez.
Une fois la connexion établie, la synchronisation initiale démarre automatiquement.
2. Données synchronisées
Clients
ID, nom, email, pays, code postal, parent (hiérarchie client)
Produits & Prix
Produit : ID, nom, famille
Prix : ID, nom, durée, période, type, montant, devise, type d’item
Abonnements
ID, client lié, statut, dates d’essai, début d’abonnement, annulation, fin d’engagement
Lignes d’abonnement (item_price) analysées une à une
Montants mensuels calculés, en devise d’origine et devise de base
Factures & Lignes
Facture : ID, statut, client, date
Ligne : prix lié, description, montants HT, remises (temp/perm), taxes, quantité, période, devise
Avoirs (Crédit Notes)
Avoir : ID, statut, facture d’origine
Lignes : 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
Engagements contractuels : reconstitués via GetContractualCommitmentEndDate()
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
Suppression ou ressource inactive : gérée avec IdPathOrResourceDeleted(...)
À 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
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
Besoin d’aide ?
Notre équipe support est disponible via le chat de l’application ou par email : [email protected]
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
Mis à jour