# Gyors kezdés

> Base URL, első kérés, kérés- és válaszformátum, lapozás, idempotencia.

## Base URL

```
https://echo.uptools.io/public/v1
```

Ugyanezt a címet mutatja a felületen az **Integrációk** menü **API** oldala a **Base URL** mellett. A példák két shell-változót használnak:

```bash
export ECHO_API=https://echo.uptools.io/public/v1
export ECHO_TOKEN=upm_...   # az API-tokened, lásd Hitelesítés
```

## Az első kérés

Hozz létre egy tokent az **Integrációk**, **API**, **Új token létrehozása** úton ([Hitelesítés](https://docs.uptools.io/hu/echo/developer-guide/authentication/)), majd kérdezd le, hány aktív feliratkozód van:

```bash
curl -H "Authorization: Bearer $ECHO_TOKEN" "$ECHO_API/subscribers/count"
```

```http
HTTP/1.1 200 OK
Content-Type: application/json
X-Ratelimit-Limit: 120
X-Ratelimit-Remaining: 119

{"data":{"total":4712}}
```

Egy feliratkozó felvétele (Teljes hozzáférés szintű token kell hozzá):

```bash
curl -X POST "$ECHO_API/subscribers" \
  -H "Authorization: Bearer $ECHO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"email":"lilla.farkas@example.com","fields":{"name":"Lilla","city":"Szeged"}}'
```

A válasz `201 Created` az új feliratkozóval, vagy `200 OK`, ha a cím már szerepelt a listán. A részletek a [Feliratkozók](https://docs.uptools.io/hu/echo/developer-guide/subscribers/) oldalon vannak.

## A kérések formátuma

- Minden kéréshez kell az `Authorization: Bearer <token>` fejléc.
- A kérés törzse csak JSON lehet: küldd a `Content-Type: application/json` fejlécet. Másra `415 unsupported_media_type` a válasz.
- A törzs egyetlen JSON-objektum legyen. A hibás JSON vagy bármi más, ami nem egyetlen objektum, `400 invalid_json` választ kap. Az ismeretlen kulcsokat az API `422 validation` hibával elutasítja (a kulcsot a `fields` megnevezi), így egy elírás sem marad észrevétlen.
- A törzs legfeljebb 1 MB lehet, importnál legfeljebb 10 MB.
- Az `Accept-Language: en` vagy `hu` fejléc dönti el a hibaüzenetek nyelvét. Az adatokat (mezőnevek, csoportnevek) az API nem fordítja. Az útmutató példái `Accept-Language: en` fejléccel futottak.
- A szögletes zárójeles paraméterekhez, mint a `filter[status]`, a curl `-g` kapcsolója kell (vagy URL-kódolás: `filter%5Bstatus%5D`), különben a curl mintának olvassa a zárójeleket.
- Az azonosítók UUID-k. Az API válaszaiban minden időpont UTC szerinti, `Z` végű RFC 3339 időbélyeg (például `2026-10-22T08:52:08.527488Z`). A webhookok üzeneteiben eltolással megadott időpont is lehet ([Webhookok](https://docs.uptools.io/hu/echo/developer-guide/webhooks/#az-események-tartalma)), ezért az időpontokat RFC 3339 szerint dolgozd fel.
- A JSON-szövegekben a HTML `<` és `>` jele `\u003c` és `\u003e` formában érkezik. Bármelyik JSON-feldolgozó visszaalakítja őket.

## A válaszok formátuma

Egy objektum a `data` kulcsban érkezik:

```json
{"data":{"id":"257e83a2-d55e-4a8c-b9a4-b3e939c151cc","name":"Webshop vásárlók","created_at":"2026-10-22T08:52:08.269421Z","subscribers":0,"total":0,"open_rate":0,"click_rate":0}}
```

Egy lista a `data` kulcsban, a lapozás adatai a `meta` kulcsban:

```json
{"data":[...],"meta":{"next_cursor":"bzoz","prev_cursor":null,"limit":3,"total":7}}
```

A sikeres törlés és a tartalom nélküli művelet `204 No Content` választ ad, üres törzzsel. A hibáknak saját formátumuk van, lásd [Hibák és korlátok](https://docs.uptools.io/hu/echo/developer-guide/errors-and-limits/).

## Lapozás

A listák a `limit` paramétert fogadják (1 és 100 között, alapból 25), a kurzorokat a `meta` adja vissza:

| Kulcs | Jelentés |
|---|---|
| `next_cursor` | Ezt add át `cursor` paraméterként a következő oldalhoz. Az utolsó oldalon `null`. |
| `prev_cursor` | Ezt add át `cursor` paraméterként az előző oldalhoz. Az első oldalon `null`. |
| `limit` | A használt oldalméret. |
| `total` | A találatok száma, ha olcsó volt megszámolni. Hiányozhat. |

A kurzorok átlátszatlan szövegek: változtatás nélkül add vissza őket, mindig a `cursor` paraméterben, akármerre lapozol. Két lista csak előre lapoz: egy feliratkozó tevékenysége és egy munkafolyamat futásai. Ezeknél a `prev_cursor` mindig `null`.

A feliratkozólisták a `prev_cursor` értékét a régebbi `before` paraméterben is elfogadják, de ez elavult: használd a `cursor` paramétert.

Példa, a csoportok első, majd második oldala:

```bash
curl -g -H "Authorization: Bearer $ECHO_TOKEN" "$ECHO_API/groups?limit=3"
curl -g -H "Authorization: Bearer $ECHO_TOKEN" "$ECHO_API/groups?limit=3&cursor=bzoz"
```

```json
{"data":[{"id":"26e38149-d391-4215-86e4-92bb883e5910","name":"Új regisztrálók","created_at":"2026-09-20T14:45:00Z","subscribers":427,"total":451,"open_rate":37.55,"click_rate":7.72,"timed_out":false},{"id":"000d6529-0078-40d8-9c29-05cd541c4c2d","name":"VIP vásárlók","created_at":"2026-04-17T12:00:00Z","subscribers":466,"total":495,"open_rate":34.64,"click_rate":7.47,"timed_out":false},{"id":"19e19d19-d3df-4763-965c-d2f4d974e40a","name":"Webinar 2026","created_at":"2026-07-28T09:00:00Z","subscribers":413,"total":438,"open_rate":34.68,"click_rate":8.32,"timed_out":false}],"meta":{"next_cursor":"bzo2","prev_cursor":"bzow","limit":3,"total":7}}
```

A feliratkozólisták kurzorai titkosítva érkeznek, és idővel érvényüket veszthetik. Ilyenkor egy régi kurzor `422` választ ad `fields.cursor` hibával: kezdd újra az első oldaltól. A kurzorokat ne tárold sokáig.

Az 1 és 100 közé nem eső `limit` vagy a hibás kurzor `422 validation` hibát ad:

```json
{"error":{"code":"validation","message":"Please check the highlighted fields.","fields":{"limit":"Invalid value."}}}
```

## Idempotencia és újrapróbálás

Az API nem ismer idempotenciakulcs-fejlécet. Az újrapróbálást végpontonként tervezd meg:

| Kérés | Biztonságosan ismételhető? |
|---|---|
| `GET` kérések | Igen. |
| `POST /subscribers` | Igen: e-mail-cím alapján vesz fel vagy frissít, az ismétlés ugyanazt a feliratkozót frissíti. |
| `PUT` módosítások (feliratkozó, csoport- vagy szegmensnév, mezőnév, webhook) | Igen: ugyanaz a törzs ugyanazt az eredményt adja. |
| `POST /subscribers/{id}/groups/{group_id}` | Igen: a meglévő tagság nem változik. |
| `DELETE` | Az első `204` választ ad, az ismétlés `404 not_found` választ. Időtúllépés után a `404` azt jelenti, hogy a törlés megtörtént. |
| `POST /groups/{id}/import-subscribers` | Az ismétlés egy második importot indít. Az import a meglévő címeket frissíti, így a feliratkozók nem duplázódnak, de újraküldés előtt nézd meg az első import állapotát. |
| `POST /campaigns`, `POST /webhooks`, `POST /groups`, `POST /fields` | Nem: az ismétlés második kampányt vagy webhookot hoz létre. Azonos nevű második csoportot vagy mezőt az API elutasít (`409 name_taken`). |
| `POST /campaigns/{id}/test` | Nem: minden hívás tesztleveleket küld. |

`429` vagy válasz előtti hálózati hiba után a kérés a `Retry-After` idő elteltével újraküldhető. A [kötegelt kérések](https://docs.uptools.io/hu/echo/developer-guide/batch-requests/) nem atomiak: hiba esetén nézd meg egyenként a válaszokat, mielőtt újraküldöd a köteget.