Dans ce sujet, vous apprendrez comment récupérer les données clients (y compris les champs personnalisés) depuis l’API Chargebee. Assurez-vous de disposer d’une clé API Chargebee ainsi que d’Invantive Query Tool pour exécuter les requêtes Chargebee :
Invantive SQL couvre l’API Chargebee à travers des dizaines d’API. Pratiquement tous les points de terminaison de l’API v2 sont couverts.
Les données Chargebee peuvent non seulement être téléchargées, mais aussi importées. Cela permet aux entreprises SaaS d’alimenter un entrepôt de données avec des données d’abonnement, de facturation et de paiement provenant de toutes les sources de paiement. Le pilote SQL propose également des rapports et tableaux de bord Power BI sur l’API Chargebee.
Les données ne peuvent pas seulement être téléchargées, mais aussi chargées dans Chargebee à l’aide de simples instructions SQL qui se traduisent directement en appels à l’API Chargebee. Cela permet aux entreprises SaaS d’importer facilement des données depuis leur système ERP interne vers Chargebee et de garder les données synchronisées : abonnements, comptes, paiements, etc.
Préparer la clé API
Une clé API est nécessaire pour identifier votre utilisateur auprès de l’API. Aucune donnée Chargebee ne peut être récupérée sans identifiants. La clé API Chargebee est un texte de 30 à 40 caractères composé de chiffres, de lettres minuscules et majuscules.
Pour obtenir une clé API, suivez les étapes suivantes :
- Rendez-vous sur User Login - Chargebee.
- Choisissez votre site sur User Login - Chargebee.
- Notez le nom du site ; vous en aurez besoin lors de la connexion.
- Allez dans « Settings » dans le menu de gauche.
- Cliquez sur « Configure Chargebee ».
- Faites défiler jusqu’à « API Keys and Webhooks » :
- Cliquez sur « API Keys ».
- Créez une clé API.
- Pour un site de test, il est plus pratique d’utiliser une « Full-Access Key ».
Se connecter à l’API Chargebee
La première étape consiste à se connecter à Chargebee en suivant les étapes ci-dessous :
- Démarrez Invantive Query Tool.
- Ouvrez le groupe de bases de données « Business Apps ».
- Choisissez « Chargebee ».
- Saisissez votre clé API dans le premier champ « API Key ».
- Saisissez le nom du site dans le deuxième champ « Site ».
- Connectez-vous via « Connect ».
Récupérer les premières données Chargebee
Dans un premier temps, vous allez récupérer des données de sources de paiement, qui constituent des données de référence relativement simples, en suivant les étapes suivantes :
- Cliquez sur l’onglet en bas « Available Objects ».
- Ouvrez le schéma « PaymentSources » dans l’arborescence.
- Cliquez sur la table « PaymentSources (Payment Sources) ».
- Une liste de colonnes apparaît à droite.
- Au-dessus des colonnes se trouvent des onglets.
- Cliquez sur l’onglet « Data ».
- Les 50 premières sources de paiement apparaissent dans une grille.
Formats de données de l’API v2
Le pilote SQL pour l’API Chargebee suit des conventions générales. Une certaine connaissance des données et des types de données est utile, même en utilisant Invantive SQL.
Identifiants
Les identifiants au sein de Chargebee ont divers formats. L’identifiant d’une source de paiement peut ressembler à « pm_16CHQ2S9FKpykauA », avec un format d’identifiant similaire pour les événements comme « ev_6olyVSIlySWm57D ». Notez que les deux premiers caractères correspondent au nom de la table, comme « pm » pour « Payment » et « ev » pour « Event ». En revanche, la colonne ID d’autres tables, comme un plan tarifaire, a généralement un format de code lisible par l’humain, comme « agency-gbp-year », et sera visible dans l’interface utilisateur. Il en va de même pour les clients.
Montants
Les données de l’API Chargebee ont un format spécifique pour les montants. Tous les montants sont renvoyés en unités de centimes. Le pilote Invantive SQL convertit automatiquement et de manière totalement transparente les montants entre les unités monétaires et les centimes.
Champs personnalisés
L’API Chargebee prend en charge les champs personnalisés sur :
- Les modules complémentaires (Add-ons)
- Les clients
- Les plans
- Les abonnements
Tous les champs personnalisés ont un format texte. Étant donné que Chargebee ne fournit pas encore de métadonnées sur les champs personnalisés, Invantive SQL propose des tables supplémentaires pour récupérer les valeurs des champs personnalisés :
- AddonCustomFieldValues
- CustomerCustomFieldValues
- PlanCustomFieldValues
- SubscriptionCustomFieldValues
Pour chaque combinaison d’enregistrement et de champ personnalisé, un enregistrement est présent dans ces tables de champs personnalisés. Par exemple, lorsque le type d’abonnement Chargebee possède deux champs personnalisés « erp_id » et « chamber_of_commerce », la table SubscriptionCustomFieldValues comportera jusqu’à deux lignes pour chaque client.
Requête simple sur l’API Chargebee
Les données de Chargebee peuvent facilement être combinées en nouveaux rapports. Par exemple, la requête suivante vous fournit une liste de factures basées sur des abonnements, incluant le numéro de TVA du client :
select ctr.last_name
, ctr.vat_number
--
, ssn.plan_id
, ssn.mrr
--
, ive.amount_due
, ive.amount_paid
, ive.currency_code
, ive.po_number
from invoices ive
join customers ctr
on ctr.id = ive.customer_id
join subscriptions ssn
on ssn.id = ive.subscription_id
Requête SQL utilisant les champs personnalisés Chargebee
Certaines données Chargebee contiennent des valeurs de champs personnalisés. Étant donné qu’il peut y avoir plusieurs valeurs de champs personnalisés pour chaque entité principale, il peut être utile de pivoter ces valeurs. Cela est particulièrement vrai lors de la synchronisation des données vers un entrepôt de données ou un magasin de données opérationnel dans un modèle relationnel traditionnel. L’exemple suivant montre comment pivoter les données clients Chargebee :
select pvt.customer_id
, pvt.erp_id
, pvt.chamber_of_commerce
from customers cmr
join customercustomfieldvalues
pivot ( min(value)
for key
in
( [erp_id]
, [chamber_of_commerce]
)
) pvt
on 1=1
and cmr.id = customer_id
Enregistrer un nouveau client Chargebee via l’API et le mettre à jour
Cependant, comme indiqué précédemment, le pilote SQL pour l’API Chargebee ne se limite pas à la récupération des données, mais permet également le DML (langage de manipulation de données) sur Chargebee. L’instruction suivante crée un nouveau client dans Chargebee :
insert into customers
( id
, last_name
)
values
( 13031406
, 'Invantive BV'
)
Et l’instruction suivante modifie le prénom du client :
update customers
set first_name = 'John'
where id = 13031406
--
-- S'assurer que les données ne sont pas récupérées depuis le cache.
--
set use-http-memory-cache false
set use-http-disk-cache false
select *
from customers
where id = 13031406
Notez que l’ID est fourni dans l’instruction d’insertion et utilisé par Chargebee.

