A tenant API
Minden modul ugyanazon a tenant-hoston, saját előtag alatt érhető el:
https://<szervezet>.app.vecton.hu/api/<modul>/<erőforrás>
A <modul> az áttekintő táblázatban szereplő előtag
(webshop, warehouse, crm, …). Ha a modul a szervezetnél nincs
bekapcsolva, az útvonalai nem érhetők el.
Egy hívás
curl https://acme.app.vecton.hu/api/webhook/webhooks \
-H "Authorization: Bearer $VECTON_TOKEN" \
-H "Accept: application/json" \
-H "Accept-Language: hu"
| Fejléc | Mire való |
|---|---|
Authorization: Bearer <token> | Kötelező. A token típusairól: Hitelesítés. |
Accept: application/json | Mindig küldd, így a hibák is JSON-ként jönnek. |
Accept-Language | A válaszban szereplő emberi szövegek (message, fordított mezők) nyelve. Fejléc nélkül a szervezet alapnyelve. |
X-Idempotency-Key | Opcionális, lásd Ismételhető írás. |
A token csak annak a szervezetnek a hostján érvényes, amelynek a tulajdonosa
tagja (személyes tokennél: amelyre a tokent kiadták). Más szervezet hostján a
válasz 403.
Válaszok
Az irány, amit az új végpontok követnek:
| Eset | Státusz | Törzs |
|---|---|---|
| Lista | 200 | { "data": [...], "links": {...}, "meta": {...} } |
| Egy rekord, módosítás | 200 | { "data": {...} } |
| Létrehozás | 201 | { "data": {...} } |
| Törlés, adat nélküli művelet | 204 | üres |
| Validációs hiba | 422 | { "message": "...", "errors": { "mező": ["..."] } } |
| Egyéb hiba | 4xx / 5xx | { "message": "...", "error": "gepi_kod" } |
Néhány régebbi végpont még a { "success": true, "message": "...", "data": ... }
burkot adja, és törléskor 200-at üzenettel. A data mindkét alakban ugyanott
van — olvasd azt, a success mezőre ne építs. Ezek a végpontok fokozatosan
állnak át a fenti alakra.
Hibák
A hibaválasz error mezője gépi kód (snake_case): erre ágaztass. A message
a felhasználónak szóló, lefordított mondat, a szövege változhat.
| Státusz | error | Mit jelent |
|---|---|---|
401 | unauthenticated | Hiányzó, lejárt vagy visszavont token. Frissíts tokent, vagy jelentkeztesd be újra a felhasználót. |
403 | tenant_not_a_member | A token tulajdonosa nem tagja ennek a szervezetnek. |
403 | permission_denied, no_policies | Hiányzik a jog. A required_permission mező megmondja, melyik. |
403 | service_account_scope_denied | API-kulcsnál a kért jog nincs a kulcs hatókörében (required_permission). |
403 | personal_token_read_only | Csak olvasásra kiadott személyes tokennel írni próbáltál. |
403 | insufficient_app_scope, app_scope_unmapped | Marketplace-app tokennel a végpont nincs az app engedélyezett hatókörében. |
422 | — | Validációs hiba, mezőnként az errors-ban. |
429 | tenant_rate_limited | Túl sok kérés. A Retry-After fejléc mondja meg, hány másodperc múlva próbálkozz újra. |
503 | identity_unreachable | Az identity átmenetileg nem érhető el. Ez nem kijelentkezés: próbáld újra később, a tokent ne dobd el. |
Példa:
{
"message": "Nincs jogosultságod ehhez a művelethez.",
"error": "permission_denied",
"required_permission": "tenant.acme.webhook.webhooks.create",
"resource_type": "tenant",
"resource_id": null
}
Lapozás
A listák a Laravel lapozóját használják: ?page=2&per_page=50. A per_page
felső korlátja végpontonként más (jellemzően 100); a korlát fölötti érték
validációs hibát ad vagy a korlátra vágódik. A válasz meta része hordozza a
current_page, last_page, per_page és total értéket, a links a
szomszédos oldalak címét.
Kéréskorlát
A kéréseket szervezetenként és felhasználónként (API-kulcsnál kulcsonként)
mérjük. Korlát fölött a válasz 429, Retry-After fejléccel; ilyenkor várj
annyit, és utána ismételd a kérést. Erre a kliensed akkor is legyen felkészítve,
ha eddig nem találkozott vele: a korlátokat szervezetenként állítjuk. Ha a válasz X-RateLimit-Limit és
X-RateLimit-Remaining fejlécet hordoz, abból látod, mennyi kereted maradt.
Ismételhető írás
Az ismétlésre érzékeny írások (például mobil- és eszköz-végpontok) elfogadják
az X-Idempotency-Key: <uuid> fejlécet. Ugyanarra a kulcsra és végpontra a
második kérés a művelet újrafuttatása nélkül a tárolt választ kapja,
X-Idempotency-Replayed: true fejléccel. Ha az első kérés még fut, a
válasz 409 (idempotency_in_progress). A kulcs 24 óráig él, és a
felhasználóé: másik felhasználó ugyanazzal a kulccsal 422-t kap
(idempotency_key_reused). Sikertelen (nem 2xx) válasz után a kulcs
felszabadul, a javított kérés ugyanazzal a kulccsal újraküldhető.
API-referencia
A végpontok OpenAPI-leírása modulonként a kódból generálódik, így mindig a futó verziót írja le:
| Modul | Felület | OpenAPI-dokumentum |
|---|---|---|
| webshop | /docs/api/webshop | /docs/api/webshop/api.json |
| warehouse | /docs/api/warehouse | /docs/api/warehouse/api.json |
| crm | /docs/api/crm | /docs/api/crm/api.json |
| webhook | /docs/api/webhook | /docs/api/webhook/api.json |
| analytics | /docs/api/analytics | /docs/api/analytics/api.json |
| automation | /docs/api/automation | /docs/api/automation/api.json |
| repair | /docs/api/repair | /docs/api/repair/api.json |
| rental | /docs/api/rental | /docs/api/rental/api.json |
| copilot | /docs/api/copilot | /docs/api/copilot/api.json |
Az útvonalak a tenant-host gyökeréhez képest értendők (nem az /api alatt).
Éles tenant-hoston a referencia nem nyilvános. Ha integrációt fejlesztesz és szükséged van rá, kérd az OpenAPI-dokumentumot a Vecton ügyfélszolgálatától. Az e-mail modulnak jelenleg nincs generált referenciája.
Az OpenAPI-dokumentumból típusos klienst is generálhatsz (például
@hey-api/openapi-ts-sel vagy openapi-generator-ral) — a Vecton saját
felületei is így hívják az API-t.