En este tema aprenderás a recuperar datos de clientes (incluidos los campos personalizados) desde la API de Chargebee. Asegúrate de tener disponible una clave de API de Chargebee, así como Invantive Query Tool para ejecutar las consultas de Chargebee:
Invantive SQL cubre la API de Chargebee a través de docenas de API. Prácticamente todos los endpoints de la API v2 están cubiertos.
Los datos de Chargebee se pueden descargar, pero también cargar. Esto permite a las empresas SaaS llenar un almacén de datos (data warehouse) con datos de suscripciones, facturación y pagos de todas las fuentes de pago. El controlador SQL también incluye informes y paneles de Power BI sobre la API de Chargebee.
Los datos no solo se pueden descargar, sino también cargar en Chargebee mediante sentencias SQL simples que se traducen directamente en llamadas a la API de Chargebee. Esto permite a las empresas SaaS cargar fácilmente datos desde su sistema ERP de back office a Chargebee y mantener los datos sincronizados: suscripciones, cuentas, pagos, etc.
Preparar la clave de API
Se requiere una clave de API para identificar a tu usuario en la API. No se pueden recuperar datos de Chargebee sin credenciales. La clave de API de Chargebee es un texto de 30-40 caracteres compuesto por dígitos y letras minúsculas y mayúsculas.
Para obtener una clave de API, sigue estos pasos:
- Ve a User Login - Chargebee.
- Elige tu sitio en User Login - Chargebee.
- Toma nota del nombre del sitio; lo necesitarás al iniciar sesión.
- Ve a “Settings” (Configuración) en el menú de la izquierda.
- Haz clic en “Configure Chargebee” (Configurar Chargebee).
- Desplázate hacia abajo hasta “API Keys and Webhooks” (Claves de API y Webhooks):
- Haz clic en “API Keys” (Claves de API).
- Crea una clave de API.
- Para un sitio de prueba, lo más conveniente es usar una Full-Access Key (clave de acceso completo).
Iniciar sesión en la API de Chargebee
El primer paso es iniciar sesión en Chargebee siguiendo estos pasos:
- Inicia Invantive Query Tool.
- Abre el grupo de bases de datos “Business Apps”.
- Elige “Chargebee”.
- Introduce tu clave de API en el primer campo “API Key”.
- Introduce el nombre del sitio en el segundo campo “Site”.
- Haz clic en “Connect” (Conectar) para iniciar sesión.
Recuperar los primeros datos de Chargebee
Como primer paso, recuperarás algunos datos de fuentes de pago, que son datos semilla (de referencia) relativamente simples, siguiendo estos pasos:
- Haz clic en la pestaña inferior “Available Objects” (Objetos disponibles).
- Abre el esquema “PaymentSources” en el árbol.
- Haz clic en la tabla “PaymentSources (Payment Sources)”.
- En el lado derecho aparecerá una lista de columnas.
- Encima de las columnas hay pestañas.
- Haz clic en la pestaña “Data” (Datos).
- Las primeras 50 fuentes de pago aparecerán en una cuadrícula.
Formatos de datos de la API v2
El controlador SQL para la API de Chargebee sigue convenciones generales. Tener cierto conocimiento sobre los datos y los tipos de datos es útil incluso al usar Invantive SQL.
Identificadores
Los ID dentro de Chargebee tienen varios formatos. El ID de la fuente de pago puede ser algo como “pm_16CHQ2S9FKpykauA”, con un formato similar para los ID de Events como “ev_6olyVSIlySWm57D”. Nota que los dos primeros caracteres están contenidos en el nombre de la tabla, como “pm” para “Payment” y “ev” para “Event”. Sin embargo, la columna ID de otras tablas, como un plan de precios, suele tener un formato de código legible por humanos, como “agency-gbp-year”, y será visible en la interfaz de usuario. Lo mismo ocurre con los clientes.
Importes
Los datos de la API de Chargebee tienen un formato específico para los importes. Todos los importes se devuelven en unidades de centavos. El controlador de Invantive SQL convierte automática y totalmente de forma transparente los importes entre unidades de moneda y centavos.
Campos personalizados
La API de Chargebee admite campos personalizados en:
- Add-ons (Complementos)
- Customers (Clientes)
- Plans (Planes)
- Subscriptions (Suscripciones)
Todos los campos personalizados tienen un formato de texto. Dado que Chargebee aún no proporciona metadatos sobre los campos personalizados, Invantive SQL ofrece tablas adicionales para recuperar los valores de dichos campos:
- AddonCustomFieldValues
- CustomerCustomFieldValues
- PlanCustomFieldValues
- SubscriptionCustomFieldValues
Para cada combinación de registro y campo personalizado, existe un registro en estas tablas de campos personalizados. Por ejemplo, cuando el tipo de suscripción de Chargebee tiene dos campos personalizados “erp_id” y “chamber_of_commerce”, la tabla SubscriptionCustomFieldValues tendrá hasta dos filas por cada cliente.
Consulta simple sobre la API de Chargebee
Los datos de Chargebee se pueden combinar fácilmente en nuevos informes. Por ejemplo, la siguiente consulta te proporciona una lista de facturas basadas en suscripciones, incluyendo el número de 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
Consulta SQL usando campos personalizados de Chargebee
Algunos datos de Chargebee contienen valores de campos personalizados. Dado que puede haber múltiples valores de campos personalizados para cada entidad principal, puede ser útil pivotar dichos valores. Esto es especialmente útil al sincronizar los datos con un almacén de datos (data warehouse) o un almacén de datos operacional en un modelo de datos relacional tradicional. El siguiente ejemplo muestra cómo pivotar los datos de clientes de 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
Registrar un nuevo cliente de Chargebee a través de la API y actualizarlo
Sin embargo, como se mencionó antes, el controlador SQL para la API de Chargebee no solo cubre la recuperación de datos, sino que también permite DML (lenguaje de manipulación de datos) en Chargebee. La siguiente sentencia crea un nuevo cliente en Chargebee:
insert into customers
( id
, last_name
)
values
( 13031406
, 'Invantive BV'
)
Y la siguiente sentencia cambia el nombre del cliente:
update customers
set first_name = 'John'
where id = 13031406
--
-- Asegurarse de que los datos no se recuperen desde la caché.
--
set use-http-memory-cache false
set use-http-disk-cache false
select *
from customers
where id = 13031406
Ten en cuenta que el ID se proporciona en la sentencia insert y Chargebee lo utiliza.

