/** * EasyBankData para Google Sheets * ================================ * * Rellena esta hoja con tus cuentas, tus movimientos y tus indicadores mensuales, leídos de la API de * EasyBankData con tu propia clave. Guía completa: https://easybankdata.com/docs/plantillas * * CÓMO SE INSTALA * 1. En tu hoja: Extensiones > Apps Script. Borra lo que haya en «Código.gs» y pega este fichero entero. * 2. Guarda y vuelve a la hoja. Recárgala: aparece el menú «EasyBankData». * 3. EasyBankData > Poner la clave de la API. Usa una clave de «Solo leer» (se saca en el panel, en * API y webhooks). Google te pedirá permiso para que el script salga a internet y toque * esta hoja: es lo que necesita para llamar a la API y escribir los datos. * 4. EasyBankData > Actualizar todo. * * DÓNDE VA LA CLAVE * En las propiedades de usuario del script (PropertiesService.getUserProperties()): solo las ves tú, con * tu cuenta de Google, y NUNCA se escribe en una celda. Quien comparta la hoja contigo no la ve; si quiere * actualizarla, tendrá que poner su propia clave. «Borrar la clave de esta cuenta de Google» la quita. * * QUÉ ESCRIBE (hojas que crea si no existen, y que REESCRIBE: no pongas nada tuyo dentro) * - «EBD Cuentas»: las cuentas con sus saldos. * - «EBD Movimientos»: los movimientos. La primera vez los trae todos; después, solo los que han * cambiado desde la última vez (updated_since + sort=updated) y los mezcla por su identificador. * - «EBD Indicadores»: entradas, salidas y neto de los últimos 12 meses completos, con el mismo mes del * año anterior. * - «EBD Categorías»: entradas y salidas por categoría y mes, en formato largo (listo para una tabla * dinámica). * Para tus cálculos y gráficos, usa otras hojas que lean de estas. * * SOLO LEE. Hace únicamente peticiones GET: con una clave de «Solo leer» no puede cambiar nada aunque * quisiera. Leer por la API no llama al banco ni gasta cupo de refrescos. * * Límites de Google que conviene saber: una ejecución dura como mucho 6 minutos. Con decenas de miles de * movimientos, la primera carga puede no caber; las siguientes (solo cambios) son cortas. * * EasySoft Tech S.L. · info@easysoft.es */ // La dirección de la API. La guía la ajusta a la instalación desde la que la descargas. var EBD_BASE = 'https://app.easybankdata.com/v1'; // Las rutas del contrato que usa este script, escritas tal cual las declara /v1/openapi.json. Una prueba // del servicio comprueba que todas existen en el contrato: si alguna cambia, la plantilla se corrige antes // de publicarse. var EBD_RUTAS = { empresas: '/tenants', cuentas: '/tenants/{tenant}/accounts', movimientos: '/tenants/{tenant}/transactions', mensuales: '/tenants/{tenant}/insights/monthly', categorias: '/tenants/{tenant}/insights/categories' }; var EBD_HOJAS = { cuentas: 'EBD Cuentas', movimientos: 'EBD Movimientos', mensuales: 'EBD Indicadores', categorias: 'EBD Categorías' }; var EBD_POR_PAGINA = 500; // El máximo que admite la API. var EBD_PROP_CLAVE = 'easybankdata.clave'; var EBD_PROP_EMPRESA = 'easybankdata.empresa'; var EBD_PROP_MARCA = 'easybankdata.movimientos.marca'; var EBD_PROP_ORIGEN = 'easybankdata.movimientos.origen'; // ─── Menú ──────────────────────────────────────────────────────────────────────────────────────── function onOpen() { SpreadsheetApp.getUi() .createMenu('EasyBankData') .addItem('Poner la clave de la API', 'ebdPonerClave') .addItem('Elegir la empresa', 'ebdElegirEmpresa') .addSeparator() .addItem('Actualizar todo', 'ebdActualizarTodo') .addItem('Actualizar solo los movimientos que han cambiado', 'ebdActualizarMovimientos') .addItem('Volver a cargar todos los movimientos', 'ebdRecargarMovimientos') .addSeparator() .addItem('Activar la actualización diaria (6:00)', 'ebdActivarDiaria') .addItem('Desactivar la actualización diaria', 'ebdDesactivarDiaria') .addSeparator() .addItem('Borrar la clave de esta cuenta de Google', 'ebdBorrarClave') .addToUi(); } function ebdPonerClave() { var ui = SpreadsheetApp.getUi(); var respuesta = ui.prompt( 'Clave de la API de EasyBankData', 'Pega tu clave (ebd_live_… o ebd_test_…). Mejor una de «Solo leer». Se guarda solo para tu cuenta de ' + 'Google, fuera de la hoja.', ui.ButtonSet.OK_CANCEL ); if (respuesta.getSelectedButton() !== ui.Button.OK) return; var clave = String(respuesta.getResponseText() || '').trim(); if (!/^ebd_(live|test)_[A-Za-z0-9]+$/.test(clave)) { ui.alert('Eso no parece una clave de EasyBankData: empiezan por ebd_live_ o ebd_test_.'); return; } // Se prueba antes de guardarla: una clave que no sirve no se guarda. var empresas; try { empresas = ebdTodas_(EBD_RUTAS.empresas, {}, clave); } catch (e) { ui.alert('No se ha guardado la clave. ' + e.message); return; } PropertiesService.getUserProperties().setProperty(EBD_PROP_CLAVE, clave); if (empresas.length === 1) { ebdGuardarEmpresa_(empresas[0].id); ui.alert('Clave guardada. Empresa: ' + empresas[0].name + '. Ya puedes usar «Actualizar todo».'); } else if (empresas.length === 0) { ui.alert('Clave guardada, pero no alcanza ninguna empresa.'); } else { ebdElegirEmpresa(); } } function ebdElegirEmpresa() { var ui = SpreadsheetApp.getUi(); var empresas; try { empresas = ebdTodas_(EBD_RUTAS.empresas, {}); } catch (e) { ui.alert(e.message); return; } if (empresas.length === 0) { ui.alert('La clave no alcanza ninguna empresa.'); return; } var lista = empresas .map(function (e, i) { return (i + 1) + '. ' + e.name; }) .join('\n'); var respuesta = ui.prompt('¿Qué empresa?', lista + '\n\nEscribe el número:', ui.ButtonSet.OK_CANCEL); if (respuesta.getSelectedButton() !== ui.Button.OK) return; var n = parseInt(respuesta.getResponseText(), 10); if (!(n >= 1 && n <= empresas.length)) { ui.alert('Ese número no está en la lista.'); return; } ebdGuardarEmpresa_(empresas[n - 1].id); ui.alert('Empresa elegida: ' + empresas[n - 1].name + '.'); } function ebdBorrarClave() { PropertiesService.getUserProperties().deleteProperty(EBD_PROP_CLAVE); SpreadsheetApp.getUi().alert('Clave borrada de tu cuenta de Google. Los datos ya escritos siguen en la hoja.'); } function ebdActualizarTodo() { ebdEjecutar_(function () { ebdActualizarTodo_(); }); } function ebdActualizarMovimientos() { ebdEjecutar_(function () { ebdEscribirMovimientos_(ebdCuentasPorId_(ebdLeerCuentas_()), false); }); } function ebdRecargarMovimientos() { ebdEjecutar_(function () { ebdEscribirMovimientos_(ebdCuentasPorId_(ebdLeerCuentas_()), true); }); } function ebdActivarDiaria() { ebdQuitarDisparadores_(); ScriptApp.newTrigger('ebdActualizacionDiaria').timeBased().everyDays(1).atHour(6).create(); SpreadsheetApp.getUi().alert( 'Hecho: la hoja se actualizará sola cada día hacia las 6:00, con tu clave. Si falla, Google te lo manda por correo.' ); } function ebdDesactivarDiaria() { var quitados = ebdQuitarDisparadores_(); SpreadsheetApp.getUi().alert(quitados > 0 ? 'Actualización diaria desactivada.' : 'No había ninguna activada.'); } /** Lo que llama el disparador diario. Sin ventanas: en un disparador no hay nadie mirando. */ function ebdActualizacionDiaria() { ebdActualizarTodo_(); } // ─── Lo que hace el trabajo ────────────────────────────────────────────────────────────────────── function ebdActualizarTodo_() { var cuentas = ebdLeerCuentas_(); ebdEscribirCuentas_(cuentas); ebdEscribirMovimientos_(ebdCuentasPorId_(cuentas), false); ebdEscribirMensuales_(); ebdEscribirCategorias_(); } function ebdLeerCuentas_() { return ebdTodas_(ebdRuta_(EBD_RUTAS.cuentas), {}); } function ebdCuentasPorId_(cuentas) { var mapa = {}; cuentas.forEach(function (c) { mapa[c.id] = c.name || c.identifier || c.id; }); return mapa; } function ebdEscribirCuentas_(cuentas) { var cabecera = [ 'id', 'Nombre', 'IBAN o identificador', 'Tipo', 'Divisa', 'Saldo disponible', 'Saldo contable', 'Movimientos', 'Control de saldo', 'Última lectura', 'De ejemplo' ]; var filas = cuentas.map(function (c) { return [ c.id, ebdTexto_(c.name), ebdTexto_(c.identifier), ebdTexto_(c.type), c.currency || '', ebdImporte_(c.balance_available), ebdImporte_(c.balance_current), c.transactions_count == null ? '' : c.transactions_count, c.balance_check_status || '', ebdInstante_(c.last_seen_at), c.is_demo === true ]; }); var hoja = ebdHoja_(EBD_HOJAS.cuentas); ebdVolcar_(hoja, cabecera, filas); ebdFormato_(hoja, filas.length, [6, 7], '#,##0.00'); ebdFormato_(hoja, filas.length, [10], 'yyyy-mm-dd hh:mm'); ebdNota_(hoja, filas.some(function (f) { return f[10] === true; })); } var EBD_CABECERA_MOVIMIENTOS = [ 'id', 'Fecha', 'Fecha valor', 'Cuenta', 'id de la cuenta', 'Concepto', 'Contraparte', 'Importe', 'Divisa', 'Saldo', 'Categoría', 'Código de categoría', 'Origen de la categoría', 'Categoría del banco', 'Etiquetas', 'Centro de coste', 'Traspaso', 'De ejemplo', 'Modificado' ]; /** * Los movimientos: todos la primera vez (o al pedir «volver a cargar»); después, solo lo que cambió desde la * marca guardada, mezclado por identificador. La marca es el `updated_at` más alto que se ha visto: pedir * desde ahí con `sort=updated` puede repetir alguno del mismo instante (se sobrescribe), nunca perderlo. */ function ebdEscribirMovimientos_(nombresDeCuentas, desdeCero) { var props = PropertiesService.getDocumentProperties(); var empresa = ebdEmpresa_(); // Si cambian la empresa o el tipo de clave (prueba / real), lo que hay en la hoja es de otro sitio. var origen = empresa + '|' + (ebdClave_().indexOf('ebd_test_') === 0 ? 'test' : 'live'); if (props.getProperty(EBD_PROP_ORIGEN) !== origen) desdeCero = true; var marca = desdeCero ? null : props.getProperty(EBD_PROP_MARCA); var consulta = { sort: 'updated' }; if (marca) consulta.updated_since = marca; var nuevos = ebdTodas_(ebdRuta_(EBD_RUTAS.movimientos), consulta); var hoja = ebdHoja_(EBD_HOJAS.movimientos); var filas = []; var posicion = {}; if (!desdeCero && hoja.getLastRow() > 1) { filas = hoja.getRange(2, 1, hoja.getLastRow() - 1, EBD_CABECERA_MOVIMIENTOS.length).getValues(); filas.forEach(function (f, i) { posicion[f[0]] = i; }); } var marcaNueva = marca; nuevos.forEach(function (m) { var fila = ebdFilaDeMovimiento_(m, nombresDeCuentas); if (Object.prototype.hasOwnProperty.call(posicion, m.id)) { filas[posicion[m.id]] = fila; } else { posicion[m.id] = filas.length; filas.push(fila); } if (m.updated_at && (!marcaNueva || new Date(m.updated_at) > new Date(marcaNueva))) { marcaNueva = m.updated_at; } }); // Del más reciente al más antiguo, como en el panel. filas.sort(function (a, b) { var fa = a[1] instanceof Date ? a[1].getTime() : 0; var fb = b[1] instanceof Date ? b[1].getTime() : 0; return fb - fa || (a[0] < b[0] ? 1 : a[0] > b[0] ? -1 : 0); }); ebdVolcar_(hoja, EBD_CABECERA_MOVIMIENTOS, filas); ebdFormato_(hoja, filas.length, [2, 3], 'yyyy-mm-dd'); ebdFormato_(hoja, filas.length, [8, 10], '#,##0.00'); ebdFormato_(hoja, filas.length, [19], 'yyyy-mm-dd hh:mm'); ebdNota_(hoja, filas.some(function (f) { return f[17] === true; })); props.setProperty(EBD_PROP_ORIGEN, origen); if (marcaNueva) props.setProperty(EBD_PROP_MARCA, marcaNueva); else props.deleteProperty(EBD_PROP_MARCA); } function ebdFilaDeMovimiento_(m, nombresDeCuentas) { var clasificacion = m.classification || {}; var contraparte = m.counterparty || {}; return [ m.id, ebdFecha_(m.date), ebdFecha_(m.value_date), ebdTexto_(nombresDeCuentas[m.account_id] || ''), m.account_id, ebdTexto_(m.description), ebdTexto_(contraparte.masked ? '(enmascarada)' : contraparte.name), ebdImporte_(m.amount), m.currency || '', ebdImporte_(m.balance), ebdTexto_(clasificacion.label), clasificacion.category || '', clasificacion.source || '', ebdTexto_(m.category), ebdTexto_((m.tags || []).map(function (t) { return t.name; }).join(', ')), ebdTexto_(m.cost_center ? m.cost_center.name : ''), m.transfer_status || '', m.is_demo === true, ebdInstante_(m.updated_at) ]; } function ebdEscribirMensuales_() { var datos = ebdPedir_(ebdRuta_(EBD_RUTAS.mensuales), {}); var cabecera = [ 'Mes', 'Entradas', 'Salidas', 'Neto', 'Movimientos', 'Mes del año anterior', 'Entradas año anterior', 'Salidas año anterior', 'Neto año anterior', 'Variación entradas %', 'Variación salidas %' ]; var filas = (datos.months || []).map(function (m) { var anterior = m.previous_year || {}; return [ m.period, ebdEuros_(m.inflows_cents), ebdEuros_(m.outflows_cents), ebdEuros_(m.net_cents), m.transactions, anterior.period || '', ebdEuros_(anterior.inflows_cents), ebdEuros_(anterior.outflows_cents), ebdEuros_(anterior.net_cents), m.inflows_change_percent == null ? '' : m.inflows_change_percent, m.outflows_change_percent == null ? '' : m.outflows_change_percent ]; }); var hoja = ebdHoja_(EBD_HOJAS.mensuales); ebdVolcar_(hoja, cabecera, filas, [1, 6]); ebdFormato_(hoja, filas.length, [2, 3, 4, 7, 8, 9], '#,##0.00'); ebdNota_(hoja, datos.sample_data === true, datos.other_currency_accounts); } function ebdEscribirCategorias_() { var datos = ebdPedir_(ebdRuta_(EBD_RUTAS.categorias), {}); var cabecera = ['Mes', 'Código de categoría', 'Categoría', 'Entradas', 'Salidas', 'Movimientos']; var filas = []; (datos.categories || []).forEach(function (c) { (c.months || []).forEach(function (m) { filas.push([ m.period, c.category || '', ebdTexto_(c.label), ebdEuros_(m.inflows_cents), ebdEuros_(m.outflows_cents), m.transactions ]); }); }); var hoja = ebdHoja_(EBD_HOJAS.categorias); ebdVolcar_(hoja, cabecera, filas, [1]); ebdFormato_(hoja, filas.length, [4, 5], '#,##0.00'); ebdNota_(hoja, datos.sample_data === true, datos.other_currency_accounts); } // ─── La API ────────────────────────────────────────────────────────────────────────────────────── /** Una llamada GET a la API. Espera y reintenta si responde 429 (con su Retry-After). */ function ebdPedir_(ruta, consulta, clave) { clave = clave || ebdClave_(); var url = EBD_BASE + ruta + ebdConsulta_(consulta); for (var intento = 0; ; intento++) { var respuesta = UrlFetchApp.fetch(url, { method: 'get', headers: { Authorization: 'Bearer ' + clave, Accept: 'application/json' }, muteHttpExceptions: true, followRedirects: false }); var codigo = respuesta.getResponseCode(); if (codigo === 429 && intento < 3) { var cabeceras = respuesta.getHeaders(); var espera = parseInt(cabeceras['Retry-After'] || cabeceras['retry-after'] || '5', 10); Utilities.sleep(Math.min(Math.max(espera, 1), 60) * 1000); continue; } var texto = respuesta.getContentText(); if (codigo >= 200 && codigo < 300) return JSON.parse(texto); var error = {}; try { error = JSON.parse(texto); } catch (e) { // No era JSON: se enseña el principio del texto. } throw new Error( 'EasyBankData respondió ' + codigo + (error.code ? ' (' + error.code + ')' : '') + ': ' + (error.message || String(texto).slice(0, 200)) + (error.request_id ? ' · petición ' + error.request_id : '') ); } } /** Todas las páginas de una lista, siguiendo el testigo (`pagination.next_cursor`). */ function ebdTodas_(ruta, consulta, clave) { var filas = []; var cursor = null; do { var q = {}; Object.keys(consulta).forEach(function (k) { q[k] = consulta[k]; }); q.limit = EBD_POR_PAGINA; if (cursor) q.cursor = cursor; var pagina = ebdPedir_(ruta, q, clave); Array.prototype.push.apply(filas, pagina.data || []); cursor = pagina.pagination && pagina.pagination.has_more ? pagina.pagination.next_cursor : null; } while (cursor); return filas; } function ebdConsulta_(consulta) { var partes = Object.keys(consulta || {}) .filter(function (k) { return consulta[k] !== null && consulta[k] !== undefined && consulta[k] !== ''; }) .map(function (k) { return encodeURIComponent(k) + '=' + encodeURIComponent(String(consulta[k])); }); return partes.length ? '?' + partes.join('&') : ''; } function ebdRuta_(plantilla) { return plantilla.replace('{tenant}', encodeURIComponent(ebdEmpresa_())); } function ebdClave_() { var clave = PropertiesService.getUserProperties().getProperty(EBD_PROP_CLAVE); if (!clave) throw new Error('Falta la clave: menú EasyBankData > Poner la clave de la API.'); return clave; } function ebdEmpresa_() { var empresa = PropertiesService.getDocumentProperties().getProperty(EBD_PROP_EMPRESA); if (!empresa) throw new Error('Falta la empresa: menú EasyBankData > Elegir la empresa.'); return empresa; } function ebdGuardarEmpresa_(id) { var props = PropertiesService.getDocumentProperties(); if (props.getProperty(EBD_PROP_EMPRESA) !== id) { props.setProperty(EBD_PROP_EMPRESA, id); props.deleteProperty(EBD_PROP_MARCA); } } // ─── La hoja ───────────────────────────────────────────────────────────────────────────────────── function ebdEjecutar_(trabajo) { var libro = SpreadsheetApp.getActive(); try { libro.toast('Leyendo de EasyBankData…', 'EasyBankData', 5); trabajo(); libro.toast('Hecho.', 'EasyBankData', 5); } catch (e) { SpreadsheetApp.getUi().alert(String(e && e.message ? e.message : e)); } } function ebdHoja_(nombre) { var libro = SpreadsheetApp.getActive(); return libro.getSheetByName(nombre) || libro.insertSheet(nombre); } /** Reescribe la hoja entera: cabecera y filas. `columnasDeTexto`: las que llevan meses «AAAA-MM». */ function ebdVolcar_(hoja, cabecera, filas, columnasDeTexto) { hoja.clearContents(); (columnasDeTexto || []).forEach(function (c) { // «2026-08» es un texto: sin esto, Sheets lo convierte en una fecha. hoja.getRange(1, c, Math.max(filas.length + 1, 2), 1).setNumberFormat('@'); }); hoja.getRange(1, 1, 1, cabecera.length).setValues([cabecera]).setFontWeight('bold'); if (filas.length > 0) hoja.getRange(2, 1, filas.length, cabecera.length).setValues(filas); hoja.setFrozenRows(1); } function ebdFormato_(hoja, n, columnas, formato) { if (n === 0) return; columnas.forEach(function (c) { hoja.getRange(2, c, n, 1).setNumberFormat(formato); }); } function ebdNota_(hoja, deEjemplo, otrasDivisas) { var nota = 'Actualizado desde EasyBankData el ' + Utilities.formatDate(new Date(), Session.getScriptTimeZone(), 'yyyy-MM-dd HH:mm') + '.'; if (deEjemplo) nota += '\nOJO: son DATOS DE EJEMPLO, no los de la empresa.'; if (otrasDivisas) nota += '\n' + otrasDivisas + ' cuenta(s) en otra divisa no se suman aquí.'; hoja.getRange(1, 1).setNote(nota); } // ─── Conversiones ──────────────────────────────────────────────────────────────────────────────── /** * Un texto que viene de fuera (el concepto, la contraparte): lo escribe un tercero. Si empieza por = + - @, * Sheets lo tomaría por una fórmula; el apóstrofo delante lo deja como texto y no se ve. */ function ebdTexto_(v) { if (v === null || v === undefined) return ''; var s = String(v); return /^[=+\-@]/.test(s) ? "'" + s : s; } /** Los importes llegan como decimal en texto («-19.95»); en la hoja van como número para poder sumarlos. */ function ebdImporte_(v) { if (v === null || v === undefined || v === '') return ''; var n = Number(v); return isNaN(n) ? '' : n; } /** Los indicadores llegan en céntimos enteros. */ function ebdEuros_(centimos) { if (centimos === null || centimos === undefined) return ''; return centimos / 100; } /** «AAAA-MM-DD» como fecha de la hoja (sin hora ni zona: es un día del calendario). */ function ebdFecha_(v) { if (!v) return ''; var p = String(v).split('-'); return new Date(Number(p[0]), Number(p[1]) - 1, Number(p[2])); } function ebdInstante_(v) { return v ? new Date(v) : ''; } function ebdQuitarDisparadores_() { var quitados = 0; ScriptApp.getProjectTriggers().forEach(function (t) { if (t.getHandlerFunction() === 'ebdActualizacionDiaria') { ScriptApp.deleteTrigger(t); quitados++; } }); return quitados; }