# Airtable integracija

> Paruoštas receptas: susitikimų protokolai ir užduotys automatiškai keliauja į jūsų Airtable bazę per įvykių srautą.

Šaltinis: https://diko.app/api-docs/airtable

Per maždaug 10 minučių sujungsite Diko su Airtable: kiekvienas paruoštas susitikimas taps eilute lentelėje **Susitikimai** (pavadinimas, data, trukmė, santrauka, sprendimai, nuoroda į Diko), o kiekviena užduotis iš protokolo – eilute lentelėje **Užduotys**, susieta su savo susitikimu. Toliau jas galite rūšiuoti, filtruoti, rodyti Kanban lentoje ar sieti su kitais procesais.

Receptas naudoja Airtable automatizaciją su veiksmu **Run a script** ir mūsų paruoštą skriptą [`diko-airtable-sync.js`](https://diko.app/examples/diko-airtable-sync.js). Jums nereikia jokio serverio.

> **Pastaba:**
> Diko turi ir integruotą Airtable jungtį (Integracijos), kuri protokolą išsiunčia be kodo. Šis receptas skirtas API klientams, kurie nori patys valdyti bazės struktūrą. Užduotys tampa atskiromis eilutėmis. Duomenys sinchronizuojami ir po pakeitimų Diko.

## Kaip tai veikia

1. Airtable automatizacija kas 15 minučių paleidžia skriptą.
2. Skriptas skaito naujus įvykius iš [`GET /events`](https://diko.app/api-docs/zinynas/list-events.md) nuo ten, kur sustojo praėjusį kartą. Vietą (žymeklį, angl. *cursor*) jis laiko lentelėje **Diko nustatymai**.
3. Gavęs `meeting.ready`, `meeting.minutes.updated` arba `meeting.updated`, skriptas nuskaito dabartinę susitikimo būseną ([`GET /meetings/{meeting_id}`](https://diko.app/api-docs/zinynas/get-meeting.md), [`/minutes`](https://diko.app/api-docs/zinynas/get-meeting-minutes.md), [`/action-items`](https://diko.app/api-docs/zinynas/list-meeting-action-items.md)) ir atnaujina eilutes. Kelis to paties susitikimo įvykius jis sujungia į vieną nuskaitymą.
4. `meeting.deleted` eilutės neištrina: pažymi langelį **Ištrintas**, o susitikimo užduotims pažymi **Pašalinta**.
5. Žymeklis pasistumia tik tada, kai visas įvykių puslapis įrašytas į Airtable. Eilutės randamos pagal **Diko ID**, todėl pakartotinis paleidimas nesukuria dublikatų.

Kodėl ne webhook? Airtable paleidiklis **When webhook received** negali patikrinti Diko [webhook parašo](https://diko.app/api-docs/webhooks.md#para%C5%A1o-tikrinimas), todėl bet kas, sužinojęs adresą, galėtų įrašyti netikrų duomenų. Įvykių srauto skaitymas su raktu yra saugesnis ir nieko nepraranda: įvykiai saugomi 30 dienų. Diko užfiksuoja įvykius tik nuo tada, kai paskyra turi neatšauktą raktą arba įjungtą webhook endpointą. Anksčiau pasibaigę susitikimai į srautą nepatenka.

## 1. Paruoškite bazę

Sukurkite bazę (arba naudokite esamą) su trimis lentelėmis. Pavadinimai turi sutapti tiksliai; jei norite kitų, pakeiskite juos skripto `CONFIG` bloke.

**Susitikimai**

| Laukas | Tipas |
|---|---|
| `Pavadinimas` | Single line text (pirminis laukas) |
| `Diko ID` | Single line text |
| `Data` | Date, su laiku |
| `Trukmė (min)` | Number, 1 skaitmuo po kablelio |
| `Santrauka` | Long text |
| `Sprendimai` | Long text |
| `Nuoroda` | URL |
| `Faktų patikra` | Single line text arba Single select su `Patikrinta`, `Pataisyta`, `Nepatikrinta` |
| `Archyvuotas` | Checkbox |
| `Ištrintas` | Checkbox |

**Užduotys**

| Laukas | Tipas |
|---|---|
| `Užduotis` | Single line text (pirminis laukas) |
| `Diko ID` | Single line text |
| `Susitikimas` | Link to another record → `Susitikimai` |
| `Atsakingas` | Single line text |
| `Terminas` | Single line text |
| `Būsena` | Single select su `Atvira`, `Vykdoma`, `Atlikta`, `Atšaukta` (arba Single line text) |
| `Šaltinis` | Single line text |
| `Pašalinta` | Checkbox |

**Diko nustatymai**

| Laukas | Tipas |
|---|---|
| `Pavadinimas` | Single line text (pirminis laukas) |
| `Žymeklis` | Single line text |
| `Paskutinis paleidimas` | Single line text |

Lentelę **Diko nustatymai** palikite tuščią: pirmas paleidimas pats sukurs vieną eilutę. Laukas `Terminas` yra tekstas, nes protokole terminas dažnai būna žodinis („iki penktadienio“). Rankinių užduočių datą skriptas įrašo `YYYY-MM-DD` formatu.

> **Patarimas:**
> Skriptas prieš rašydamas patikrina, ar visi laukai yra. Jei ko nors trūksta, automatizacijos istorijoje matysite, kurio lauko ar pasirinkimo reikia.

## 2. Sukurkite API raktą

1. Atidarykite **Nustatymai → API** ([`/settings/api`](https://studio.diko.app/settings/api)) ir pasirinkite **Sukurti raktą**. Reikia „Verslas“ plano.
2. Pažymėkite tik leidimą **Susitikimai – skaityti** (`meetings:read`). Šiam receptui daugiau nieko nereikia: raktas negalės nei importuoti, nei skaityti bibliotekos (žr. [Leidimai](https://diko.app/api-docs/leidimai.md)).
3. Pavadinkite raktą, pavyzdžiui, `Airtable – pardavimų bazė`, ir pasirinkite galiojimą (pagal numatymą 90 dienų).
4. Nukopijuokite raktą. **Jis rodomas tik vieną kartą.**

## 3. Sukurkite automatizaciją

1. Airtable bazėje atidarykite **Automations** → **Create automation**.
2. Paleidiklis: **At scheduled time**, intervalas, pavyzdžiui, kas 15 minučių.
3. Veiksmas: **Run a script**.
4. Atsisiųskite [`diko-airtable-sync.js`](https://diko.app/examples/diko-airtable-sync.js) ir įklijuokite visą jo turinį į skripto redaktorių.
5. Kairėje pusėje, skiltyje **Secrets**, pridėkite paslaptį pavadinimu `DIKO_API_KEY` ir įklijuokite raktą. Skriptas ją skaito per `input.secret('DIKO_API_KEY')`.
6. Įjunkite automatizaciją.

> **Įspėjimas:**
> Niekada neįrašykite rakto tiesiai į skriptą. Skripto kodą mato kiekvienas bazės redaktorius, o paslapties reikšmės – ne. Airtable leidžia redaguoti skriptą su paslaptimis tik tiems, kas gali pasiekti tas paslaptis.

Pirmas paleidimas pagal numatymą pradeda nuo seniausio dar saugomo įvykio (iki 30 dienų atgal). Tai apima susitikimus, pasibaigusius po to, kai paskyra pirmą kartą turėjo neatšauktą raktą ar įjungtą webhook endpointą, bet ne senesnius: jiems Diko įvykių neužfiksavo. Jei norite tik naujų susitikimų, `CONFIG` bloke nustatykite `startFrom: 'latest'`.

## 4. Išbandykite

1. Skripto redaktoriuje paspauskite **Test** (arba **Run test**).
2. Rezultate rasite santrauką `summary`, pavyzdžiui, kiek susitikimų ir užduočių sukurta (`meetingsCreated`, `tasksCreated`) ir kodėl sustota (`stopReason`).
3. Patikrinkite lenteles: **Susitikimai** turi būti po eilutę kiekvienam susitikimui, **Užduotys** – susietos su juo, o **Diko nustatymai** – su užpildytu `Žymeklis`.
4. Paleiskite testą dar kartą. Naujų eilučių neturi atsirasti: tai įrodo, kad pakartotinis paleidimas saugus.

Vienas paleidimas apdoroja apie 10–15 susitikimų, nes Airtable leidžia skriptui daugiausia 50 `fetch` užklausų, o vienam susitikimui reikia trijų. Jei įvykių daugiau, `stopReason` bus `budget reached`. Kitas paleidimas tęs nuo ten, kur sustota.

## Ką skriptas daro su duomenimis

- **Susitikimas** atnaujinamas kiekvieną kartą, kai Diko praneša apie pakeitimą. Santrauka, sprendimai ir faktų patikra rašomi tik tada, kai protokolas paruoštas.
- **Rankinės užduotys** (sukurtos Diko) turi savo `act_...` ID, o jų būsena sinchronizuojama iš Diko.
- **Protokolo užduotys** neturi ID, todėl skriptas joms sudaro raktą iš susitikimo ID ir užduoties teksto. Jų būsena nustatoma tik sukuriant eilutę (Diko ją visada rodo kaip `open`). Toliau ją galite keisti Airtable.
- Kai protokolas sugeneruojamas iš naujo ir užduotis jame nebelieka, eilutė gauna žymą **Pašalinta**. Ji neištrinama.
- Laukus, kurių skriptas nerašo, galite laisvai pridėti: jūsų komentarai, prioritetai ar formulės liks nepaliesti.

## Alternatyva su webhook (mažiau saugi)

Galite naudoti paleidiklį **When webhook received** ir Diko [webhook](https://diko.app/api-docs/webhooks.md) endpointą, nukreiptą į Airtable adresą. Tačiau Airtable neleidžia patikrinti parašo `webhook-signature`, todėl kiekvienas, gavęs adresą, galėtų siųsti netikrus įvykius. Jei vis tiek renkatės šį kelią, webhook turinį naudokite tik kaip signalą. Neperimkite duomenų iš jo. Susitikimą visada nuskaitykite per API su raktu ir saugokite adresą kaip paslaptį.

## Trikčių šalinimas

| Požymis | Priežastis ir sprendimas |
|---|---|
| `Diko rejected the API key (invalid_api_key)` arba `api_key_expired`, `api_key_revoked` | Raktas neteisingas, pasibaigęs arba atšauktas (401). Sukurkite naują raktą ir pakeiskite paslaptį `DIKO_API_KEY`. |
| `Diko denied access (insufficient_scope)` arba `plan_required` | Raktui trūksta `meetings:read` arba paskyra neturi „Verslas“ plano (403). Žr. [Klaidos](https://diko.app/api-docs/klaidos.md). |
| `stopReason: rate limited ...` | API grąžino 429. Skriptas laukia `Retry-After` ir bando dar kartą; jei laukti per ilgai, sustoja ir tęsia kitą kartą. Nepaleiskite kelių automatizacijų su tuo pačiu raktu vienu metu: API leidžia 2 lygiagrečias užklausas paskyrai, o komandos plane visa komanda dalijasi 3 (žr. [Ribos](https://diko.app/api-docs/ribos.md)). |
| `Table "..." is missing fields` arba `Add these options to ...` | Laukų pavadinimai ar pasirinkimai nesutampa. Pataisykite bazę arba `CONFIG`. |
| Paleidimas sėkmingas, bet eilučių nėra | Per paskutines 30 dienų arba nuo pirmo paskyros rakto ar endpointo nebuvo paruoštų susitikimų, raktas priklauso kitai paskyrai arba nustatyta `startFrom: 'latest'`. Patikrinkite raktą su [`GET /me`](https://diko.app/api-docs/zinynas/get-me.md) ir paruoškite naują susitikimą. |
| `The stored cursor is no longer valid` | Žymeklis per senas ar sugadintas (400 `invalid_cursor`). Išvalykite lauką `Žymeklis` ir paleiskite iš naujo. |

**Kaip pradėti iš naujo.** Išvalykite lauką `Žymeklis` lentelėje **Diko nustatymai**. Kitas paleidimas vėl perskaitys paskutinių 30 dienų įvykius ir atnaujins esamas eilutes, nekurdamas dublikatų.

## Saugumas

- **Mažiausi leidimai:** raktas tik su `meetings:read`, skirtas tik šiai integracijai. Atšaukus jį nepaliečiamos kitos sistemos.
- **Paslaptis, ne kodas:** raktas laikomas tik Airtable paslaptyje. Airtable paslaptis slepia ir `console.log` išvestyje, o skriptas rakto niekur nerašo.
- **Galiojimas ir rotacija:** pasirinkite ribotą galiojimą. Diko primena el. laišku likus 7 ir 1 dienai; tada [rotuokite raktą](https://diko.app/api-docs/saugumas.md#rakto-rotacijos-receptas) ir atnaujinkite paslaptį.
- **Bazės prieiga:** protokoluose gali būti jautrios informacijos, todėl bazę bendrinkite tik su tais, kas mato tuos susitikimus Diko.
- Įtariate nutekėjimą? Iškart atšaukite raktą skiltyje **Nustatymai → API** ([`/settings/api`](https://studio.diko.app/settings/api); žr. [Saugumo gaires](https://diko.app/api-docs/saugumas.md)).