Marketplace-app fejlesztése

A marketplace-app olyan alkalmazás, amit bármely Vecton-szervezet telepíthet, és ami a Vecton felületén belül jelenik meg. Az app nem kódot telepít a Vectonba: a saját szervereden fut, és egy manifestben deklarálja, milyen jogokat kér és hol jelenik meg a felületen. A Vecton ezt sandboxolt iframe-en és jogkörre szűkített API-tokenen keresztül engedi be.

Fejlesztői portál: https://marketplace.vecton.hu — Vecton-fiókkal lépsz be.

Az út a publikálásig

1. Fejlesztői szervezet — a portálon létrehozod (vagy meghívnak egybe). Az appok a szervezethez tartoznak.
2. App létrehozása — azonnal kapsz egy OAuth-klienst (client_id, client_secret). A titok egyszer látszik; a marketplace csak a client_id-t tárolja. Egy appnak egy kliense van, akárhány szervezet telepíti is.
3. Manifest — a portálon szerkeszted, vagy egy https:// címről beolvastatod. A portál a beküldéskor ellenőrzi a szerkezetet és azt, hogy a kért jogok léteznek-e a jogosultság-katalógusban.
4. Beküldés review-ra — a verzió életciklusa: draft → submitted → under_review → approved → published (később suspended, deprecated vagy removed). A review a manifestet, a kért jogokat és az iframe-címeket nézi.
5. Telepítés a szervezetnél — a szervezet adminisztrátora a saját felületén aktiválja az appot, egy hozzájárulási képernyőn látja a kért jogokat. A szervezet megszabhatja azt is, mely felhasználói használhatják az appot.

App-típusok: shipping, payment, ui, automation.

A manifest

A manifest verziónként rögzül: a szervezet egy konkrét manifestre adott jogot, ezért egy későbbi, többet kérő verzió új hozzájárulást igényel.

{
  "id": "acme-shipping",
  "name": "Acme Szállítás",
  "version": "1.0.0",
  "type": "shipping",
  "author": "Acme Kft.",
  "entrypoints": {
    "settings":     { "type": "iframe", "url": "https://app.acme-szallitas.hu/vecton/settings" },
    "order_action": { "label": "Címke generálása", "url": "https://app.acme-szallitas.hu/vecton/order-action" }
  },
  "permissions": [
    "webshop.orders.list",
    "webshop.orders.view"
  ],
  "ui_extensions": [
    { "slot": "order.detail.actions",      "type": "button",    "label": "Acme címke", "entrypoint": "order_action" },
    { "slot": "settings.shipping.methods", "type": "list_item", "label": "Acme beállítások", "entrypoint": "settings" },
    { "slot": "order.detail.tabs",         "type": "tab",       "label": "Acme státusz", "entrypoint": "order_action" }
  ]
}

Mező	Szabály
version	semver (1.0.0)
type	shipping | payment | ui | automation
entrypoints	objektum (nem lista); kulcsonként egy belépési pont. Az url csak https:// lehet — ezek lesznek az iframe-ek forrásai.
permissions	a kért jogok listája <modul>.<csoport>.<művelet> alakban, a jogosultság-katalógusból (lásd lent)
ui_extensions	a felületi megjelenések; slot és type kötelező, lásd UI-slotok
egész	legfeljebb 64 KB

A manifest hooks, settings_schema és subscriptions mezőt is elfogad (szerkezeti ellenőrzéssel, a subscriptions[].url csak https:// lehet), és ezek a review-ban látszanak. A szervezet oldalán ezek alapján jelenleg nem indul automatikus feliratkozás és nem jelenik meg beállító űrlap; eseményekhez a szervezet webhookot állíthat be az app címére.

Jogok és az app-token

Az app jogai a modulok meglévő jogosultság-katalógusából jönnek, a szervezet nélküli rövid alakban: crm.contacts.list, webshop.orders.view, warehouse.inventory.view. Minta is kérhető: crm.blog.*, webshop.*. A teljes alakról: Jogosultságok.

Amikor a felhasználó megnyitja az app egy felületi elemét, a Vecton rövid életű, a felhasználóhoz és az apphoz kötött tokent ad ki (alapból 5 perc, legfeljebb 15 perc), és az iframe-nek a vecton:init üzenetben adja át (lásd UI-slotok). Ezzel a tokennel az app a szervezet tenant API-ját hívja:

const res = await fetch(`${init.apiBaseUrl}/api/webshop/orders/${init.context.order_id}`, {
  headers: { Authorization: `Bearer ${init.token}`, Accept: 'application/json' },
})

Minden kérésnél mindkét kapunak teljesülnie kell:

1. a felhasználónak megvan a jog (a szerepköre szerint), és
2. az app telepítése megadja a végpont jogát.

Ha az app nem kapta meg a végpont jogát, a válasz 403 insufficient_app_scope (a required mező megnevezi a hiányzó jogot); jogosultsághoz nem kötött végpontot az app egyáltalán nem érhet el (403 app_scope_unmapped). Ha a szervezet nem engedte az appot ennek a felhasználónak, a válasz 403 app_access_denied. Az app nevében tett minden hívás naplózódik, az app és a kezdeményező felhasználó azonosítójával együtt.

Telepítéskor a Vecton azt is ellenőrzi, hogy a telepítő maga birtokolja-e a kért jogokat — ha az app többet kér, a hozzájárulási képernyő ezt jelzi.

Amit egy app nem tehet

• kódot tölt fel vagy futtat a Vecton szerverein;
• közvetlenül ír az adatbázisba vagy migrációt futtat;
• adminisztrátori jogú tokent kap;
• szkriptet injektál a Vecton felületébe — minden külső felület iframe mögött fut, a Vecton originjétől eltérő originről.