# MainWP Abilities

> A Matomo-kapcsolat, a hozzárendelések és az adatfrissítések kezelése a MainWP Abilities API-n keresztül: képességek, kérések és hibakódok.

A bővítmény tizenkét képességet (ability) regisztrál a `mainwp-matomo` kategóriában, mindegyik a `mainwp/` névtérben a MainWP Dashboardon. Segítségükkel kapcsolati állapotot olvashatsz, tulajdonokat listázhatsz, hozzárendeléseket nézhetsz meg és módosíthatsz, elemzési pillanatképeket és trendeket olvashatsz, valamint háttérfrissítést kérhetsz, ellenőrizhetsz vagy leállíthatsz. A frissítési kéréseket a WordPress ütemezett feladatai dolgozzák fel. Az elfogadott kérés csak annyit jelent, hogy sorba került, a végrehajtást az operáció állapotából ellenőrizheted.

## Követelmények

- WordPress 6.9 vagy újabb, és Abilities API-t támogató MainWP Dashboard (a lenti `input_json` példákhoz MainWP Dashboard 6.2 vagy újabb).
- Aktív Matomo-bővítmény a MainWP Dashboardon.
- Hitelesített felhasználó `manage_options` joggal és hozzáféréssel a Matomo-kiegészítőhöz.
- Webhelyspecifikus hívásokhoz hozzáférési és szerkesztési jog a webhelyhez, és csatlakoztatott MainWP-webhely.
- Működő WordPress ütemezettfeladat-futtató a frissítési kérésekhez.
- Frissítés után egy rendszergazdának meg kell nyitnia a `wp-admin` felületet, hogy lefusson az átállás (lásd: [Frissítés, törlés és eltávolítás](https://hub.hellowp.io/hu/plugins/mainwp-piwik-extension/frissites-es-torles/)).

A hitelesítéshez használhatsz alkalmazásjelszót (Application Password) vagy a MainWP Abilities API többi hitelesítési módját. A példák alkalmazásjelszót használnak. A Team Control korlátozásai az olvasásra és az írásra is vonatkoznak. A webhelyspecifikus olvasáshoz a kiválasztott webhely szerkesztési joga is kell. Az operáció állapotát és a leállítást csak az a felhasználó éri el, aki kérte. A jelentések külön olvasási útja (lásd: [Webhelyek, adatok és jelentések](https://hub.hellowp.io/hu/plugins/mainwp-piwik-extension/webhelyek-es-adatok/)) ezekre a képességekre nem vonatkozik.

## A képességek

| Képesség | Módszer | Cél |
|---|---|---|
| `mainwp/get-matomo-connection-v1` | GET | A kapcsolat és az elemzési szabályzat kitakart olvasása |
| `mainwp/replace-matomo-connection-v1` | POST | A kapcsolat és a beállítások előnézete vagy cseréje |
| `mainwp/list-matomo-properties-v1` | GET | Tulajdonok listázása a gyorsítótárból |
| `mainwp/get-site-matomo-assignment-v1` | GET | Egy webhely hozzárendelésének és revíziójának olvasása |
| `mainwp/preview-site-matomo-assignment-v1` | GET | Hozzárendelés-módosítás előnézete, előnézeti token kérése |
| `mainwp/replace-site-matomo-assignment-v1` | POST | Az előnézett hozzárendelés alkalmazása vagy újraellenőrzése |
| `mainwp/get-site-matomo-observation-v1` | GET | A gyorsítótárazott aktuális és előző elemzési pillanatkép olvasása |
| `mainwp/get-site-matomo-trend-v1` | GET | Napi adatsor olvasása egy adott pillanatképből |
| `mainwp/request-matomo-property-refresh-v1` | POST | A tulajdonlista frissítésének sorba állítása |
| `mainwp/request-site-matomo-refresh-v1` | POST | Egy webhely elemzési adatainak frissítése egy időszakra |
| `mainwp/get-matomo-operation-v1` | GET | Saját frissítési operáció állapotának olvasása |
| `mainwp/cancel-matomo-operation-v1` | POST | Leállítás előnézete vagy kérése |

A teljes bemeneti és kimeneti sémát így kérheted le:

```bash
curl -u 'FELHASZNALO:ALKALMAZASJELSZO' \
  'https://a-dashboard-cimed.hu/wp-json/wp-abilities/v1/abilities?category=mainwp-matomo'
```

Az író képességek „destruktív” és „idempotens” jelölést kapnak. A bővítmény támogatja a JSON POST kéréseket (ahogy itt is látod), és a WordPress által a destruktív képességekhez választott natív DELETE módszert is. Mindkettő ugyanazt a `/run` végpontot és a `{"input":{...}}` JSON-törzset használja.

## Kérési szabályok

Minden bemenet elutasítja a felesleges tulajdonságokat. A `dry_run` és a `confirm` JSON logikai érték legyen.

| Mód | `dry_run` | `confirm` | Hatás |
|---|---|---|---|
| Előnézet | `true` | `false` vagy elhagyva | A kérést ellenőrzi, de nem menti a változtatást és nem állít sorba frissítést |
| Végrehajtás | `false` vagy elhagyva | `true` | Alkalmazza a változtatást vagy elfogadja a frissítési kérést |

Ha mindkét jelző `true`, a kérés érvénytelen. Ha mindkettőt elhagyod vagy mindkettő `false`, a válasz `mainwp_matomo_confirmation_required`.

- A webhelyet a `site_id_or_domain` mező adja meg, például `1`, `"1"` vagy `"example.com"`. Pontos MainWP-azonosító vagy domain kell. A számazonosító pozitív egész legyen: a nulla, a vezető nullák, a tizedes törtek és a szóközök érvénytelenek.
- Az `account_ref`, `catalog_ref`, `property_ref`, `snapshot_ref` és a revíziók átláthatatlan, 64 karakteres, kisbetűs hexadecimális értékek, amelyeket a képességek adnak vissza. Ne állítsd össze őket magad. A Matomo számazonosítója nem helyettesíti a `property_ref` értéket.
- Minden íráshoz UUID formátumú `request_ref` kell. Csak ugyanazon felhasználó azonos kérésének megismétlésekor használd újra, más kéréshez új UUID kell.
- A hozzárendelés előnézeti tokenjének és az `if_match` revíziónak ugyanarra a webhelyre és ugyanarra a javasolt tulajdonra kell vonatkoznia.

## Kapcsolat olvasása

Képesség: `mainwp/get-matomo-connection-v1`, módszer: GET, bemenet nincs.

```bash
curl -u 'FELHASZNALO:ALKALMAZASJELSZO' \
  'https://a-dashboard-cimed.hu/wp-json/wp-abilities/v1/abilities/mainwp/get-matomo-connection-v1/run'
```

| Válaszmező | Jelentés |
|---|---|
| `connection_state` | `missing`, `configured`, `invalid` vagy `migration_required` |
| `account_ref` | Az aktuális fiókgeneráció, vagy `null` |
| `origin_class` | `public_https`, `private_allowlisted` vagy `unset` |
| `range_days` | Az alapértelmezett, bezárólag számolt jelentési időszak, 1 és 366 nap között |
| `refresh_hours` | A frissítés időköze, 1 és 720 óra között |
| `revision` | Az aktuális kapcsolati revízió az `if_match` mezőhöz |

A válasz nem tartalmazza az URL-t és az API-tokent. A kapcsolat módosítása előtt olvasd el.

## Kapcsolat előnézete vagy cseréje

Képesség: `mainwp/replace-matomo-connection-v1`, módszer: POST.

| Bemenet | Kötelező | Jelentés |
|---|---|---|
| `origin_url` | igen | A Matomo abszolút HTTPS alap URL-je, almappával, ha van, például `https://analytics.example.com` vagy `https://example.com/matomo/` |
| `api_token` | igen | Új, csak írható token, vagy JSON `null` a mentett token megtartásához |
| `trust_profile` | igen | `public`, vagy `private_allowlisted` a kiszolgálói szabályzat által kifejezetten engedélyezett címhez |
| `timeout_seconds` | igen | 1 és 30 közötti egész |
| `range_days` | igen | 1 és 366 közötti egész |
| `refresh_hours` | igen | 1 és 720 közötti egész |
| `if_match` | igen | Az aktuális kapcsolati `revision` |
| `request_ref` | igen | A kérést azonosító UUID |
| `dry_run`, `confirm` | a kérési szabályok szerint | Előnézet vagy végrehajtás |

Az URL-re ugyanazok a szabályok vonatkoznak, mint a beállítóoldalon (lásd: [Kapcsolat beállítása](https://hub.hellowp.io/hu/plugins/mainwp-piwik-extension/kapcsolat/)). A tanúsítványellenőrzés mindig be van kapcsolva. A `private_allowlisted` előfeltétele egy már meglévő kiszolgálóoldali engedélylista, a kiválasztása önmagában nem ad hozzáférést privát célhoz.

Az `api_token: null` csak akkor használható, ha ugyanazt a kiszolgálót, portot, almappát és bizalmi profilt tartod meg, és van használható mentett token. Bármelyik módosításához token kell. Az azonos kiszolgáló másik almappája külön telepítés. A tokent a válasz sosem adja vissza.

Kezdd `dry_run: true` móddal. Az előnézet is felveszi a kapcsolatot a Matomóval, ezért elérhető kiszolgáló és érvényes token kell hozzá. A megerősített kérés előtt nézd meg a `changed`, `credential_action` (`retained` vagy `rotated`), `property_count` és `rebind_count` értékeket.

Az eredet, a token vagy a bizalmi profil módosítása új fiókgenerációt hoz létre: a meglévő hozzárendeléseket újra kell kötni, a régi helyi hozzárendelések és gyorsítótárazott adatok törlődnek, az előző fiók még el nem indított operációi leállnak. A `rebind_count` az érintett hozzárendelések számát adja.

A teljesült válasz a `mode`, `request_id`, `changed`, `credential_action`, `property_count`, `rebind_count` és az új `revision` mezőt tartalmazza. A megerősített híváshoz az előnézetnél használt aktuális revíziót add meg, az előnézet nem menti a javasolt revíziót.

## Tulajdonok listázása

Képesség: `mainwp/list-matomo-properties-v1`, módszer: GET.

```bash
curl -G -u 'FELHASZNALO:ALKALMAZASJELSZO' \
  --data-urlencode 'input_json={"limit":25}' \
  'https://a-dashboard-cimed.hu/wp-json/wp-abilities/v1/abilities/mainwp/list-matomo-properties-v1/run'
```

Választható bemenet a `limit` (1 és 100 között, alapérték 25) és az `after_property_ref` (egy korábban kapott kurzor vagy `null`). A válasz tartalmazza a `catalog_ref`, a `state` (`fresh` vagy `stale`), a `properties`, a `next_after_property_ref` és a `truncated` mezőt. Minden tulajdonnak van `property_ref`, `display_name` és `assignment_state` (`unassigned` vagy `assigned`) értéke. Ha a `truncated` értéke `true`, a `next_after_property_ref` értékkel folytasd. A képesség a teljes, gyorsítótárazott listát olvassa, a Matomóból nem kér le tulajdonokat, ahhoz a tulajdonlista-frissítést használd.

## Hozzárendelés olvasása, előnézete és cseréje

### Hozzárendelés olvasása

Képesség: `mainwp/get-site-matomo-assignment-v1`, módszer: GET.

```bash
curl -G -u 'FELHASZNALO:ALKALMAZASJELSZO' \
  --data-urlencode 'input_json={"site_id_or_domain":1}' \
  'https://a-dashboard-cimed.hu/wp-json/wp-abilities/v1/abilities/mainwp/get-site-matomo-assignment-v1/run'
```

A válasz: `site_id`, `assignment_state` (`unassigned`, `assigned` vagy `rebind_required`), `property_ref`, `property_name` és `revision`. A revíziót tartsd meg az előnézethez. A kapcsolat módosítása újrakötést tehet szükségessé akkor is, ha a webhelynek volt korábbi hozzárendelése.

### Javasolt hozzárendelés előnézete

Képesség: `mainwp/preview-site-matomo-assignment-v1`, módszer: GET. Kötelező bemenet: `site_id_or_domain`, `property_ref` és `if_match`. A `property_ref` értékét a gyorsítótárazott listából válaszd, vagy JSON `null` értékkel szüntesd meg a hozzárendelést. Az `if_match` a webhely aktuális hozzárendelési revíziója legyen.

A válasz: `site_id`, `desired_state`, `would_change`, `cache_effect` (`none` vagy `mark_stale`), `conflict_state` (`none` vagy `property_already_assigned`), `preview_token` és `expires_at`. Egy tulajdon csak egy MainWP-webhelyhez tartozhat, a `property_already_assigned` ütközést a módosítás előtt oldd fel. Az előnézeti token öt percig érvényes, és a kérő felhasználóhoz, a webhelyhez, a fiókhoz, a listához, a tulajdonhoz és a hozzárendelési revízióhoz kötött. Ha ezek bármelyike változik, olvasd el az aktuális állapotot, és kérj új előnézetet.

### Hozzárendelés cseréje

Képesség: `mainwp/replace-site-matomo-assignment-v1`, módszer: POST. Kötelező bemenet: `site_id_or_domain`, `property_ref`, `if_match`, `preview_token` és `request_ref`, valamint a kívánt módhoz tartozó jelzők. Pontosan az előnézet értékeit add meg. A próbafuttatás újraellenőrzi az előnézetet, a megerősített hívás menti a hozzárendelést, és ha az megváltozott, érvényteleníti a korábbi elemzési adatokat.

A válasz: `mode` (`preview` vagy `completed`), `request_id`, `site_id`, `assignment_state`, `changed` és az új `revision`. A hozzárendelés módosítása után kérj webhelyfrissítést, hogy az új tulajdon adatai betöltődjenek.

## Elemzési pillanatképek és trendek

### Pillanatkép olvasása

Képesség: `mainwp/get-site-matomo-observation-v1`, módszer: GET. Kötelező bemenet: `site_id_or_domain`. A választható `snapshot_ref` pontos pillanatképet jelöl ki, elhagyva vagy `null` értékkel az aktuális időszak legfrissebbjét kapod.

```bash
curl -G -u 'FELHASZNALO:ALKALMAZASJELSZO' \
  --data-urlencode 'input_json={"site_id_or_domain":1}' \
  'https://a-dashboard-cimed.hu/wp-json/wp-abilities/v1/abilities/mainwp/get-site-matomo-observation-v1/run'
```

A válasz: `site_id`, `snapshot_ref`, `state`, `start_date`, `end_date`, `observed_at`, `current` és `previous`. Mindkét időszak tartalmazza:

| Mező | Jelentés |
|---|---|
| `visits` | Látogatások száma |
| `unique_visitors` | Egyedi látogatók száma, vagy `null`, ha nem elérhető |
| `users` | Felhasználók száma, vagy `null`, ha nem elérhető |
| `actions` | Műveletek száma |
| `average_engagement_seconds` | Átlagos elköteleződési idő másodpercben |
| `bounce_rate` | Százalék 0 és 100 között |

A régi (stale) pillanatkép frissítésre szoruló, gyorsítótárazott adat. A hiányzó pillanatkép `mainwp_matomo_snapshot_not_found` hibát ad: előbb kérj webhelyfrissítést. Ezek az olvasások nem indítanak élő Matomo-kérést.

### Napi trend olvasása

Képesség: `mainwp/get-site-matomo-trend-v1`, módszer: GET. Kötelező bemenet: `site_id_or_domain`, a pillanatképből kapott `snapshot_ref` és a `metric`. A támogatott mutatók: `visits`, `unique_visitors`, `users` és `actions`. A válasz: `site_id`, `snapshot_ref`, `metric`, `timezone` és a napi `points`. Minden ponthoz tartozik `date` és `value`, a nem elérhető mutató értéke `null` lehet. Legfeljebb 366 pont jön. Ugyanazt a pillanatkép-hivatkozást használd, hogy az összegzés és a trend egyező legyen.

## Ütemezett frissítések kérése

A frissítési kérések azelőtt válaszolnak, hogy a szolgáltatói munka befejeződne. A tartós sort a WordPress ütemezett feladatai dolgozzák fel. Az aktuális Matomo-fiókhoz egyszerre csak egy frissítés lehet aktív, másik kérés `mainwp_matomo_lock_busy` hibát adhat.

### Tulajdonlista frissítése

Képesség: `mainwp/request-matomo-property-refresh-v1`, módszer: POST. Küldd a `request_ref` mezőt és a mód jelzőit. A megerősített kérés a teljes tulajdonlistát frissíti.

```bash
curl -X POST -u 'FELHASZNALO:ALKALMAZASJELSZO' \
  -H 'Content-Type: application/json' \
  -d '{"input":{"request_ref":"9e38a2d1-52ec-4ef0-bfe8-795f01c4b7d0","confirm":true}}' \
  'https://a-dashboard-cimed.hu/wp-json/wp-abilities/v1/abilities/mainwp/request-matomo-property-refresh-v1/run'
```

A válasz: `mode` (`preview` vagy `accepted`), `operation_id`, `status`, `account_ref` és `accepted_at`. Az előnézet nem hoz létre operációt, és az elfogadás ideje `null`.

### Webhelyadatok frissítése

Képesség: `mainwp/request-site-matomo-refresh-v1`, módszer: POST. Kötelező bemenet: `site_id_or_domain`, `start_date`, `end_date` és `request_ref`, valamint a mód jelzői. A dátumok `ÉÉÉÉ-HH-NN` alakúak, a bezárólag számolt időszak 1 és 366 nap közötti, és a kezdet nem lehet a végnél későbbi. A webhelynek érvényes hozzárendeléssel kell rendelkeznie.

```bash
curl -X POST -u 'FELHASZNALO:ALKALMAZASJELSZO' \
  -H 'Content-Type: application/json' \
  -d '{"input":{"site_id_or_domain":1,"start_date":"2026-10-01","end_date":"2026-10-07","request_ref":"053ac987-41b3-49b1-8c71-356f809fe4ac","confirm":true}}' \
  'https://a-dashboard-cimed.hu/wp-json/wp-abilities/v1/abilities/mainwp/request-site-matomo-refresh-v1/run'
```

A válasz: `mode`, `operation_id`, `site_id`, `status`, `range_days` és `accepted_at`. Az operáció az aktuális fiókhoz, a kapcsolati revízióhoz, a hozzárendeléshez és a webhely azonosságához kötött, ezek változása megakadályozhatja a futását. Mindkét frissítésnél az `operation_id` a kérés UUID-ja. Ugyanezzel az UUID-dal megismételt, azonos kérés a meglévő operációt adja vissza, amíg az elérhető. A kérés vagy a hozzá kötött állapot módosítása `mainwp_matomo_request_conflict` hibát adhat.

## Operáció ellenőrzése és leállítása

### Állapot lekérése

Képesség: `mainwp/get-matomo-operation-v1`, módszer: GET. Kötelező bemenet: `operation_ref`.

```bash
curl -G -u 'FELHASZNALO:ALKALMAZASJELSZO' \
  --data-urlencode 'input_json={"operation_ref":"053ac987-41b3-49b1-8c71-356f809fe4ac"}' \
  'https://a-dashboard-cimed.hu/wp-json/wp-abilities/v1/abilities/mainwp/get-matomo-operation-v1/run'
```

A válasz: `operation_id`, `kind` (`property_refresh` vagy `site_refresh`), `site_id` (tulajdonlista-frissítésnél `null`), `status`, `retryable`, `error_code`, `accepted_at` és `finished_at`.

| Állapot | Jelentés |
|---|---|
| `queued` | Elfogadva, ütemezett feldolgozásra vár |
| `running` | A feldolgozás elindult |
| `succeeded` | A frissítés befejeződött |
| `failed` | A frissítés meghiúsult, nézd meg az `error_code` és a `retryable` értékét |
| `unknown` | Az eredmény nem állapítható meg, nézd meg az aktuális adatokat, és egyeztesd, mielőtt újabb frissítést kérsz |
| `cancel_requested` | A leállítás biztonságos hívási határra vár |
| `cancelled` | Az operáció leállt |
| `skipped_access_lost` | A szükséges hozzáférés elveszett a befejezés előtt |

Az állapotlekérés nem indítja el a sorban álló munkát. Ha egy operáció sokáig `queued` marad, ellenőrizd a Dashboard webhely WordPress ütemezettfeladat-futtatóját. Az operációs bejegyzéseket 30 napig őrzi a rendszer, kivéve ha a webhely törlése vagy a bővítmény eltávolítása előbb letörli őket.

### Operáció leállítása

Képesség: `mainwp/cancel-matomo-operation-v1`, módszer: POST. Kötelező bemenet: `operation_ref`, a leállításhoz külön UUID `request_ref`, és a mód jelzői.

```bash
curl -X POST -u 'FELHASZNALO:ALKALMAZASJELSZO' \
  -H 'Content-Type: application/json' \
  -d '{"input":{"operation_ref":"053ac987-41b3-49b1-8c71-356f809fe4ac","request_ref":"649b8f4d-1778-489c-9194-74306793bfd4","confirm":true}}' \
  'https://a-dashboard-cimed.hu/wp-json/wp-abilities/v1/abilities/mainwp/cancel-matomo-operation-v1/run'
```

A válasz: `mode`, `request_id`, `operation_id`, `previous_status`, `status` és `quiescence`. A sorban álló operáció `cancelled` lesz `quiescence: before_dispatch` értékkel. A futó operáció `cancel_requested` lesz `quiescence: at_call_boundary` értékkel. A leállítás együttműködő: nem szakítja meg azonnal a már úton lévő Matomo-kérést, és nem vonja vissza a kész munkát. Ellenőrizd az állapotot, amíg végállapotba nem kerül. Befejezett operáció leállítása `mainwp_matomo_cancel_conflict` hibát ad.

## Hibák és újrapróbálás

| Hibakód | HTTP-állapot | Teendő |
|---|---|---|
| `mainwp_matomo_authentication_required` | 401 | Ellenőrizd a hitelesítést |
| `mainwp_matomo_access_denied` | 403 | Ellenőrizd a Dashboard-, Matomo-, webhely- és szerkesztési jogokat |
| `mainwp_matomo_invalid_input` | 400 | Ellenőrizd a kötelező mezőket, típusokat, dátumokat, URL-korlátozásokat és a felesleges tulajdonságokat |
| `mainwp_matomo_confirmation_required` | 409 | Válassz előnézeti vagy végrehajtási módot |
| `mainwp_matomo_stale_revision` | 409 | Olvasd el az aktuális beállítást vagy hozzárendelést, és nézd át újra a változtatást |
| `mainwp_matomo_stale_preview` | 409 | Kérj új hozzárendelési előnézetet |
| `mainwp_matomo_property_conflict` | 409 | Válassz olyan tulajdont, amely nincs másik webhelyhez rendelve |
| `mainwp_matomo_request_conflict` | 409 | Egyeztesd a korábbi kérést, másik szándékhoz használj új UUID-t |
| `mainwp_matomo_lock_busy` | 409 | Várd meg az aktív operációt vagy a konfigurációs zárat, tartsd be a `retry_after` értéket, ha van |
| `mainwp_matomo_assignment_required` | 422 | Előbb rendeld hozzá vagy kösd újra a webhelyet |
| `mainwp_matomo_snapshot_not_found` | 404 | Frissítsd a webhelyet, vagy ellenőrizd a pillanatkép-hivatkozást |
| `mainwp_matomo_operation_not_found` | 404 | Ellenőrizd a hivatkozást, a kérő felhasználót, a fiókot és a megőrzési időt |
| `mainwp_matomo_cancel_conflict` | 409 | Olvasd újra az állapotot, csak sorban álló vagy futó munka állítható le |
| `mainwp_matomo_write_failed` | 500 | Nézd meg az aktuális állapotot, és oldd meg a tárolási hibát |
| `mainwp_matomo_storage_unavailable` | 503 | Fejezd be az átállást, és oldd meg az adatbázis- vagy tárolási értesítéseket |
| `mainwp_matomo_provider_unavailable` | 502 | Ellenőrizd a Matomo elérhetőségét, a hitelesítő adatokat és a TLS-beállítást |
| `mainwp_matomo_outcome_unknown` | 502 | Egyeztesd az aktuális kapcsolati, hozzárendelési vagy operációs állapotot az újrapróbálás előtt |

A hibák tartalmazhatnak `retryable` és `retry_after` mezőt. Az időtúllépés vagy a bizonytalan válasz nem bizonyítja, hogy semmi nem változott. Előbb olvasd el a vonatkozó aktuális állapotot vagy operációt, azonos újrapróbálásnál tartsd meg az UUID-t, és ne küldj más kérést, amíg a korábbi eredmény nem világos.