# Importálás API-val

> Tömeges import egy csoportba és az állapota.

Egyszerre néhány feliratkozóhoz (feliratkozás, vásárlás) a [`POST /subscribers`](https://docs.uptools.io/hu/echo/developer-guide/subscribers/#feliratkozó-felvétele-vagy-frissítése) való. Egy egész listához a tömeges import: a háttérben fut, pontosan úgy, mint a felületen a fájlimport, és megjelenik a **Feliratkozók** menü **Előzmények** fülén.

## Az import indítása

A `POST /groups/{id}/import-subscribers` 1-50 000 feliratkozót importál egy csoportba. Feliratkozók: kezelés jog kell hozzá.

| Kulcs | Jelentés |
|---|---|
| `subscribers` | A sorok. Minden sor egy objektum `email` (kötelező) és `fields` (értékek mezőkulcs szerint) kulccsal. Más kulcs nem lehet benne. |

```bash
curl -X POST "$ECHO_API/groups/257e83a2-d55e-4a8c-b9a4-b3e939c151cc/import-subscribers" \
  -H "Authorization: Bearer $ECHO_TOKEN" -H "Content-Type: application/json" \
  -d '{"subscribers":[
        {"email":"bence.kovacs@example.com","fields":{"name":"Bence","city":"Győr"}},
        {"email":"reka.toth@example.org","fields":{"name":"Réka","rendelesek_szama":5}},
        {"email":"hibas-cim"}
      ]}'
```

```http
HTTP/1.1 202 Accepted
Content-Type: application/json
X-Ratelimit-Limit: 5
X-Ratelimit-Remaining: 4

{"data":{"import_id":"df745729-be25-495c-a5b1-8a070dbd18cb"}}
```

Ennek a válasznak a sebességkorlát-fejlécei az importkeretet mutatják (percenként 5), lásd [Hibák és korlátok](https://docs.uptools.io/hu/echo/developer-guide/errors-and-limits/#sebességkorlát).

Bármelyik sorban használt mezőkulcsnak léteznie kell a munkaterületen, különben semmi sem importálódik:

```json
{"error":{"code":"validation","message":"Please check the highlighted fields.","fields":{"fields.kedvenc_szin":"Unknown field."}}}
```

Ismeretlen csoportra a válasz `404 not_found`; üres listára vagy 50 000-nél több sorra `422` a `fields.subscribers` kulccsal.

## Az import követése

A `GET /subscribers/import/{import_id}` (Feliratkozók: megtekintés) mutatja az import haladását és eredményét. Kérdezd le néhány másodpercenként, amíg a `status` értéke `done`, `failed` vagy `canceled` nem lesz.

```bash
curl -H "Authorization: Bearer $ECHO_TOKEN" "$ECHO_API/subscribers/import/df745729-be25-495c-a5b1-8a070dbd18cb"
```

```json
{"data":{"id":"df745729-be25-495c-a5b1-8a070dbd18cb","kind":"csv","status":"done","filename":"api-import.csv","size_bytes":115,"encoding":"utf-8","delimiter":",","has_header":true,"preview":{"headers":[],"rows":[],"columns":0},"mapping":["email","city","name","rendelesek_szama"],"groups":[{"id":"257e83a2-d55e-4a8c-b9a4-b3e939c151cc","name":"Webshop vásárlók"}],"start_automations":false,"processed_rows":3,"added":2,"updated":0,"failed":1,"error":"","created_at":"2026-10-22T08:52:08.576581Z","started_at":"2026-10-22T08:52:08.759366Z","finished_at":"2026-10-22T08:52:08.810755Z","failed_rows":[{"row":3,"email":"hibas-cim","reason":"invalid_email","detail":""}]}}
```

| Kulcs | Jelentés |
|---|---|
| `status` | `queued` (egy korábbi importra vár), `processing`, `done`, `failed` vagy `canceled`. |
| `processed_rows` | Az eddig feldolgozott sorok. |
| `added`, `updated`, `failed` | Új feliratkozók, frissített feliratkozók, kimaradt sorok. |
| `error` | `parse_error` vagy `internal`, ha az egész import meghiúsult, egyébként üres. |
| `mapping` | Az oszlopok: `email`, aztán a használt mezőkulcsok (ábécérendben). |
| `start_automations` | API-s importnál mindig `false`. |
| `failed_rows` | Az első 100 kimaradt sor: `row` (a sor helye a `subscribers` tömbben, 1-től), `email` úgy, ahogy elküldted (üres, ha hiányzott), `reason` és `detail` (a mező, ha egy értéket utasított el). |

Az API-s import egy `api-import.csv` nevű CSV-ként tárolódik, ezért a `kind`, a `filename`, az `encoding`, a `delimiter` és a `has_header` ezt a fájlt írja le. A `failed` minden kimaradt sort megszámol, a `failed_rows` az első 100-at sorolja fel. A `reason` értéke `missing_email`, `invalid_email`, `duplicate`, `role_address`, `short_gmail`, `suppressed`, `invalid_number`, `invalid_date`, `value_too_long` vagy `invalid_text`. Ugyanezeket a sorokat a felületen az import eredményoldala is mutatja (**Előzmények** fül, **Megtekintés**).

## Hogyan kezeli a sorokat

- Az új címek `import` forrású, `active` feliratkozók lesznek a csoportban. Az importált feliratkozók nem kapnak megerősítő levelet, ezért csak olyanokat importálj, akik hozzájárultak a leveleidhez.
- A meglévő címek frissülnek, és bekerülnek a csoportba; az állapotuk nem változik, a leiratkozott leiratkozott marad.
- Az üres érték nem törli a tárolt értéket.
- A sorok ugyanazokból az okokból maradnak ki, mint a felületen: érvénytelen vagy hiányzó cím, szerepkör-cím, tiltólistán lévő cím, a listában kétszer szereplő cím, vagy a mező típusához nem illő érték (szám mezőbe szám, dátumhoz `YYYY-MM-DD`).
- Az import nem indít automatizálást.
- Egy munkaterületen egyszerre egy import fut, a második `queued` állapotban vár.
- Amikor az import végez, a munkaterület értesítési csengője jelzi; API-s importról e-mail-értesítés nem megy.

## Korlátok

| Korlát | Érték |
|---|---|
| Sorok egy kérésben | 1-50 000 |
| A kérés törzse | 10 MB (fölötte `413 too_large`) |
| Import tokenenként | Percenként 5, a percenkénti 120 kérésen felül |