/** * EasyBankData para Looker Studio (conector de comunidad) * ====================================================== * * Un conector de Looker Studio que lee tus movimientos o tus indicadores mensuales de la API de * EasyBankData con tu propia clave. Guía completa: https://easybankdata.com/docs/plantillas * * CÓMO SE INSTALA (una vez) * 1. https://script.google.com > Nuevo proyecto. Ponle de nombre «EasyBankData». * 2. Pega este fichero entero en «Código.gs». * 3. Configuración del proyecto (la rueda) > marca «Mostrar el archivo de manifiesto appsscript.json». * Abre appsscript.json y sustitúyelo por el que se descarga junto a este fichero. * 4. Implementar > Probar implementaciones > copia el «ID de implementación principal» y abre * https://lookerstudio.google.com/datasources/create?connectorId= * 5. Looker Studio pide autorizar el script y después la CLAVE: pega una de «Solo leer» (panel > * API y webhooks). Elige la empresa y qué datos quieres, y conecta. * * DÓNDE VA LA CLAVE * En las propiedades de usuario del script (PropertiesService.getUserProperties()), solo para tu cuenta * de Google. No va en el informe: quien vea el informe ve los datos con tus credenciales (así funcionan * las fuentes de Looker Studio), pero no ve la clave. Si compartes el informe, piensa en qué datos * enseña. Para quitarla: en la fuente de datos, «Editar conexión» > «Revocar acceso». * * SOLO LEE. Hace únicamente peticiones GET. Leer por la API no llama al banco ni gasta cupo de refrescos. * * EasySoft Tech S.L. · info@easysoft.es */ var cc = DataStudioApp.createCommunityConnector(); // 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'; var EBD_AYUDA = 'https://easybankdata.com/docs/plantillas'; // Las rutas del contrato que usa este conector, tal cual las declara /v1/openapi.json. Una prueba del // servicio comprueba que todas existen en el contrato. var EBD_RUTAS = { empresas: '/tenants', cuentas: '/tenants/{tenant}/accounts', movimientos: '/tenants/{tenant}/transactions', mensuales: '/tenants/{tenant}/insights/monthly' }; var EBD_PROP_CLAVE = 'easybankdata.clave'; var EBD_POR_PAGINA = 500; var EBD_MESES_MAXIMOS = 24; // Lo más que devuelve /insights/monthly de una vez. // ─── Autenticación: una clave de API ───────────────────────────────────────────────────────────── function getAuthType() { return cc.newAuthTypeResponse().setAuthType(cc.AuthType.KEY).setHelpUrl(EBD_AYUDA).build(); } function setCredentials(request) { var clave = String((request && request.key) || '').trim(); if (!ebdClaveQueFunciona_(clave)) return { errorCode: 'INVALID_CREDENTIALS' }; PropertiesService.getUserProperties().setProperty(EBD_PROP_CLAVE, clave); return { errorCode: 'NONE' }; } function isAuthValid() { var clave = PropertiesService.getUserProperties().getProperty(EBD_PROP_CLAVE); if (!clave) return false; // Looker Studio pregunta a menudo: se recuerda diez minutos que la clave funcionaba. var cache = CacheService.getUserCache(); if (cache.get('easybankdata.valida') === 'si') return true; var valida = ebdClaveQueFunciona_(clave); if (valida) cache.put('easybankdata.valida', 'si', 600); return valida; } function resetAuth() { PropertiesService.getUserProperties().deleteProperty(EBD_PROP_CLAVE); CacheService.getUserCache().remove('easybankdata.valida'); } function isAdminUser() { return false; } function ebdClaveQueFunciona_(clave) { if (!/^ebd_(live|test)_[A-Za-z0-9]+$/.test(clave)) return false; try { ebdPedir_(EBD_RUTAS.empresas, { limit: 1 }, clave); return true; } catch (e) { return false; } } // ─── Configuración: la empresa y qué datos ─────────────────────────────────────────────────────── function getConfig(request) { var config = cc.getConfig(); config .newInfo() .setId('info') .setText('Movimientos: uno por fila, en el intervalo de fechas del informe. Indicadores mensuales: ' + 'entradas, salidas y neto por mes (como mucho los 24 últimos del intervalo), sin los traspasos ' + 'entre cuentas propias.'); var empresas = []; try { empresas = ebdTodas_(EBD_RUTAS.empresas, {}); } catch (e) { // Sin la lista, se escribe el identificador a mano. } if (empresas.length > 0) { var selector = config.newSelectSingle().setId('tenant').setName('Empresa').setAllowOverride(true); empresas.forEach(function (e) { selector.addOption(config.newOptionBuilder().setLabel(e.name).setValue(e.id)); }); } else { config .newTextInput() .setId('tenant') .setName('Identificador de la empresa') .setHelpText('El «id» que devuelve GET /v1/tenants con tu clave.') .setAllowOverride(true); } config .newSelectSingle() .setId('dataset') .setName('Qué datos') .addOption(config.newOptionBuilder().setLabel('Movimientos').setValue('movimientos')) .addOption(config.newOptionBuilder().setLabel('Indicadores mensuales').setValue('mensuales')); config.setDateRangeRequired(true); return config.build(); } // ─── Esquema ───────────────────────────────────────────────────────────────────────────────────── function ebdCampos_(dataset) { var fields = cc.getFields(); var t = cc.FieldType; var a = cc.AggregationType; if (dataset === 'mensuales') { fields.newDimension().setId('mes').setName('Mes').setType(t.YEAR_MONTH); fields.newMetric().setId('entradas').setName('Entradas').setType(t.CURRENCY_EUR).setAggregation(a.SUM); fields.newMetric().setId('salidas').setName('Salidas').setType(t.CURRENCY_EUR).setAggregation(a.SUM); fields.newMetric().setId('neto').setName('Neto').setType(t.CURRENCY_EUR).setAggregation(a.SUM); fields.newMetric().setId('movimientos').setName('Movimientos').setType(t.NUMBER).setAggregation(a.SUM); fields.newMetric().setId('entradas_anio_anterior').setName('Entradas del año anterior') .setType(t.CURRENCY_EUR).setAggregation(a.SUM); fields.newMetric().setId('salidas_anio_anterior').setName('Salidas del año anterior') .setType(t.CURRENCY_EUR).setAggregation(a.SUM); fields.newMetric().setId('neto_anio_anterior').setName('Neto del año anterior') .setType(t.CURRENCY_EUR).setAggregation(a.SUM); fields.newMetric().setId('variacion_entradas').setName('Variación de las entradas') .setType(t.PERCENT).setAggregation(a.AVG); fields.newMetric().setId('variacion_salidas').setName('Variación de las salidas') .setType(t.PERCENT).setAggregation(a.AVG); fields.newDimension().setId('datos_de_ejemplo').setName('Datos de ejemplo').setType(t.BOOLEAN); return fields; } fields.newDimension().setId('id').setName('Identificador').setType(t.TEXT); fields.newDimension().setId('fecha').setName('Fecha').setType(t.YEAR_MONTH_DAY); fields.newDimension().setId('cuenta').setName('Cuenta').setType(t.TEXT); fields.newDimension().setId('concepto').setName('Concepto').setType(t.TEXT); fields.newDimension().setId('contraparte').setName('Contraparte').setType(t.TEXT); fields.newDimension().setId('categoria').setName('Categoría').setType(t.TEXT); fields.newDimension().setId('codigo_categoria').setName('Código de categoría').setType(t.TEXT); fields.newDimension().setId('etiquetas').setName('Etiquetas').setType(t.TEXT); fields.newDimension().setId('centro_de_coste').setName('Centro de coste').setType(t.TEXT); fields.newDimension().setId('traspaso').setName('Traspaso entre cuentas propias').setType(t.TEXT); fields.newDimension().setId('de_ejemplo').setName('Dato de ejemplo').setType(t.BOOLEAN); fields.newMetric().setId('importe').setName('Importe').setType(t.CURRENCY_EUR).setAggregation(a.SUM); fields.newMetric().setId('entrada').setName('Entrada').setType(t.CURRENCY_EUR).setAggregation(a.SUM); fields.newMetric().setId('salida').setName('Salida').setType(t.CURRENCY_EUR).setAggregation(a.SUM); fields.newMetric().setId('numero').setName('Número de movimientos').setType(t.NUMBER).setAggregation(a.SUM); return fields; } function getSchema(request) { return { schema: ebdCampos_(ebdDataset_(request)).build() }; } // ─── Datos ─────────────────────────────────────────────────────────────────────────────────────── function getData(request) { var dataset = ebdDataset_(request); var pedidos = request.fields.map(function (f) { return f.name; }); var campos = ebdCampos_(dataset).forIds(pedidos); var filas; try { filas = dataset === 'mensuales' ? ebdMensuales_(request) : ebdMovimientos_(request); } catch (e) { cc.newUserError().setDebugText(String(e)).setText('EasyBankData: ' + e.message).throwException(); } return { schema: campos.build(), rows: filas.map(function (fila) { return { values: pedidos.map(function (id) { return fila[id]; }) }; }) }; } function ebdMovimientos_(request) { var rango = request.dateRange || {}; var consulta = {}; if (rango.startDate) consulta.from = rango.startDate; if (rango.endDate) consulta.to = rango.endDate; var cuentas = {}; ebdTodas_(ebdRuta_(EBD_RUTAS.cuentas, request), {}).forEach(function (c) { cuentas[c.id] = c.name || c.identifier || c.id; }); return ebdTodas_(ebdRuta_(EBD_RUTAS.movimientos, request), consulta).map(function (m) { var importe = ebdNumero_(m.amount); var clasificacion = m.classification || {}; var contraparte = m.counterparty || {}; return { id: m.id, fecha: String(m.date || '').replace(/-/g, ''), cuenta: cuentas[m.account_id] || m.account_id, concepto: m.description || '', contraparte: contraparte.masked ? '(enmascarada)' : contraparte.name || '', categoria: clasificacion.label || '', codigo_categoria: clasificacion.category || '', etiquetas: (m.tags || []).map(function (e) { return e.name; }).join(', '), centro_de_coste: m.cost_center ? m.cost_center.name : '', traspaso: m.transfer_status || '', de_ejemplo: m.is_demo === true, importe: importe, entrada: importe > 0 ? importe : 0, salida: importe < 0 ? importe : 0, numero: 1 }; }); } function ebdMensuales_(request) { var rango = request.dateRange || {}; var hasta = (rango.endDate || '').slice(0, 7); var desde = (rango.startDate || '').slice(0, 7); // La API da como mucho 24 meses: con un intervalo más largo, los 24 últimos. if (desde && hasta && ebdMesesEntre_(desde, hasta) > EBD_MESES_MAXIMOS) desde = ebdMesAtras_(hasta, EBD_MESES_MAXIMOS - 1); var consulta = {}; if (desde) consulta.from = desde; if (hasta) consulta.to = hasta; var datos = ebdPedir_(ebdRuta_(EBD_RUTAS.mensuales, request), consulta); return (datos.months || []).map(function (m) { var anterior = m.previous_year || {}; return { mes: String(m.period).replace('-', ''), entradas: ebdEuros_(m.inflows_cents), salidas: ebdEuros_(m.outflows_cents), neto: ebdEuros_(m.net_cents), movimientos: m.transactions, entradas_anio_anterior: ebdEuros_(anterior.inflows_cents), salidas_anio_anterior: ebdEuros_(anterior.outflows_cents), neto_anio_anterior: ebdEuros_(anterior.net_cents), // La API da el porcentaje entero (12 = 12 %); Looker Studio espera la fracción. variacion_entradas: m.inflows_change_percent == null ? null : m.inflows_change_percent / 100, variacion_salidas: m.outflows_change_percent == null ? null : m.outflows_change_percent / 100, datos_de_ejemplo: datos.sample_data === true }; }); } // ─── La API ────────────────────────────────────────────────────────────────────────────────────── function ebdPedir_(ruta, consulta, clave) { clave = clave || PropertiesService.getUserProperties().getProperty(EBD_PROP_CLAVE); if (!clave) throw new Error('Falta la clave de la API.'); 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. } throw new Error( 'respondió ' + codigo + (error.code ? ' (' + error.code + ')' : '') + ': ' + (error.message || String(texto).slice(0, 200)) + (error.request_id ? ' · petición ' + error.request_id : '') ); } } 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, request) { var empresa = String((request.configParams && request.configParams.tenant) || '').trim(); if (!empresa) { // Sin empresa elegida: vale si la clave alcanza una sola. var empresas = ebdTodas_(EBD_RUTAS.empresas, {}); if (empresas.length !== 1) throw new Error('Elige la empresa en la configuración de la fuente de datos.'); empresa = empresas[0].id; } return plantilla.replace('{tenant}', encodeURIComponent(empresa)); } function ebdDataset_(request) { return request && request.configParams && request.configParams.dataset === 'mensuales' ? 'mensuales' : 'movimientos'; } function ebdNumero_(v) { var n = Number(v); return isNaN(n) ? 0 : n; } function ebdEuros_(centimos) { return centimos === null || centimos === undefined ? null : centimos / 100; } function ebdMesesEntre_(desde, hasta) { var d = desde.split('-'); var h = hasta.split('-'); return (Number(h[0]) - Number(d[0])) * 12 + (Number(h[1]) - Number(d[1])) + 1; } function ebdMesAtras_(mes, n) { var p = mes.split('-'); var total = Number(p[0]) * 12 + (Number(p[1]) - 1) - n; var anio = Math.floor(total / 12); var m = (total % 12) + 1; return anio + '-' + (m < 10 ? '0' + m : m); }