In diesem Thema lernst du, wie man Kundendaten (einschließlich benutzerdefinierter Felder) aus der Chargebee-API abruft. Stelle sicher, dass du einen Chargebee-API-Schlüssel sowie das Invantive Query Tool zur Verfügung hast, um die Chargebee-Abfragen auszuführen:
Invantive SQL deckt die Chargebee-API über Dutzende von APIs ab. Praktisch alle Endpunkte der API v2 werden abgedeckt.
Chargebee-Daten können nicht nur heruntergeladen, sondern auch hochgeladen werden. Dies ermöglicht es SaaS-Unternehmen, ein Data Warehouse mit Abonnement-, Abrechnungs- und Zahlungsdaten aus allen Zahlungsquellen zu füllen. Der SQL-Treiber bietet außerdem Power-BI-Berichte und -Dashboards für die Chargebee-API.
Daten können nicht nur heruntergeladen, sondern auch mit einfachen SQL-Anweisungen, die direkt in Chargebee-API-Aufrufe übersetzt werden, in Chargebee geladen werden. Dies ermöglicht es SaaS-Unternehmen, Daten aus ihrem Backoffice-ERP-System einfach in Chargebee hochzuladen und die Daten synchron zu halten: Abonnements, Konten, Zahlungen usw.
API-Schlüssel vorbereiten
Ein API-Schlüssel ist erforderlich, um deinen Benutzer bei der API zu identifizieren. Ohne Zugangsdaten können keine Chargebee-Daten abgerufen werden. Der Chargebee-API-Schlüssel ist ein Text aus 30-40 Zeichen mit Ziffern, Klein- und Großbuchstaben.
Um einen API-Schlüssel zu erhalten, führe die folgenden Schritte aus:
- Gehe zu User Login - Chargebee.
- Wähle deine Site auf User Login - Chargebee.
- Notiere dir den Namen der Site; du wirst ihn beim Anmelden benötigen.
- Gehe im linken Menü zu „Settings“.
- Klicke auf „Configure Chargebee“.
- Scrolle nach unten zu „API Keys and Webhooks“:
- Klicke auf „API Keys“.
- Erstelle einen API-Schlüssel.
- Für eine Test-Site ist es am praktischsten, einen Full-Access Key zu verwenden.
Bei der Chargebee-API anmelden
Der erste Schritt besteht darin, sich bei Chargebee anzumelden. Gehe dazu wie folgt vor:
- Starte das Invantive Query Tool.
- Öffne die Datenbankgruppe „Business Apps“.
- Wähle „Chargebee“.
- Gib deinen API-Schlüssel in das erste Feld „API Key“ ein.
- Gib den Site-Namen in das zweite Feld „Site“ ein.
- Melde dich mit „Connect“ an.
Erste Chargebee-Daten abrufen
Als ersten Schritt rufst du mit den folgenden Schritten einige Zahlungsquellendaten ab, bei denen es sich um relativ einfache Stamm- (Referenz-)Daten handelt:
- Klicke auf den unteren Tab „Available Objects“.
- Öffne das Schema „PaymentSources“ im Baum.
- Klicke auf die Tabelle „PaymentSources (Payment Sources)“.
- Auf der rechten Seite erscheint eine Liste von Spalten.
- Über den Spalten befinden sich Tabs.
- Klicke auf den Tab „Data“.
- Die ersten 50 Zahlungsquellen erscheinen in einem Raster.
API-v2-Datenformate
Der SQL-Treiber für die Chargebee-API folgt allgemeinen Konventionen. Einige Kenntnisse über die Daten und Datentypen sind auch bei der Verwendung von Invantive SQL hilfreich.
Identifikatoren
IDs innerhalb von Chargebee haben verschiedene Formate. Die Zahlungsquellen-ID kann etwa „pm_16CHQ2S9FKpykauA“ lauten, mit einem ähnlichen Format bei Events wie „ev_6olyVSIlySWm57D“. Beachte, dass die ersten beiden Zeichen im Tabellennamen enthalten sind, wie „pm“ für „Payment“ und „ev“ für „Event“. Die ID-Spalte anderer Tabellen, wie zum Beispiel eines Preisplans, hat jedoch typischerweise ein menschenlesbares Code-Format wie „agency-gbp-year“ und wird in der Benutzeroberfläche sichtbar sein. Dasselbe gilt für Kunden.
Beträge
Daten aus der Chargebee-API haben ein spezifisches Format für Beträge. Alle Beträge werden in Cent-Einheiten zurückgegeben. Der Invantive-SQL-Treiber konvertiert die Beträge automatisch und vollständig transparent zwischen Währungs- und Cent-Einheiten.
Benutzerdefinierte Felder
Die Chargebee-API unterstützt benutzerdefinierte Felder bei:
- Add-ons
- Kunden
- Plänen
- Abonnements
Alle benutzerdefinierten Felder haben ein Textformat. Da Chargebee noch keine Metadaten zu den benutzerdefinierten Feldern bereitstellt, bietet Invantive SQL zusätzliche Tabellen, um die Werte der benutzerdefinierten Felder abzurufen:
- AddonCustomFieldValues
- CustomerCustomFieldValues
- PlanCustomFieldValues
- SubscriptionCustomFieldValues
Für jede Kombination aus Datensatz und benutzerdefiniertem Feld gibt es einen Datensatz in diesen Tabellen für benutzerdefinierte Felder. Wenn zum Beispiel der Chargebee-Abonnementtyp zwei benutzerdefinierte Felder „erp_id“ und „chamber_of_commerce“ hat, wird die Tabelle SubscriptionCustomFieldValues für jeden Kunden bis zu zwei Zeilen enthalten.
Einfache Abfrage der Chargebee-API
Die Daten von Chargebee lassen sich leicht zu neuen Berichten kombinieren. Die folgende Abfrage liefert dir zum Beispiel eine Liste von abonnementbasierten Rechnungen, einschließlich der Umsatzsteuer-Identifikationsnummer des Kunden:
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
SQL-Abfrage mit benutzerdefinierten Chargebee-Feldern
Einige Chargebee-Daten enthalten Werte für benutzerdefinierte Felder. Da es für jede Haupteinheit mehrere Werte für benutzerdefinierte Felder geben kann, kann es praktisch sein, die Werte der benutzerdefinierten Felder zu pivotieren. Dies gilt insbesondere bei der Synchronisierung der Daten mit einem Data Warehouse oder einem operativen Datenspeicher in einem traditionellen relationalen Datenmodell. Das folgende Beispiel zeigt, wie man die Chargebee-Kundendaten pivotiert:
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
Neuen Chargebee-Kunden über die API registrieren und aktualisieren
Wie bereits erwähnt, deckt der SQL-Treiber für die Chargebee-API jedoch nicht nur den Datenabruf ab, sondern ermöglicht auch DML (Data Manipulation Language) bei Chargebee. Die folgende Anweisung erstellt einen neuen Kunden in Chargebee:
insert into customers
( id
, last_name
)
values
( 13031406
, 'Invantive BV'
)
Und die folgende Anweisung ändert den Vornamen des Kunden:
update customers
set first_name = 'John'
where id = 13031406
--
-- Sicherstellen, dass Daten nicht aus dem Cache abgerufen werden.
--
set use-http-memory-cache false
set use-http-disk-cache false
select *
from customers
where id = 13031406
Beachte, dass die ID in der insert-Anweisung angegeben und von Chargebee verwendet wird.

