Sådan kører du en SQL-forespørgsel på Chargebee API

I dette emne lærer du, hvordan du henter kundedata (inklusive brugerdefinerede felter) fra Chargebee API’et. Sørg for at have en Chargebee API-nøgle til rådighed samt Invantive Query Tool til at udføre Chargebee-forespørgslerne:

Invantive SQL dækker Chargebee API’et på tværs af dusinvis af API’er. Praktisk talt alle endpoints i API v2 er dækket.

Chargebee-data kan hentes, men også uploades. Dette gør det muligt for SaaS-virksomheder at fylde et datawarehouse med abonnements-, fakturerings- og betalingsdata fra alle betalingskilder. SQL-driveren indeholder også Power BI-rapporter og -dashboards til Chargebee API’et.

Data kan ikke kun hentes, men også indlæses i Chargebee ved hjælp af simple SQL-sætninger, der direkte oversættes til Chargebee API-kald. Dette gør det muligt for SaaS-virksomheder nemt at uploade data fra deres backoffice ERP-system til Chargebee og holde dataene synkroniseret: abonnementer, konti, betalinger osv.

Forbered API-nøgle

En API-nøgle er påkrævet for at identificere din bruger på API’et. Ingen Chargebee-data kan hentes uden legitimationsoplysninger. Chargebee API-nøglen er en tekst på 30-40 tegn bestående af tal, små og store bogstaver.

For at få en API-nøgle, udfør følgende trin:

  • Gå til User Login - Chargebee.
  • Vælg dit site på User Login - Chargebee.
  • Noter navnet på sitet; du får brug for det ved login.
  • Gå til “Settings” i venstremenuen.
  • Klik på “Configure Chargebee”.
  • Rul ned til “API Keys and Webhooks”:
  • Klik på “API Keys”.
  • Opret en API-nøgle.
  • For et testsite er det mest praktisk at bruge en Full-Access Key.

Log på Chargebee API

Første trin er at logge på Chargebee ved hjælp af følgende trin:

  • Start Invantive Query Tool.
  • Åbn databasegruppen “Business Apps”.
  • Vælg “Chargebee”.
  • Indtast din API-nøgle i det første felt “API Key”.
  • Indtast sitenavnet i det andet felt “Site”.
  • Log på med “Connect”.

Hent de første Chargebee-data

Som et første skridt vil du hente nogle betalingskildedata, som er relativt simple grund- (reference) data ved hjælp af følgende trin:

  • Klik på fanen “Available Objects” nederst.
  • Åbn skemaet “PaymentSources” i træstrukturen.
  • Klik på tabellen “PaymentSources (Payment Sources)”.
  • I højre side vises en liste med kolonner.
  • Over kolonnerne er der faner.
  • Klik på fanen “Data”.
  • De første 50 betalingskilder vises i et gitter.

API v2-dataformater

SQL-driveren til Chargebee API’et følger generelle konventioner. Noget kendskab til dataene og datatyperne er nyttigt, selv når man bruger Invantive SQL.

Identifikatorer

ID’er i Chargebee har forskellige formater. Betalingskilde-ID’et kan være noget i stil med “pm_16CHQ2S9FKpykauA” med et lignende format for ID på Events såsom “ev_6olyVSIlySWm57D”. Bemærk, at de første to tegn er indeholdt i tabelnavnet, som “pm” for “Payment” og “ev” for “Event”. Dog har ID-kolonnen i andre tabeller, som en prisplan, typisk et menneskeligt læsbart kodeformat som “agency-gbp-year” og vil være synligt i brugergrænsefladen. Det samme gælder for kunder.

Beløb

Data fra Chargebee API’et har et specifikt format for beløb. Alle beløb returneres i centenheder. Invantive SQL-driveren konverterer automatisk og fuldt gennemsigtigt beløbene mellem valuta- og centenheder.

Brugerdefinerede felter

Chargebee API’et understøtter brugerdefinerede felter på:

  • Add-ons
  • Kunder
  • Planer
  • Abonnementer

Alle brugerdefinerede felter har et tekstformat. Da Chargebee endnu ikke leverer metadata om de brugerdefinerede felter, giver Invantive SQL ekstra tabeller til at hente de brugerdefinerede feltværdier:

  • AddonCustomFieldValues
  • CustomerCustomFieldValues
  • PlanCustomFieldValues
  • SubscriptionCustomFieldValues

For hver kombination af post og brugerdefineret felt er der én post i disse tabeller for brugerdefinerede felter. For eksempel, når Chargebee-abonnementstypen har to brugerdefinerede felter “erp_id” og “chamber_of_commerce”, vil tabellen SubscriptionCustomFieldValues have op til to rækker for hver kunde.

Simpel forespørgsel på Chargebee API

Data fra Chargebee kan nemt kombineres i nye rapporter. For eksempel giver følgende forespørgsel dig en liste over abonnementsbaserede fakturaer, inklusive kundens momsnummer:

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-forespørgsel med brug af Chargebee brugerdefinerede felter

Nogle Chargebee-data indeholder brugerdefinerede feltværdier. Da der kan være flere brugerdefinerede feltværdier for hver hovedentitet, kan det være praktisk at pivotere de brugerdefinerede feltværdier. Dette gælder især ved synkronisering af dataene til et datawarehouse eller en operationel datalagring i en traditionel relationel datamodel. Følgende eksempel viser, hvordan man pivoterer Chargebee-kundedataene:

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

Registrer ny Chargebee-kunde via API og opdater

Som nævnt tidligere dækker SQL-driveren til Chargebee API’et dog ikke kun datahentning, men muliggør også DML (data manipulation language) på Chargebee. Følgende sætning opretter en ny kunde i Chargebee:

insert into customers
( id
, last_name
)
values
( 13031406
, 'Invantive BV'
)

Og følgende sætning ændrer kundens fornavn:

update customers
set    first_name = 'John'
where  id = 13031406

--
-- Sørg for at data ikke hentes fra cache.
--
set use-http-memory-cache false

set use-http-disk-cache false

select *
from   customers
where  id = 13031406

Bemærk, at ID’et angives i insert-sætningen og bruges af Chargebee.