In questo argomento imparerai come recuperare i dati dei clienti (inclusi i campi personalizzati) dall’API Chargebee. Assicurati di avere una chiave API Chargebee disponibile, oltre a Invantive Query Tool per eseguire le query Chargebee:
Invantive SQL copre l’API Chargebee attraverso decine di API. Praticamente tutti gli endpoint dell’API v2 sono coperti.
I dati di Chargebee possono essere scaricati ma anche caricati. Questo permette alle aziende SaaS di popolare un data warehouse con dati su abbonamenti, fatturazione e pagamenti provenienti da tutte le fonti di pagamento. Il driver SQL offre inoltre report e dashboard di Power BI sull’API Chargebee.
I dati non possono solo essere scaricati, ma anche caricati in Chargebee utilizzando semplici istruzioni SQL che si traducono direttamente in chiamate all’API Chargebee. Questo permette alle aziende SaaS di caricare facilmente i dati dal proprio sistema ERP di back office in Chargebee e mantenerli sincronizzati: abbonamenti, account, pagamenti, ecc.
Preparazione della chiave API
È necessaria una chiave API per identificare il tuo utente sull’API. Nessun dato Chargebee può essere recuperato senza credenziali. La chiave API di Chargebee è un testo di 30-40 caratteri composto da cifre e caratteri minuscoli e maiuscoli.
Per ottenere una chiave API, esegui i seguenti passaggi:
- Vai su User Login - Chargebee.
- Scegli il tuo sito su User Login - Chargebee.
- Prendi nota del nome del sito; ti servirà al momento dell’accesso.
- Vai su “Settings” nel menu a sinistra.
- Clicca su “Configure Chargebee”.
- Scorri fino a “API Keys and Webhooks”:
- Clicca su “API Keys”.
- Crea una chiave API.
- Per un sito di test, è più comodo utilizzare una Full-Access Key.
Accesso all’API Chargebee
Il primo passo è accedere a Chargebee seguendo questi passaggi:
- Avvia Invantive Query Tool.
- Apri il gruppo di database “Business Apps”.
- Scegli “Chargebee”.
- Inserisci la tua chiave API nel primo campo “API Key”.
- Inserisci il nome del sito nel secondo campo “Site”.
- Accedi con “Connect”.
Recupero dei primi dati da Chargebee
Come primo passo, recupererai alcuni dati sulle fonti di pagamento, che rappresentano dati di riferimento (seed) relativamente semplici, seguendo questi passaggi:
- Clicca sulla scheda in basso “Available Objects”.
- Apri lo schema “PaymentSources” nell’albero.
- Clicca sulla tabella “PaymentSources (Payment Sources)”.
- Sulla destra appare un elenco di colonne.
- Sopra le colonne ci sono delle schede.
- Clicca sulla scheda “Data”.
- Le prime 50 fonti di pagamento appaiono in una griglia.
Formati dei dati dell’API v2
Il driver SQL per l’API Chargebee segue convenzioni generali. Una certa conoscenza dei dati e dei tipi di dati è utile anche quando si utilizza Invantive SQL.
Identificatori
Gli ID all’interno di Chargebee hanno vari formati. L’ID della fonte di pagamento può essere qualcosa come “pm_16CHQ2S9FKpykauA”, con un formato simile per l’ID degli Events, come “ev_6olyVSIlySWm57D”. Nota che i primi due caratteri sono contenuti nel nome della tabella, come “pm” per “Payment” ed “ev” per “Event”. Tuttavia, la colonna ID di altre tabelle, come un piano tariffario, ha tipicamente un formato di codice leggibile dall’uomo, come “agency-gbp-year”, e sarà visibile nell’interfaccia utente. Lo stesso vale per i clienti.
Importi
I dati provenienti dall’API Chargebee hanno un formato specifico per gli importi. Tutti gli importi vengono restituiti in unità di centesimi. Il driver Invantive SQL converte automaticamente e in modo completamente trasparente gli importi tra unità di valuta e centesimi.
Campi personalizzati
L’API Chargebee supporta campi personalizzati su:
- Add-on
- Clienti
- Piani
- Abbonamenti
Tutti i campi personalizzati hanno un formato testuale. Poiché Chargebee non fornisce ancora metadati sui campi personalizzati, Invantive SQL fornisce tabelle aggiuntive per recuperare i valori dei campi personalizzati:
- AddonCustomFieldValues
- CustomerCustomFieldValues
- PlanCustomFieldValues
- SubscriptionCustomFieldValues
Per ogni combinazione di record e campo personalizzato, è presente un record in queste tabelle dei campi personalizzati. Ad esempio, quando il tipo di abbonamento Chargebee ha due campi personalizzati “erp_id” e “chamber_of_commerce”, la tabella SubscriptionCustomFieldValues avrà fino a due righe per ogni cliente.
Query semplice sull’API Chargebee
I dati di Chargebee possono essere facilmente combinati in nuovi report. Ad esempio, la seguente query fornisce un elenco di fatture basate su abbonamento, incluso il numero di partita IVA del cliente:
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
Query SQL utilizzando i campi personalizzati di Chargebee
Alcuni dati Chargebee contengono valori di campi personalizzati. Poiché possono esserci più valori di campi personalizzati per ogni entità principale, può essere utile effettuare un pivot dei valori dei campi personalizzati. Questo vale soprattutto quando si sincronizzano i dati con un data warehouse o un archivio dati operativo in un modello di dati relazionale tradizionale. Il seguente esempio mostra come effettuare il pivot dei dati dei clienti 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
Registrazione di un nuovo cliente Chargebee tramite API e aggiornamento
Tuttavia, come detto in precedenza, il driver SQL per l’API Chargebee non copre solo il recupero dei dati, ma consente anche il DML (data manipulation language) su Chargebee. La seguente istruzione crea un nuovo cliente in Chargebee:
insert into customers
( id
, last_name
)
values
( 13031406
, 'Invantive BV'
)
E la seguente istruzione modifica il nome del cliente:
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
Nota che l’ID viene fornito nell’istruzione insert e utilizzato da Chargebee.

