Hur man kör en SQL-fråga mot Chargebee API

I det här ämnet kommer du att lära dig hur man hämtar kunddata (inklusive anpassade fält) från Chargebee API. Se till att ha en Chargebee API-nyckel tillgänglig samt Invantive Query Tool för att köra Chargebee-frågorna:

Invantive SQL täcker Chargebee API över dussintals API:er. Praktiskt taget alla slutpunkter i API v2 täcks.

Chargebee-data kan både laddas ner och laddas upp. Detta gör det möjligt för SaaS-företag att fylla ett datalager med prenumerations-, fakturerings- och betalningsdata från alla betalningskällor. SQL-drivrutinen har även Power BI-rapporter och instrumentpaneler för Chargebee API.

Data kan inte bara laddas ner, utan även laddas in i Chargebee med hjälp av enkla SQL-satser som direkt översätts till Chargebee API-anrop. Detta gör det möjligt för SaaS-företag att enkelt ladda upp data från sitt backoffice-ERP-system till Chargebee och hålla datan synkroniserad: prenumerationer, konton, betalningar med mera.

Förbered API-nyckel

En API-nyckel krävs för att identifiera din användare i API:et. Ingen Chargebee-data kan hämtas utan autentiseringsuppgifter. Chargebee API-nyckeln är en text på 30-40 tecken bestående av siffror, gemener och versaler.

För att skaffa en API-nyckel, utför följande steg:

  • Gå till User Login - Chargebee.
  • Välj din webbplats på User Login - Chargebee.
  • Notera namnet på webbplatsen; du kommer att behöva det vid inloggning.
  • Gå till “Settings” i vänstermenyn.
  • Klicka på “Configure Chargebee”.
  • Bläddra ner till “API Keys and Webhooks”:
  • Klicka på “API Keys”.
  • Skapa en API-nyckel.
  • För en testwebbplats är det smidigast att använda en Full-Access Key.

Logga in på Chargebee API

Första steget är att logga in på Chargebee med följande steg:

  • Starta Invantive Query Tool.
  • Öppna databasgruppen “Business Apps”.
  • Välj “Chargebee”.
  • Ange din API-nyckel i det första fältet “API Key”.
  • Ange webbplatsnamnet i det andra fältet “Site”.
  • Logga in med “Connect”.

Hämta första Chargebee-datan

Som ett första steg hämtar du lite betalningskälldata, vilket är relativt enkel grunddata (referensdata), med följande steg:

  • Klicka på fliken “Available Objects” längst ner.
  • Öppna schemat “PaymentSources” i trädet.
  • Klicka på tabellen “PaymentSources (Payment Sources)”.
  • På höger sida visas en lista med kolumner.
  • Ovanför kolumnerna finns flikar.
  • Klicka på fliken “Data”.
  • De första 50 betalningskällorna visas i ett rutnät.

API v2-dataformat

SQL-drivrutinen för Chargebee API följer allmänna konventioner. Viss kunskap om data och datatyper är till hjälp även när man använder Invantive SQL.

Identifierare

ID:n inom Chargebee har olika format. Betalningskällans ID kan se ut som “pm_16CHQ2S9FKpykauA” med ett liknande ID-format för Events som “ev_6olyVSIlySWm57D”. Observera att de två första tecknen finns med i tabellnamnet, som “pm” för “Payment” och “ev” för “Event”. ID-kolumnen i andra tabeller, som en prisplan, har dock vanligtvis ett läsbart kodformat som “agency-gbp-year” och kommer att visas i användargränssnittet. Detsamma gäller för kunder.

Belopp

Data från Chargebee API har ett specifikt format för belopp. Alla belopp returneras i centenheter. Invantive SQL-drivrutinen konverterar automatiskt och helt transparent beloppen mellan valuta och centenheter.

Anpassade fält

Chargebee API stöder anpassade fält på:

  • Tillägg (Add-ons)
  • Kunder
  • Planer
  • Prenumerationer

Alla anpassade fält har textformat. Eftersom Chargebee ännu inte tillhandahåller metadata om de anpassade fälten, erbjuder Invantive SQL ytterligare tabeller för att hämta de anpassade fältvärdena:

  • AddonCustomFieldValues
  • CustomerCustomFieldValues
  • PlanCustomFieldValues
  • SubscriptionCustomFieldValues

För varje kombination av post och anpassat fält finns en post i dessa anpassade fälttabeller. Till exempel, när Chargebee-prenumerationstypen har två anpassade fält “erp_id” och “chamber_of_commerce”, kommer tabellen SubscriptionCustomFieldValues att ha upp till två rader för varje kund.

Enkel fråga mot Chargebee API

Data från Chargebee kan enkelt kombineras till nya rapporter. Följande fråga ger dig till exempel en lista över prenumerationsbaserade fakturor, inklusive kundens momsregistreringsnummer:

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-fråga med Chargebee anpassade fält

Viss Chargebee-data innehåller anpassade fältvärden. Eftersom det kan finnas flera anpassade fältvärden för varje huvudentitet kan det vara praktiskt att pivotera de anpassade fältvärdena. Detta gäller särskilt vid synkronisering av data till ett datalager eller en operativ datalagringsplats i en traditionell relationsdatamodell. Följande exempel visar hur man pivoterar Chargebee-kunddata:

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

Registrera ny Chargebee-kund via API och uppdatera

Som nämnts tidigare täcker dock SQL-drivrutinen för Chargebee API inte bara datahämtning, utan möjliggör även DML (data manipulation language) på Chargebee. Följande sats skapar en ny kund i Chargebee:

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

Och följande sats ändrar kundens förnamn:

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

--
-- Ensure data is not retrieved from cache.
--
set use-http-memory-cache false

set use-http-disk-cache false

select *
from   customers
where  id = 13031406

Observera att ID:t anges i insert-satsen och används av Chargebee.