Raktárkezelő API · v1

Termékhez tartozó PDF-dokumentumok

A terméktörzsben mentett PDF-ek nem külön webshopadatok. A kijelölt, az API-ban elérhető termékek válaszában documents lista érkezik. Üres lista: nincs dokumentum; helyileg a korábbi kapcsolatokat is törölni kell a listából hiányzó azonosítóknál.

Minden dokumentumhoz id, kötelező name, size_bytes, sha256, updated_at és download_url tartozik. Belső fájlútvonal és feltöltő felhasználó nem kerül ki. A GET /products/{product}/documents külön is visszaadja a teljes, nem lapozott listát data alatt.

GET /products/{product}/documents/{document}: egy PDF letöltése application/pdf válasszal. Ugyanaz a catalog:read jogosultságú Bearer-kulcs szükséges, mint a termékhez. Csak a saját céghez és a lekérdező webshopban elérhető termékhez tartozó fájl érhető el. Más termék, más cég, megszüntetett hozzárendelés, törölt vagy hiányzó fájl: 404.

A download_url védett végpont, nem nyilvános webshoplink. A webshop szerveroldalon töltse le, ellenőrizze a SHA-256 hash-t, és a saját tárhelyéről szolgálja ki. A név módosítása, feltöltés és törlés products változási eseményt eredményezhet; frissítse a termék dokumentumlistáját. Törlés után a korábbi letöltési URL 404-et ad.

Tesztkulccsal ugyanezek a végpontok /test előtaggal használhatók, catalog:test jogosultsággal. A 910001 termék 940001 dokumentuma kizárólag szintetikus teszt-PDF. Más termékhez nem kérhető le, valós céges fájlt a teszt API nem ad át. Fájlcsere új dokumentumazonosítóval történik.

Szolgáltatói korlátozás · HTTP 423

Kézzel elrendelt csak olvasható módban a lekérdezések továbbra is működnek, de a rendelésbeküldés és a fizetési esemény beküldése HTTP 423 választ ad, code: organization_read_only értékkel. A kérés üzleti adatai nem kerülnek mentésre. Ez teszt és éles környezetben is érvényes.

Ez nem hibás rendelésadat: ne dobja el a beküldendő rendelést vagy fizetési eseményt. Őrizze meg helyileg, jelezze az adminisztrátornak, és a szolgáltatói feloldás után az eredeti külső azonosítókkal küldje újra. Ne próbálkozzon folyamatosan; a feloldás ideje nem ismert. A fizetés vagy az API-kulcs cseréje önmagában nem oldja fel a korlátozást.

1. Gyors indulás

Katalóguslekérés: termékek, kategóriák, készlet, képek és változásnapló. Külön jogosultsággal rendelésbeküldés, saját rendelésállapot lekérése és fizetési esemény rögzítése is elérhető. Közvetlen készletmódosítás nincs.

Éles alapcím: /api/v1/. Teszt: /api/v1/test/. Azonos végpontnevek, de a teszt kizárólag állandó mintaadatokat ad, test_mode: true és X-Raktar-API-Mode: test jelöléssel.

A főadmin a webshop szerkesztésében, a Fejlesztői hozzáférés részben készít tesztkulcsot. Fizetett webshopkapcsolat nem szükséges. Éles lekéréshez aktív, fizetett webshopkapcsolat és éles kulcs kell. A két kulcstípus nem felcserélhető.

A tesztkulcs 90 napig, az éles kulcs egy évig érvényes. Külön cserélhetők és visszavonhatók. A Swagger csak a saját teszt API-ra küldhet kérést, saját tesztkulccsal.

curl --fail-with-body --get "https://cloudraktar.hu/api/v1/test/products" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer SAJAT_TESZTKULCS" \
  --data-urlencode "per_page=2"

Ügyfélcsoportok

GET /customer-groups: catalog:read jogosultsággal az adott cég aktív és a lekérdező webshophoz kijelölt ügyfélcsoportjai. Kijelölés nélkül a csoport csak raktári. Csak id és name érkezik; belső megjegyzés, ügyféllista és kedvezmény nem. Lapozás: page és per_page (alapértelmezés 50, maximum 100).

GET /test/customer-groups: catalog:test kulccsal kizárólag állandó mintaadatok, test_mode: true jelöléssel. Valós céges csoportok tesztkulccsal nem kérdezhetők le.

A csoportlista jelenleg nem része a /changes naplónak és nem küld külön webhookot. Kezdeti összekötéskor és szükség szerint kérje le újra a teljes, lapozott listát; a hiányzó vagy inaktív csoportot helyileg ne használja tovább.

A raktári csoportazonosító nem ügyfélbesorolási utasítás. Nem lehet ezzel automatikusan átsorolni az ügyfelet, és a publikálás önmagában nem ad kedvezményt.

Rendeléskor a webshop saját csoportjai opcionálisan customer.external_groups listában adhatók át (maximum 20). Minden elem kötelező id és name szöveg, legfeljebb 100 karakter; id-k a listán belül egyediek. Numerikus saját csoportazonosítót is szövegként küldjön. Elhagyható vagy üres lista, de nem null.

A customer.external_groups csak fagyasztott rendelési információ, vendég és regisztrált ügyfélnél is. Nem raktári csoportazonosítók, nincs név szerinti összekötés, automatikus csoportlétrehozás, átsorolás vagy új kedvezményszámítás. Újraküldéskor ezt a listát is változatlanul őrizze meg.

{
    "customer": {
        "type": "registered",
        "external_id": 42,
        "external_groups": [
            {
                "id": "shop-vip",
                "name": "Webshop VIP"
            }
        ]
    }
}

Rendelések és fizetési események

A főadmin kulcsgeneráláskor külön kapcsolhatja be a rendelési hozzáférést: orders:read és orders:write, tesztben orders:test. A meglévő katalóguskulcsok nem kapnak automatikusan új jogot. A két környezet nem felcserélhető.

POST /orders: external_order_id webshoponként egyedi, legfeljebb 80 karakter (betű, szám, aláhúzás, kötőjel). Ugyanaz a validált JSON ismételve 200 és az eredeti rendelés; első beküldés 201. Eltérő tartalom azonos azonosítóval: 409. Újrapróbálásnál őrizze meg a teljes eredeti payloadot, az ordered_at értékét is.

A rendelés visszaigazolt, fizetésre váró állapotban jön létre. Nem foglal és nem von le készletet; a raktári foglalás és teljesítés továbbra is külön munkafolyamat.

POST /api/v1/orders és POST /api/v1/test/orders: a customer.type kötelező JSON string, kizárólag registered vagy guest. A customer.external_id registered esetén kötelező, nem null, szigorúan JSON integer a PHP 64 bites előjeles tartományában: -9223372036854775808 és 9223372036854775807 között. A 0 és a negatív érték is érvényes. Számként írt string ("123"), tört, 123.0, exponenciális szám (1e3), logikai érték és tartományon kívüli szám nem fogadható el. Nagy azonosítónál kerülje a JavaScript Number pontosságvesztését; a JSON-ba pontos egész számot írjon, idézőjelek nélkül.

Guest esetén a customer.external_id elhagyható vagy null; ha megadja és nem null, ugyanaz a szigorú integer szabály érvényes. Vendégből nem készül Customers-törzsadat, adatai csak a rendelési pillanatképen maradnak meg, megadott external_id mellett is.

Registered esetén ugyanaz a tenant + webshop + customer.external_id több rendeléshez ugyanazt az ügyfelet azonosítja. Másik webshop vagy tenant azonos külső azonosítója külön ügyfél. Email alapján nincs automatikus összevonás. A meglévő ügyfél helyben módosított törzsadatait a rendelésbeküldés nem írja felül automatikusan.

A számlázási, szállítási és kapcsolattartási adatok rendelésenként fagyasztott pillanatképek: az adott beküldés customer adatait őrzik. Későbbi rendelés vagy ügyféltörzs-módosítás nem változtatja meg a korábbi rendelési pillanatképet.

Hibás vagy hiányzó típus: HTTP 422, errors["customer.type"]. Hiányzó/null registered azonosító vagy hibás external_id: HTTP 422, errors["customer.external_id"]. A customer.name, customer.email és customer.billing_address mindkét típusnál kötelező; phone, tax_number, contact_name és shipping_address opcionális/null.

A tételsorok product_id és sku mezője a webshophoz rendelt valós változatot azonosítja, nem a variációs gyűjtőt. A checkout name, unit_net_price, unit_gross_price és vat_rate értékei változatlan pillanatképek. Mennyiség: legfeljebb három tizedes, darabos termék egész. Egyszerre legfeljebb 200 sor és 256 KiB JSON. Jelenleg csak HUF támogatott.

A kedvezményekkel csökkentett egységárakat küldje. Szállítási és fizetési díjak: charges lista (name, net, gross, vat_rate), legfeljebb 20 sor. A total_net és total_gross a tételsorok (egységár × mennyiség, soronként HALF_UP két tizedes) és díjak összege. Egységár legfeljebb négy tizedes; végösszegek és fizetés kettő. A nettó/bruttó ÁFA-egyezésnél legfeljebb 0,02 eltérés engedett.

Fizetési mód és szállítás külön: card = Fizetés az üzletben, personal = Személyes átvétel, stripe = Online – Stripe. A card soha nem jelent automatikusan online bankkártyás fizetést. price_base: net vagy gross, de mindkét árat és végösszeget kötelező küldeni.

GET /orders/{externalOrder}: kizárólag a beküldő webshop rendelése, a külső azonosító alapján. Visszaadja a belső status és üzleti order_status értékét (például cancelled, completed), a fizetési állapotot, payment_version és payment_sequence értékeit. Nem ad vissza vevőadatot. Az állapotváltozásról külön order.status_changed webhook érkezik.

POST /orders/{externalOrder}/payment-events: a megbízható webshop szerverének összesített fizetési pillanatképe. event_id rendelésenként egyedi; sequence pozitív, szigorúan növekvő. payment_version legyen az utolsó GET válasz értéke. Változatlan esemény újraküldése nem módosít újra; azonos ID eltérő tartalommal vagy régi verzió/sorszám: 409. Konfliktusnál egyeztetés kell, nem vak újraküldés új verzióval.

paid_amount és refunded_amount összesített, nem eseményenkénti különbözet; nem csökkenhetnek. Fizetett állapothoz a paid_amount a teljes bruttó végösszeg; részleges fizetésnél kisebb, pozitív összeg. Fizetéshez paid_at szükséges. Visszatérítés nem lehet nagyobb a korábbi fizetésnél. Az esemény nem kezdeményez Stripe-terhelést, visszatérítést, teljesítést vagy készletmozgást.

A payment_status cégenként bővíthető törzsadatkulcs. Az alapkulcsok: unknown, unpaid, pending, partially_paid, paid, failed, partially_refunded, refunded, storno. Éles beküldésben saját státuszkulcs is használható, legfeljebb 32 karakterrel, de unknown pénzügyi jelentésű nem. Tesztben csak az alapkulcsok fogadhatók. A válasz payment_state mezője mindig az eredeti alapkulcs szerinti pénzügyi jelentés: az integráció erre építse a fizetési logikát, ne a megjelenített névre vagy az egyedi kulcsra.

Stripe esetén kizárólag szerveroldalon ellenőrzött szolgáltatói esemény vagy ellenőrzött fizetési lekérdezés után küldjön paid adatot. A vásárló visszatérési URL-je nem igazolja a fizetést. A raktár a beküldő szervert hitelesíti, nem ellenőrzi közvetlenül a webshop Stripe-fiókját.

Tesztben a POST-ok nem hoznak létre rendelést, ügyfelet vagy fizetést: test_mode: true, persisted: false és accepted jelölés érkezik. Ugyanaz a customer.type és customer.external_id validáció érvényes, mint élesben. A rendelésösszegeket ellenőrizzük, a teszt GET állandó mintát ad. A tesztfizetés csak formai ellenőrzés: nem szimulál előző fizetést vagy valódi készletet. Swaggerből továbbra is csak teszt GET futtatható; POST-hoz szerveroldali kliens vagy curl használható.

{
    "external_order_id": "SHOP-123",
    "ordered_at": "2026-10-24T10:00:00+02:00",
    "currency": "HUF",
    "price_base": "gross",
    "payment_method": "card",
    "shipping_method": "personal",
    "lines": [
        {
            "product_id": 910001,
            "sku": "API-DEMO-001",
            "name": "Teszt USB billentyűzet",
            "quantity": "2",
            "unit_net_price": "1000.0000",
            "unit_gross_price": "1270.0000",
            "vat_rate": "27.00"
        }
    ],
    "total_net": "2000.00",
    "total_gross": "2540.00",
    "customer": {
        "type": "registered",
        "external_id": 0,
        "name": "Teszt Vásárló",
        "email": "vasarlo@example.test",
        "billing_address": "1111 Budapest, Teszt utca 1.",
        "shipping_address": "1111 Budapest, Minta utca 2.",
        "contact_name": "Teszt Kapcsolattartó",
        "phone": "+3612345678"
    }
}

2. Hitelesítés és adatelkülönítés

Authorization: Bearer SAJAT_API_KULCS. A kulcs kizárólag szerveroldali konfigurációba való. Ne tegye URL-be, naplóba, forráskódba vagy nyilvános webshop-JavaScriptbe. Élesben kizárólag HTTPS-t használjon.

Egy kulcs egy cég egy webshopjához tartozik. Küldött organization_id vagy webshop_id nem változtatja meg ezt. Csak a webshopnak publikált, elérhető adatok kérdezhetők le; beszerzési ár, nagykerár és belső készlethely nem kerül átadásra.

A Swagger csak az aktuális oldal memóriájában tartja a kulcsot, frissítéskor újra meg kell adni. A megjelenő cURL-példa is tartalmazhatja a megadott kulcsot: megosztás előtt takarja ki. A hozzáférést minden kérésnél újra ellenőrizzük.

use Illuminate\Support\Facades\Http;

$response = Http::acceptJson()
    ->withToken(config('services.raktar.test_key'))
    ->connectTimeout(3)->timeout(15)
    ->get(rtrim(config('services.raktar.test_url'), '/').'/products', [
        'per_page' => 50, 'page' => 1,
    ]);
$response->throw();
$products = $response->json('data');

3. Mezők, árak és készlet

Variációs gyűjtők: GET /variant-groups és /variant-groups/{group}. A gyűjtő webshoponként önálló, nincs cikkszáma, készlete vagy ára. Közös név/leírás, category_id, brand, manufacturer, attribute_names és variants lista tartozik hozzá. A kategória önállóan megadható; a gyártót és márkát a kiinduló változatból vesszük át. A változatok product_id, sku és attribute_values mezői alapján készíthető választó.

A termék variant_group mezője null önálló terméknél; változatnál a gyűjtő id, name, url és saját attribute_values értékei szerepelnek. Az ár, kép és készlet továbbra is változatonként kérdezhető le. A gyűjtő csak az adott webshopnak publikált, aktív változatokat tartalmazza. Üres gyűjtő nincs az API-ban.

A gyűjtő category_id mezője kategóriaazonosító vagy null; a /categories listával kapcsolható össze. Saját webshopos besorolás, nem írja át a változatok raktári kategóriáját. A kijelölt kategóriának és minden szülőjének aktívnak és a webshop számára publikáltnak kell lennie; különben a gyűjtő és változatai nem érhetők el.

A gyűjtő brand és manufacturer mezője megnevezés vagy null, nem azonosító. Létrehozáskor a kiinduló változat márka- és gyártó-hozzárendelését vesszük át; ezek a gyűjtő szerkesztésében csak olvashatók. Másik változat hozzáadása vagy a kiinduló változat későbbi átállítása nem cseréli le a gyűjtő hozzárendeléseit.

A gyűjtőnél nincs prices, sku vagy quantity mező. A variants lista product_id alapján a /products/{product} végpontról az adott változat prices adatai, a /stocks/{product} végpontról a készlete kérdezhető le. Az attribute_names adja a választók sorrendjét; az attribute_values objektumot név szerint olvassa, ne a JSON-kulcsok sorrendjére támaszkodjon.

Az id egész szám, a sku karakterlánc, pontos egyezéssel kereshető; URL-kódolva küldje. A category_id a kategóriára utal. A parent_id alapján építhető kategóriafa, null esetén fő kategória.

prices.retail és prices.discount: nettó HUF, négy tizedesjegyes karakterlánc. tax_included: false; vat_rate: százalékos ÁFA karakterláncként. Null: nincs megadva; "0.0000": valódi nulla. Decimális aritmetikával számoljon.

prices.discount az aktuálisan legkedvezőbb érvényes webshopos akciós ár. A termék- és kategóriaakció, valamint a kézi webshopakció nem halmozódik. Kategóriaakciónál a normál webshopár a számítás alapja, az alkategóriákra kiterjesztés külön beállítás. Automatikus webshopárazásnál a raktári termék akciós árát a beállított árréssel növeljük; kézi webshopárazásnál nem vesszük át a raktári termékakciót.

Az akció kezdőidőpontja már érvényes; a záróidőponttól nem érvényes. Időpont nélkül az akció folyamatos. Akció hiányában prices.discount: null, ilyenkor a korábban mentett akciós árat is törölje. A 0.0000 érvényes ingyenes ár, nem null. A raktári ügyfélcsoport-kedvezmény nem publikus webshopár. A rendelésbeküldés checkout-végárait a raktár továbbra sem kedvezményezi újra.

Variációs webshopterméknél a gyűjtő saját kategóriája adja a webshopos kategóriaakció alapját, ha be van állítva; egyébként a változat kategóriája. Ez nem módosítja a változat raktári kategóriáját vagy a belső rendelési árazását.

Akció szerkesztésekor outboxba kerül az árfrissítés. Az időzített kezdetet és lejáratot a raktár discounts:refresh ütemezett parancsa percenként teszi outboxba; az értesítés ugyanaz a catalog.changed webhook, products upsert változással. A fogadó kérje le újra a terméket; a webhook nem teljes árpayload. Sikertelen kézbesítés a meglévő újrapróbálással pótolható.

description_format: html. A leírásokat saját megjelenítési környezetének megfelelően is tisztítsa. Vonalkód, kategória, márka, gyártó, leírás, ár és kép lehet null.

quantity: a kijelölt aktív raktárak összesített készlete. reserved_quantity: nyitott foglalás. available_quantity = quantity - reserved_quantity. Negatív elérhető és nulla készletű publikált termék is előfordulhat.

Mennyiség: karakterlánc; tizedesjegyek: quantity_scale. Darabnál 0, például "10". A termék measurement_unit mezője a mértékegység neve, a készleté a jele. calculated_at: a válasz időpontja, nem többoldalas készlet-pillanatkép. Raktár-/polcbontás nincs.

4. Lapozás és első teljes import

Listák: page és per_page, alapból 50, legfeljebb 100 tétel/oldal. page: 1-1000000. Termék- és készletlistán opcionális, pontos sku szűrés. A válasz data, links és meta elemeket tartalmaz; links.next null jelzi a végét.

A kapott URL-t csak saját konfigurált API-domain és engedélyezett útvonal ellenőrzése után kövesse. Ismeretlen domainnek soha ne továbbítsa a Bearer-kulcsot.

Első import előtt GET /changes?after=0&limit=1: mentse a meta.current_cursor értékét. 410 válasznál a current_cursor a gyökérben található. Töltse le a teljes kategória-, termék-, variációs gyűjtő- és készletlistát, majd játssza vissza az eltárolt kurzor óta történt változásokat. A /variant-groups listát is lapozza végig; webshoponként külön gyűjtőazonosítókat tároljon.

Import közben változhatnak az adatok. Idempotens felülírás és sikeresen feldolgozott oldalak/kurzorok alapján folytatható import szükséges.

5. Változásnapló

GET /changes?after=MENTETT_KURZOR&limit=50. after/until: 0-9007199254740991; after <= until <= aktuális kurzor. limit: 1-100, alapérték 50. A következő oldalon after = meta.next_cursor; az első meta.until értékét végig tartsa meg. meta.has_more jelzi a folytatást.

resource: categories, products, stocks vagy variant_groups. upsert: friss erőforrás-lekérés; remove: helyi publikáció eltávolítása. Upsert utáni 404-nél is távolítsa el a publikációt. Egyedi kategórialekérés nincs: kategóriaváltozáskor a kategórialistát frissítse. Csak sikeres feldolgozás után mentse a kurzort.

Megőrzés: 90 nap. Lejárt kurzornál HTTP 410, reset_required: true és current_cursor: teljes újraimport szükséges. A teszt változásnapló három állandó eseményt ad.

Mentések után háttérfeldolgozás fut, ezért a változásnapló nem feltétlenül azonnali. Gyors módosításokat összevonhatunk. Ez állapotszinkronizálás, nem üzleti auditnapló.

6. Termékképek

Kép nélkül image: null; egyébként url és version. A /products/{product}/image ugyanazt a Bearer-kulcsot kéri. Szerveroldalon töltse le, saját tárhelyéről szolgálja ki; a védett URL nem nyilvános img-forrás.

A version változásjelző, nem garantáltan dátum (a tesztben demo-v1). Változásakor töltse újra. Egy fő kép érhető el JPEG/PNG/WebP formátumban, nem képgaléria. Hiányzó kép vagy nem publikált termék: 404. Mintakép: /api/v1/test/products/910001/image.

7. Webhook fogadása

A főadmin a webshopkapcsolatban állítja be a fogadó URL-t és a külön webhooktitkot, amely nem az API-kulcs. Élesben nyilvános HTTPS-fogadó kell; átirányítást nem követünk.

POST JSON: id, type (catalog.changed), webshop_id (nyilvános kapcsolat-azonosító), cursor, changes_url, occurred_at. Ez csak jelzés, nem teljes termék-/készletadat. A Webhook séma az OpenAPI-ban is szerepel.

Rendelési értesítés: type: order.status_changed, id: WEBSHOPAZONOSITO:order:RENDELES_ID:REVIZIO, webshop_id, revision, occurred_at, order: {order_id, external_order_id, number, status, order_status}. Ugyanaz az éles webhooktitok, aláírás és időbélyeg-ellenőrzés érvényes. Csak a beküldő webshop, érvényes orders:read kulcs és fizetett kapcsolat mellett kapja meg; vevőadatot nem tartalmaz.

A revision rendelésenként monoton növekszik, nem katalóguskurzor és nem payment_version. A fogadó rendelésenként tárolja az utolsó revíziót, az ismételt és régebbi értesítést mellőzi, és csak a saját external_order_id + order_id párosát módosítja. Rövid időn belüli változások összevonhatók: mindig az aktuális állapot érkezik, nem teljes történet. Hibánál tartós outboxból újrapróbáljuk, az id változatlan; 2xx nyugtázás szükséges.

A fulfilled belső állapot készletkiadást jelent, nem feltétlenül sikeres kézbesítést: at_delivery esetén még folyamatban van a rendelés. A completed üzleti státusz jelzi a befejezést, cancelled a törlést. Egyik webhook sem indíthat automatikus fizetést, visszatérítést vagy újabb készletlevonást. Egyedi üzleti státuszok saját leképezést igényelnek. Kikapcsolt webhook mellett a GET /orders/{externalOrder} lekérdezés használható.

Fejlécek: X-Raktar-Event-Id, X-Raktar-Timestamp (Unix-másodperc), X-Raktar-Signature, X-Request-ID. Aláírás: sha256=HMAC_SHA256(timestamp + "." + NYERS_BODY, titok). A nyers, újrakódolás nélküli törzset ellenőrizze, konstans idejű összehasonlítással és legfeljebb 5 perc eltéréssel.

Ezután kapcsolat-azonosító és eseménytípus ellenőrzése, id szerinti idempotens feldolgozás. changes_url helyett saját konfigurált API-alapcímét használja. Tartós rögzítés vagy megbízható sorba állítás után gyors 2xx választ adjon: ez csak átvételt igazol.

Hibánál 1, 5, 15, 60, 360, majd 1440 percenként újrapróbálunk; az ütemezés módosíthatja a pontos időt. Ismételt/összevont értesítés normális. A legújabb kurzor korábbi, még kézbesítetlen állapotot válthat fel; saját mentett kurzortól olvassa a változásokat.

Kézi teszt: a főadmin a Fejlesztői hozzáférés részen külön teszt-webhooktitkot készít és a fogadó tesztkonfigurációjába másolja. A Teszt-webhook küldése gomb a mentett webhook-végpontra küld, jelszóval és megerősítéssel. Fizetett kapcsolat nem szükséges. Limit: 3 küldés/perc/webshop; nincs automatikus újraküldés.

A teszt típusa catalog.test, test_mode: true, X-Raktar-API-Mode: test, cursor: 3, changes_url: a /api/v1/test/changes címe. Az id test:KAPCSOLATAZONOSITO:ULID formátumú, nem az éles kurzorhoz kötött. Az aláírást kizárólag a külön teszt-webhooktitokkal ellenőrizze. A törzs jelölését, fejlécet és típust együtt ellenőrizze, a teszt nem indíthat éles importot. A termelési webhooktitok, kurzorok és függő küldések nem változnak.

$raw = $request->getContent();
$timestamp = (string) $request->header('X-Raktar-Timestamp', '');
$signature = (string) $request->header('X-Raktar-Signature', '');
abort_unless(ctype_digit($timestamp) && strlen($timestamp) <= 12, 401);
abort_if(abs(time() - (int) $timestamp) > 300, 401);
$expected = 'sha256='.hash_hmac('sha256', $timestamp.'.'.$raw, $secret);
abort_unless(hash_equals($expected, $signature), 401);

8. Limitek, hibák és támogatás

Éles: 120 kérés/perc/webshop. Teszt: 30 kérés/perc és 5000 kérés/24 óra/webshop. Külön keretek; kulcscserével nem indulnak újra. A 24 órás ablak nem feltétlenül naptári nap.

Nincs havi, csomaghoz kötött kérési kvóta miatti automatikus tiltás. A technikai sebességvédelem ettől függetlenül érvényes. A szolgáltató a forgalmat technikai számlálókkal méri; egyedi kapacitás egyeztethető.

Közös IP-védelem is működik: 300 kérés/perc. X-RateLimit-Limit és X-RateLimit-Remaining az alkalmazott korlátot jelzi; több limit nem feltétlenül látható külön.

401: hibás/lejárt kulcs; 403: hibás környezet/jogosultság vagy inaktív hozzáférés; 404: nem elérhető erőforrás; 410: lejárt kurzor; 422: hibás paraméter; 429: kérési korlát; 5xx: szerverhiba.

429-nél várjon a Retry-After szerinti másodpercig. Átmeneti hálózati/5xx hibánál korlátozott, növekvő várakozású újrapróbálás, véletlen szórással. 401/403/422-nél ne próbálkozzon végtelenül.

Hibabejelentés: időpont, végpont sablonja, HTTP-státusz, X-Request-ID. Ne küldjön kulcsot vagy nyers céges adatot. A főadmin Technikai állapot ablaka és a szolgáltató adatmentes naplója segít, egy naptári hónap megőrzéssel.

Új opcionális válaszmezőket a kliens hagyjon figyelmen kívül. Az API-főverzió és a dokumentáció kiadása külön fogalom. Törő módosítás külön API-főverzióba kerül; integráció frissítésekor ellenőrizze az aktuális kiadást.