Önfrissülő szabadság-riport Google Sheetsben a Collabin API-val

A pénzügynek negyedéves távollét-kimutatás kell, egy vezetőnek kapacitás-tábla, a HR vezet egy törzs-táblázatot — a szabadságadatok előbb-utóbb Google Sheetsben kötnek ki. Másolgatás helyett építhetsz olyan táblázatot, amely a Collabin REST API-ból magától töltődik és frissül, Google Apps Scripttel: nincs szerver, nincs költség, nagyjából harminc sor kód, másolásra készen.

Mire lesz szükséged

• Collabin-fiókra Pro csomaggal és egy csak olvasható API-kulcsra (a generálást az API gyorstalpaló mutatja — riporthoz a csak olvasható bőven elég).
• Egy Google-fiókra és egy üres Google-táblázatra.

1. lépés: Szerkesztő megnyitása és a kulcs biztonságos tárolása

A táblázatban válaszd a Bővítmények → Apps Script menüt. Mielőtt kódot írnál, tedd a kulcsot oda, ahol nem a kód része: a szerkesztőben nyisd meg a Projektbeállítások → Szkripttulajdonságok részt, és vegyél fel egy COLLABIN_API_KEY nevű tulajdonságot a kulcsoddal. A szkripttulajdonság kimarad magából a kódból, a verzióelőzményekből, és nem látja az sem, akivel megosztod a táblázatot.

2. lépés: Illeszd be a szkriptet

Cseréld le a szerkesztő tartalmát erre:

const BASE_URL = 'https://api.collabin.eu';

function syncCollabinLeaves() {
  const apiKey = PropertiesService.getScriptProperties()
    .getProperty('COLLABIN_API_KEY');
  if (!apiKey) {
    throw new Error('Vedd fel a COLLABIN_API_KEY kulcsot a Szkripttulajdonságok közé.');
  }

  const year = new Date().getFullYear();
  const leaves = fetchAll(
    '/v1/leaves?status=APPROVED&start=' + year + '-01-01&end=' + year + '-12-31',
    apiKey
  );

  const rows = leaves.map(function (l) {
    return [
      l.user ? l.user.name : '#' + l.user_id,
      l.leave_type ? l.leave_type.name : '',
      l.start_date.slice(0, 10),
      l.end_date.slice(0, 10),
      l.is_half_day ? 'igen' : 'nem',
      l.status
    ];
  });

  const ss = SpreadsheetApp.getActiveSpreadsheet();
  const sheet = ss.getSheetByName('Szabadságok') || ss.insertSheet('Szabadságok');
  sheet.clearContents();
  sheet.getRange(1, 1, 1, 6)
    .setValues([['Név', 'Típus', 'Kezdete', 'Vége', 'Fél nap', 'Státusz']]);
  if (rows.length > 0) {
    sheet.getRange(2, 1, rows.length, 6).setValues(rows);
  }
  sheet.getRange('A1:F1').setFontWeight('bold');
}

// Végiglapozza a /v1 lista-végpontot, és minden elemet visszaad.
function fetchAll(path, apiKey) {
  const sep = path.indexOf('?') === -1 ? '?' : '&';
  const limit = 500; // az API maximuma
  let offset = 0;
  let all = [];
  for (;;) {
    const url = BASE_URL + path + sep + 'limit=' + limit + '&offset=' + offset;
    const res = UrlFetchApp.fetch(url, {
      headers: { 'X-API-Key': apiKey }
    });
    const body = JSON.parse(res.getContentText());
    all = all.concat(body.data);
    if (body.data.length === 0 || all.length >= body.total) {
      return all;
    }
    offset += limit;
  }
}

Néhány dolog, amit ez a szkript jól csinál, és az ad-hoc verziók általában elrontanak:

• Lapozás. A lista-végpontok hívásonként legfeljebb 500 elemet adnak vissza; a fetchAll addig lépteti a limit/offset párost, amíg mindent össze nem gyűjtött — a riport akkor is teljes marad, ha az előzmények túlnőnek egy oldalon.
• A nevek benne vannak. A leaves válasz beágyazva tartalmazza a user és leave_type objektumokat, így nem kell második lekérés vagy FKERES.
• A dátumszűrő átfedésre szűr — a decemberben kezdődő és januárban végződő szabadság mindkét év riportjában megjelenik.

3. lépés: Futtasd le egyszer, és engedélyezd

Válaszd ki a syncCollabinLeaves függvényt az eszköztáron, és nyomd meg a Futtatás gombot. A Google engedélyt kér a szkriptnek (táblázat-hozzáférés és külső szolgáltatás hívása kell neki) — ez csak egyszer történik meg. Pár másodperc múlva a Szabadságok fülön ott az adat.

4. lépés: Frissítse magát

A szkriptszerkesztőben nyisd meg az Eseményindítók részt (vekker ikon), és adj hozzá egyet: függvény syncCollabinLeaves, eseményforrás Időalapú, például minden reggel 6 és 7 között. Innentől a táblázat egyszerűen mindig friss — a rá épített kimutatások, diagramok és QUERY() képletek vele együtt frissülnek.

Ötletek, amire ráépíthetsz

• Nap/fő kimutatás: tegyél kimutatástáblát a Szabadságok fülre — sorok: Név, értékek: Kezdete DARAB — gyors kérelem-darabszám fejenként.
• Függő kérelmek: cseréld a status=APPROVED szűrőt status=PENDING-re egy jóváhagyási-hátralék dashboardhoz.
• Egy ember előzményei: fűzd hozzá a &user_id=7 paramétert egyéni riportokhoz.
• Inkrementális szinkron: nagyon nagy szervezetnél az updated_since paraméterrel csak a változásokat kérd le, és fésüld össze, a teljes újraírás helyett.

Figyelj a rate limitre

Az API kulcsonként percenként 120 kérést enged. A fenti szkript 500 rekordonként egy kérést használ, így még egy tekintélyes előzmény is csak néhány hívás — de ha beszédesebb megoldást építesz, inkább nagyobb oldalméretet használj több kérés helyett, és az eseményindítókat se sűrítsd percenkéntire.