Buy Me a Coffee API y Google Sheets

Introducción

Uno de los casos de uso de Apps Script es el poder conectar y comunicarte con aplicaciones externas en Internet. Buy Me a Coffee es una plataforma de financiación colectiva que brinda a tu audiencia una manera fácil y rápida de decirte gracias.

En este tutorial te mostraré cómo trabajar con la API de Buy Me a Coffee con Apps Script. Te enseñaré a importar la información a un Google Sheet, donde podrás procesarla, analizarla e interpretarla para generar mejores insights de tu audiencia.

Lo que necesitarás

Un navegador con accesso a internet
Una cuenta de Google
Conocimientos básicos de Javascript/Apps Script
Una cuenta de Buy Me a Coffee (de preferencia con algunas transacciones)

Lo que haremos

Conectar con la API de BMC usando Apps Script
Usar el servicio urlFetchApp para hacer una solicitud a un host externo
Trabajar con datos con Apps Script
Escribir en las hojas de cálculo con Apps Script.

Paso 1. La documentación de BMC API

Primero que nada, tienes que ir a al sitio de desarrolladores de BMC. Aquí encontrarás como trabaja la API y los alcances que tiene, el proceso de autenticación, los códigos HTTP devueltos cuando hacemos una solicitud. En pocas palabras, toda la referencia de la API.

Da clic en el link de la esquina superior derecha para ingresar a tu cuenta o a la cuenta en la que vayas a practicar.

Paso 2. Obtener tu código de acceso

Una vez que te hayas loggeado y estés en el dashboard, da click en el botón "Create New Token".

Asigna un nombre a tu token. Al momento de escribir este post, los alcances de la API solo son de lectura, así que da lo mismo si marcas o dejas en blanco el checkbox del alcance.

Presiona el botón "Create"

Ya tienes tu token listo 🔑. Cópialo y guárdalo en un lugar seguro, ya que no se volverá a mostrar y lo necesitarás para hacer las solicitudes. En caso de extravío, necesitarás generar un nuevo token.

Paso 3. Acceder a la API

Abre o crea una nueva hoja de cálculo de google y en el menú extensiones, selecciona Apps Script.

Ahora debemos de declarar una constante para almacenar el token de acceso. Lo puedes declarar afuera de cualquier función para que tengas acceso desde cualquier parte del script.

// GLOBALS
const ACCESS_TOKEN = 'YOUR_API_ACCESS_TOKEN';

Ahora es tiempo de crear nuestra función principal, en este caso la llamaremos getBMCInfo(). Aquí necesitamos crear una url base que servirá para hacer la solicitud. En la documentación oficial hay un ejemplo de una consulta básica y el formato en el que debe de estar. Necesitaremos un objeto Javascript para especificar los headers, el método y si queremos silenciar las excepciones HTTP.

Ejemplo de una consulta básica.

curl https://developers.buymeacoffee.com/api/v1/supporters \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -X GET

Función getBMCInfo() (Para este ejemplo obtendremos los supporters que han donado, comprado un extra o han comprado una suscripción.

function getBMCInfo(){

  const url = 'https://developers.buymeacoffee.com/api/v1/supporters';

  const params = {
    headers: {
      'Authorization': 'Bearer ' + ACCESS_TOKEN
    },
    method: 'GET',
    muteHttpExceptions: true
  }
}

Ha llegado el momento de utilizar la magia de Apps Script. Usaremos la clase UrlFetchApp que nos permite conectarnos y comunicarnos con otros servicios en Internet. Almacenaremos en un constante la respuesta recibida, mientras que en la constante result convertiremos el JSON recibido en un objeto Javascript que será más fácil de manipular.

const response = UrlFetchApp.fetch(url, params);

const result = JSON.parse(response.getContentText());

Si todo salió bien y haces un console de la constante result, deberías de obtener un objeto como el siguiente. El objeto contiene distintas propiedades y valores, por ejemplo "current_page" contiene el valor 1, si no se especifica una página en especial, arrojará los resultados de la primera página. A vez el objeto "data" tendrá un array de objetos que tienen la información de cada transacción (la información que nos interesa analizar) También podemos encontrar las propiedades "total" que nos arroja el total de transacciones y "last_page" que nos arroja el último número de página.

{
  "current_page": 1,
  "data": [
    {
      "support_id": 245731,
      "support_note": null,
      "support_coffees": 1,
      "transaction_id": "3JV542690H0XXX",
      "support_visibility": 1,
      "support_created_on": "2020-08-05 09:38:26",
      "support_updated_on": "2020-08-05 09:38:26",
      "transfer_id": null,
      "supporter_name": null,
      "support_coffee_price": "1.0000",
      "support_email": "****@gmail.com",
      "is_refunded": null,
      "support_currency": "GBP",
      "support_note_pinned": 0,
      "referer": null,
      "country": "IN",
      "payer_email": "*****@gmail.com",
      "payment_platform": "paypal",
      "payer_name": "** Fora"
    },
...
"first_page_url": "https://developers.buymeacoffee.com/api/v1/supporters?page=1",
  "from": 1,
  "last_page": 2,
  "last_page_url": "https://developers.buymeacoffee.com/api/v1/supporters?page=2",
  "next_page_url": "https://developers.buymeacoffee.com/api/v1/supporters?page=2",
  "path": "https://developers.buymeacoffee.com/api/v1/supporters",
  "per_page": 5,
  "prev_page_url": null,
  "to": 5,
  "total": 10
}

Paso 4. Procesando la información

Necesitaremos crear y llenar un array bidimensional con el objeto "data". En primera instancia este objeto estará vacío, pero lo llenaremos dinámicamente con la información de cada elemento del objeto "data". Para esto iteraremos a travez del array con el loop forEach().

const data = result.data; 
var transactions = [];

data.forEach(coffeeTransaction =>{
    transactions.push([
      coffeeTransaction.support_id,
      coffeeTransaction.support_created_on,
      coffeeTransaction.support_currency,
      coffeeTransaction.support_coffees,
      coffeeTransaction.support_coffee_price,
      coffeeTransaction.support_coffees * coffeeTransaction.support_coffee_price
      ])
    });

Con el segmento de código anterior, obtendremos el id de la transacción, la fecha, el tipo de moneda, la cantidad de "cafés" y el precio. Además crearemos un campo calculado, el cual será el subtotal de cada operación.

Estos datos solo son por cuestiones educativas, pero puedes obtener las propiedades que desees trabajar.

Paso 5. Insertar la información en la hoja de cálculo

Una vez tengamos lleno el array de datos importaremos los valores. Primero necesitamos acceder a la hoja de cálculo a la que está ligado este script. Después a la hoja donde queremos insertar los datos y por último al rango de celdas de destino, por último, utilizaremos el método "setValues" para insertar los valores.

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheetTransactions = ss.getSheetByName('BMC Info');
const rangeInfo = sheetTransactions.getRange(2,1,transactions.length,transactions[0].length);
rangeInfo.setValues(transactions);

Paso 6. Menú personalizado.

Puedes crear un menú personalizado para ejecutar la función getBMCInfo() sin necesidad de acceder al editor de código. La función onOpen() se conoce como un activador simple y se ejecuta cada que se abre la hoja, cargando el menú.

function onOpen(){
    const ui = SpreadsheetApp.getUi();
    ui.createMenu('☕️ BMC API')
    .addItem('Import Transactions ☕️', 'getBMCInfo')
    .addToUi();
}

Paso 7. Extraer todas las transacciones

Si quieres ir más allá y extraer todas las transacciones y no solo las de la primera página, tendrás que hacer una consulta con un filtro que es el número de página y hacer el proceso anterior por cada llamada. Esto lo puedes hacer con un loop.

Primero, agrega una constante con la consulta, el número de página lo agregaremos dinámicamente más tarde.

Así quedarían las primeras líneas de la función

const url = 'https://developers.buymeacoffee.com/api/v1/supporters';
const query = '?page='
const params = {
  headers: {
    'Authorization': 'Bearer ' + ACCESS_TOKEN
  },
  method: 'GET',
  muteHttpExceptions: true
}

Ahora necesitas modificar un poco tu script y agregar un loop para iterar por el número de páginas, y por cad página iteraremos por los 5 registros.

for( let i = 1; i<= result.last_page; i++ ){
    const callAPI = UrlFetchApp.fetch(url + query + i, params);
    const result2 = JSON.parse(callAPI.getContentText());
    const data = result2.data;
    const current_page = result2.current_page;
    console.log(current_page);

    data.forEach(coffeeTransaction =>{
    transactions.push([
      coffeeTransaction.support_id,
      coffeeTransaction.support_created_on,
      coffeeTransaction.support_currency,
      coffeeTransaction.support_coffees,
      coffeeTransaction.support_coffee_price,
      coffeeTransaction.support_coffees * coffeeTransaction.support_coffee_price
      ])
    });

  }

Si este tutorial fue de ayuda o aprendiste algo nuevo puedes invitarme un café ☕️, lo cuál me ayuda a seguir creando contenido.

Wrap

Ahora sabes como conectar con la API de Buy Me usando Apps Script, extraer información e importarla a Google Sheets. Usamos ciertas propiedades por cuestiones educativas, pero puedes obtener más información y crear algo más complejo. Por ejemplo, el email de tus supporters por compra y enviar información relevante o alguna actualización. También podrías crear una aplicación que automáticamente muestre el número de supporters y la información del último café que te fue comprado y mostrarlo en tu página web.

Si lo prefieres, abajo te dejo un paso a paso de este tutorial en video.