# Automatizálások

> Munkafolyamatok, statisztika, futások, aktiválás, szüneteltetés, feliratkozók hozzáadása.

Olvasáshoz Automatizálások: megtekintés, minden művelethez Automatizálások: kezelés jog kell.

## Mire képes az API

A munkafolyamatokat a felületen építed. Az API olvassa őket az indítóikkal és lépéseikkel együtt, visszaadja a számaikat, aktiválja és szünetelteti őket, és feliratkozókat tesz be vagy vesz ki.

| Metódus és útvonal | Mit csinál |
|---|---|
| `GET /automations` | Listázza a munkafolyamatokat. |
| `GET /automations/{id}` | Egy munkafolyamat az indítóival és lépéseivel. |
| `GET /automations/{id}/stats` | Számok levéllépésenként és A/B elágazásonként. |
| `GET /automations/{id}/runs` | A feliratkozók futásai. |
| `POST /automations/{id}/activate` | Aktivál az új feliratkozókra. |
| `POST /automations/{id}/pause` | Szüneteltet. |
| `POST /automations/{id}/subscribers` | Sorba állítja a feliratkozókat, hogy az elejéről belépjenek. |
| `DELETE /automations/{id}/subscribers/{subscriber_id}` | Megszakítja a feliratkozó aktív futását. |

## Munkafolyamatok listázása és lekérése

A `GET /automations` minden munkafolyamatot listáz a legutóbbi módosítással kezdve, indítók és lépések nélkül. Paraméterek: `status` (`draft`, `active`, `paused`), `search` (a név tartalmazza), `limit`, `cursor`.

```bash
curl -H "Authorization: Bearer $ECHO_TOKEN" "$ECHO_API/automations/477323d4-1ba3-4658-b70d-a7d94ceed56b"
```

```json
{"data":{"id":"477323d4-1ba3-4658-b70d-a7d94ceed56b","name":"Welcome email (EN)","status":"active","reenter":false,"created_at":"2026-05-05T06:00:00Z","updated_at":"2026-05-05T09:00:00Z","issues":[],"stats":{"active":0,"completed":660,"canceled":0,"failed":0},"triggers":[{"id":"t1","type":"joins_group","settings":{"exclude_groups":[],"groups":["5e30c6ff-0462-47d1-9a6c-7db4c33d6b9a"]}}],"steps":[{"id":"e1","type":"email","parent":null,"settings":{"from_email":"hirlevel@news.kertlak.example.com","from_name":"Kertlak Garden Shop","subject":"Welcome to Kertlak, {$name}"}}]}}
```

| Kulcs | Jelentés |
|---|---|
| `status` | `draft`, `active` vagy `paused`. |
| `reenter` | Beléphet-e újra a feliratkozó. |
| `issues` | Ami az aktiváláshoz még hiányzik: mindegyiknek van `code` értéke (például `no_trigger`, `no_steps`, `subject_required`, `sender_unverified`), és megnevezi az érintett `trigger` vagy `step` azonosítót. |
| `stats` | A futások állapot szerint: `active`, `completed`, `canceled`, `failed`. |
| `triggers` | Csak egyedi lekérésnél. `type`: `joins_group`, `clicks_link`, `updated_field`, `anniversary`, `exact_date`, `joins_segment`, a hozzá tartozó `settings` értékkel. |
| `steps` | Csak egyedi lekérésnél. `type`: `delay`, `condition`, `split`, `email`, `webhook`, `notify`, `move_to_step`, `update_field`, `copy_to_groups`, `move_to_groups`, `remove_from_groups`, `unsubscribe`. A `parent` az a lépés, ahonnan a futás érkezik (az elsőnél `null`), a `branch` feltétel után `yes` vagy `no`, A/B elágazás után `a`, `b` vagy `c`. |

A levéllépések a tárgyukat és a feladójukat mutatják, a tartalmukat soha. A webhook-lépések csak a cél eredetét mutatják. Egy később bevezetett lépéstípus csak az `id`, `type`, `parent` és `branch` kulcsot adja, ezért az ismeretlen típusokat hagyd figyelmen kívül.

## Statisztika

```bash
curl -H "Authorization: Bearer $ECHO_TOKEN" "$ECHO_API/automations/477323d4-1ba3-4658-b70d-a7d94ceed56b/stats"
```

```json
{"data":{"emails":{"e1":{"sent":660,"delivered":655,"opened":299,"clicked":76,"unsubscribed":2,"bounced":2,"complaints":1,"queued":0}},"paths":{}}}
```

Az `emails` kulcsai a levéllépések azonosítói, a `paths` kulcsai az A/B elágazások azonosítói, útvonalanként a futások számával.

## Futások

`GET /automations/{id}/runs`, a legutóbbi változással kezdve. Paraméterek: `status` (`active`, `completed`, `canceled`, `failed`), `search` (az e-mail-cím tartalmazza, Feliratkozók: megtekintés jog kell hozzá), `limit`, `cursor`. A `total` csak az első oldalon van.

```bash
curl -H "Authorization: Bearer $ECHO_TOKEN" "$ECHO_API/automations/477323d4-1ba3-4658-b70d-a7d94ceed56b/runs?limit=2"
```

```json
{"data":[{"id":"dc47e464-5a95-46b4-87e7-10fd672bbd26","subscriber":{"id":"92af241b-ab4a-442c-a087-30236d57ce62","email":"felix.harris@example.org"},"status":"completed","source":"trigger","current_step":"e1","started_at":"2026-10-21T16:51:00.565674Z","finished_at":"2026-10-21T16:51:07.565674Z"},{"id":"10146ae9-3c5c-41ff-9167-8e172e1690f2","subscriber":{"id":"622089f1-ac52-42dc-9cf6-4b7ec9f616d8","email":"becker.samuel@example.com"},"status":"completed","source":"trigger","current_step":"e1","started_at":"2026-10-21T15:00:46.009312Z","finished_at":"2026-10-21T15:00:50.009312Z"}],"meta":{"next_cursor":"ATFli9bJvH7vKdoiO_bfuDPeXu6Ewb_n7VatGLvGHqYhgF6cXmaxAQGUfTzVplQTbrQ0ytcGl-4Z2Yynkn28Z3cxcMQE","prev_cursor":null,"limit":2,"total":660}}
```

A `source` megmutatja, hogyan indult a futás: `trigger`, `manual`, `activation`, `readd` vagy `auto_readd`.

## Aktiválás és szüneteltetés

A `POST /automations/{id}/activate` (törzs nélkül) a munkafolyamatot **csak az új feliratkozókra** aktiválja; a meglévő feliratkozókra aktiválni a felületen lehet. Az aktív munkafolyamat változatlan marad, a válasz maga a munkafolyamat. A nem kész munkafolyamat `422 validation` választ ad, a `fields` megnevezi a helyet: `automation`, `trigger.<id>` vagy `step.<id>`.

```bash
curl -X POST "$ECHO_API/automations/477323d4-1ba3-4658-b70d-a7d94ceed56b/activate" -H "Authorization: Bearer $ECHO_TOKEN"
```

`200 OK` a munkafolyamattal (ugyanaz a forma, mint a `GET /automations/{id}` válasza).

A `POST /automations/{id}/pause` (törzs nélkül) szünetelteti az aktív munkafolyamatot. A szüneteltetett változatlan marad, a piszkozat `409 not_active`. A 7 napnál tovább szüneteltetett munkafolyamat futásai sikertelenek lesznek.

```bash
curl -X POST "$ECHO_API/automations/4a640568-5407-49d3-920a-237d5a1927f6/pause" -H "Authorization: Bearer $ECHO_TOKEN"
```

```json
{"data":{"id":"4a640568-5407-49d3-920a-237d5a1927f6","name":"Visszacsábító sorozat","status":"paused","reenter":false,"created_at":"2026-08-31T06:00:00Z","updated_at":"2026-10-05T13:20:00Z","issues":[],"stats":{"active":0,"completed":150,"canceled":0,"failed":0},"triggers":[{"id":"t1","type":"joins_segment","settings":{"segment":"056e2b2a-9214-48e6-b8cf-fa001d8893d4"}}],"steps":[{"id":"e1","type":"email","parent":null,"settings":{"from_email":"hirlevel@news.kertlak.example.com","from_name":"Kertlak Webshop","subject":"Hiányzol nekünk, {$name}"}},{"id":"d1","type":"delay","parent":"e1","settings":{"amount":7,"date":"","field":"","mode":"for","month_day":0,"past":"","past_target":"","time":"","unit":"days","until":"","weekdays":[],"zone":""}},{"id":"e2","type":"email","parent":"d1","settings":{"from_email":"hirlevel@news.kertlak.example.com","from_name":"Kertlak Webshop","subject":"Maradjunk kapcsolatban?"}}]}}
```

## Feliratkozók hozzáadása egy munkafolyamathoz

A `POST /automations/{id}/subscribers` 1-100 feliratkozót (azonosító szerint) állít sorba, hogy egy **aktív** munkafolyamatba az elejétől belépjenek.

```bash
curl -X POST "$ECHO_API/automations/{id}/subscribers" \
  -H "Authorization: Bearer $ECHO_TOKEN" -H "Content-Type: application/json" \
  -d '{"subscribers":["d5f0b4b1-b59d-40eb-b2e0-74857893a055"]}'
```

Aktív munkafolyamatnál a válasz `200 OK` a `data.queued` (a sorba állított aktív feliratkozók száma) és a `data.not_added` (az ismeretlen, nem aktív vagy épp módosítás alatt álló azonosítók) kulccsal. Aki már a munkafolyamatban van, vagy 24 órán belül lépett ki belőle, azt a sor feldolgozása kihagyja. A belépés valóban elküldi a munkafolyamat leveleit.

Ugyanez a kérés a fenti, szüneteltetett munkafolyamatra `409` választ ad:

```json
{"error":{"code":"not_active","message":"The workflow is not active."}}
```

## Feliratkozó kivétele egy munkafolyamatból

A `DELETE /automations/{id}/subscribers/{subscriber_id}` megszakítja a feliratkozó aktív futását: `204 No Content`. Aktív futás nélkül a válasz `404 not_found`.