# Integrációs frissítési útmutató Az alábbi változtatások mindegyike szigorúan additív: a meglévő végpontok, válaszmezők, HTTP-státuszkódok, a webhook-adatcsomagok bájtjai és az örökölt `Signature` fejléc változatlanok. A semmit sem módosító integrációk pontosan úgy működnek tovább, mint eddig. Az egyes funkciók egymástól függetlenül, tetszőleges sorrendben bevezethetők. Élőben elérhető itt: https://api.superlabel.ca/api/documentation/integration-updates?lang=hu (`?download=1` a mentéshez). Kapcsolódó dokumentumok: OpenAPI (https://api.superlabel.ca/api/documentation?lang=hu), Postman-gyűjtemény (https://api.superlabel.ca/api/documentation/postman-collection), állapotszótár és folyamat (https://api.superlabel.ca/api/documentation/order-status-flow?lang=hu). --- ## 1. Lemondás követési szám alapján (idempotens) `POST https://api.superlabel.ca/api/v1/orders/cancel` — pontosan egyet adjon meg a következők közül: `order_id`, `tracking_number`, `external_tracking_number`. ```json POST /api/v1/orders/cancel Authorization: Bearer { "external_tracking_number": "WP1234567890" } ``` - Siker: `200 {"result":true,"id":123456,"already_cancelled":false,...}` - Már lemondva (biztonságos újrapróbálás): `200` és `"already_cancelled": true` - A szám több élő rendeléssel egyezik: `409` és `"matched_order_ids": [...]` — próbálja újra `order_id`-val. - Az örökölt `GET /v1/orders/{orderId}/cancel` változatlan. ## 2. Inkrementális egyeztetési adatfolyamok Kérjen le mindent, ami egy adott időablakon belül változott; a kurzoros lapozásnak köszönhetően egyetlen rekord sem marad ki vagy számolódik duplán. - `GET https://api.superlabel.ca/api/v1/orders-reconciliation?updated_from=&updated_to=&per_page=&cursor=` - `GET https://api.superlabel.ca/api/v1/tracking-events/reconciliation?...` Az `updated_from` / `updated_to` unix időbélyegeket vagy a platform időzónája szerinti `Y-m-d H:i:s` karakterláncokat fogad el. Kövesse a `next_cursor` értéket, amíg a `has_more` false nem lesz; az összehasonlítást a `*_timestamp` unix mezőkkel végezze, sose helyi idejű karakterláncokkal. A nyomkövetési eseményelemek tartalmazzák az `occurred_at` / `occurred_timestamp` mezőket (az üzleti bekövetkezés ideje; a történeti soroknál megegyezik a létrehozás idejével). ## 3. Géppel olvasható hibakódok és kéréskövetés A gyakori létrehozási/lemondási hibaválaszok mostantól a változatlan `message` mellett egy stabil `code` mezőt is tartalmaznak: `VALIDATION_FAILED`, `MISSING_IDENTIFIER`, `ORDER_NOT_FOUND`, `ORDER_CANCEL_UNAUTHORIZED`, `ORDER_STATUS_NOT_CANCELLABLE`, `ORDER_CANCEL_BLOCKED_THIRD_PARTY`, `LABEL_CANCEL_FAILED`, `DUPLICATE_TRACKING_NUMBER`, `MULTIPLE_ORDERS_MATCHED`. A kódok stabil azonosítók — újak megjelenhetnek, a meglévők jelentése sosem változik. Minden API-válasz visszaadja az `X-Request-ID` fejlécet is; hibabejelentéskor hivatkozzon rá. ## 4. Duplikátumészlelési fejlesztések Az `auto_deduplication=1` beállítással egy blokkolt létrehozás `exist_package_ref` / `exist_external_tracking_number` bejegyzései mostantól tartalmazzák a meglévő `order_id` és `order_ref` értékeket, a boríték pedig a `"duplicate": true` mezőt hordozza. Opcionális szigorú mód: küldje a `strict_duplicate_check=1` paramétert, hogy az örökölt `200` + `result:false` helyett HTTP `409` választ kapjon (a jelző elhagyásával az örökölt viselkedés marad). ## 5. Kötegelt létrehozási beállítások - `per_order_transaction: 1` (a kötegtörzs legfelső szintjén): minden rendelés önállóan kerül véglegesítésre — egyetlen hiba többé nem görgeti vissza a többit. Ha a feldolgozás idő előtt megszakad, akkor is megkapja az összes befejezett elem sorát, valamint egy záró `{"result":false,"batch_aborted":true}` sort. - A 100 rendelésnél nagyobb kötegek tájékoztató jellegű `X-Batch-Size-Warning` válaszfejlécet kapnak; nagy mennyiségekhez részesítse előnyben a `POST /v1/client/batchOrderCreateAsync` végpontot. ## 6. Kézbesítési igazolás fájlszinkronizálása A nyomkövetési válaszok `proofs[]` bejegyzései mostantól a következőket is tartalmazzák: ```json { "url": "...", "full_url": "...", "type": 2, "file_id": 234567, "uploaded_at": "2026-07-20 14:30:05", "uploaded_timestamp": 1784745005, "signed_url": "https://.../files/pod/234567?expires=...&signature=...", "signed_url_expires_at": 1784745005 } ``` Használja a `file_id` értéket deduplikációs / inkrementális szinkronizációs kulcsként. A `signed_url` lejáró hivatkozás (7 nap) — lejárat után kérdezze le újra a nyomkövetést egy frissért. Az állandó `url` / `full_url` hivatkozások változatlanok. ## 7. Webhookok: v2 aláírás-fejlécek (minden kézbesítésnél) Minden webhook mostantól a változatlan, örökölt `Signature` fejléc mellett EZEKET IS elküldi: | Fejléc | Jelentés | |---|---| | `X-Webhook-Event-Id` | UUID, újrapróbálások között is állandó — deduplikációhoz használja | | `X-Webhook-Timestamp` | unix másodpercek az első küldéskor | | `X-Webhook-Signature-V2` | A `"."` HMAC-SHA256 aláírása | Ellenőrzés (bármely nyelven): `expected = HMAC_SHA256(timestamp + "." + raw_body, your_secret)`; hasonlítsa össze a fejléccel konstans idejű összehasonlítással. Az időbélyeg az első küldéskor rögzül és az újrapróbálásoknál újra felhasználásra kerül (az újrapróbálások akár ~3 óráig is futhatnak), ezért szigorú visszajátszási határidő helyett párosítson bőséges tűréssávot az `X-Webhook-Event-Id` alapú deduplikációval. A meglévő, örökölt `Signature`-ellenőrzése változatlanul működik tovább — a v2-t akkor vezeti be, amikor szeretné. Mindkét aláírást tesztelheti a végpontja ellen a webhook-útmutató oldalról (`/webhooks-guide`). ## 8. Webhookok: opcionálisan bekapcsolható adatcsomag-boríték Állítsa be a `webhook_payload_envelope = 1` értéket a webhook-beállításaiban, hogy az objektum alakú események JSON-törzsében megkapja az `event_id`, `event_time` (ISO8601 eltolással) és `event_timestamp` (unix) mezőket, valamint — ahol értelmezhető — az `is_correction: true` mezőt (egy korábban kézbesített/átadott rendelés újra belépett a folyamatba), továbbá a nyomkövetési eseményeken az `occurred_at` / `occurred_timestamp` mezőket. A jelző nélkül az adatcsomag bájtra pontosan a korábbi marad. A lista alakú adatcsomagok (`order.create_async`) soha nem módosulnak. ## 9. Új webhook-események (bekapcsolható URL-ek) - `pod.files_updated` — kézbesítési fotót/aláírást adtak hozzá vagy távolítottak el utólag. Konfigurálja a `pod_files_webhook_url` beállítást. Adatcsomag: `{"action":"added|removed","order_id":...,"order_ref":..., "tracking_number":[...],"external_tracking_number":[...], "file":{"file_id":...,"type":1|2,"note":null}, "event_id":..., ...}` - `order.deleted` — egy rendelést véglegesen töröltek. Konfigurálja az `order_deleted_webhook_url` beállítást. Adatcsomag: `{"action":"deleted","order_id":..., "order_ref":...,"tracking_number":[...],"external_tracking_number":[...], "event_id":..., ...}` Mindkét esemény mindig tartalmazza a borítékmezőket, és csak akkor kerül elküldésre, ha az URL-je konfigurálva van. ## 10. Webhookok: kézbesítési beállítások - **Több végpont eseményenként**: minden webhook-URL beállítás elfogad egyetlen URL-t (mint eddig), vesszővel elválasztott listát vagy JSON-tömböt. Minden végpont saját kézbesítési és újrapróbálási ciklust kap. - **TLS-ellenőrzés**: állítsa be a `webhook_verify_ssl = 1` értéket, hogy a kimenő hívások ellenőrizzék a tanúsítványát. Az alapértelmezés kikapcsolva marad (történeti viselkedés). - **order.created minden rendeléstípusra**: állítsa be az `order_created_webhook_all_types = 1` értéket, hogy a rendelés-létrehozási esemény a helyi kézbesítésű rendeléseken túlra is kiterjedjen. Az alapértelmezés megtartja a történeti hatókört. - **Aláírási titkok**: az első beállításkor erős véletlenszerű titkot kap; a meglévő titkok sosem cserélődnek le automatikusan. ## 11. API-token hatókörök és IP-engedélylisták (opcionális) Az egyes tokenek korlátozhatók az `orders:read`, `orders:write` és/vagy `webhooks:manage` hatókörökre, valamint engedélyezett IP-címek listájára. A korlátozás nélküli tokenek (az alapértelmezés, és minden már meglévő token) pontosan úgy viselkednek, mint eddig. Ha egy korlátozott token a hatókörein/IP-címein kívül hív, `403` választ kap. Token korlátozásához forduljon a támogatáshoz. ## 12. Fuvarozói csomag beküldése (Smart Locker) A külső fuvarozók egyetlen kötegelt hívással küldenek be csomagokat egy raktár előkészítő területére. Opcionálisan csatolható a címzett telefonszáma/e-mail címe, hogy a címzett átvételi kóddal értesüljön, amint a csomag bekerül az intelligens szekrénybe. A címzett mezői opcionálisak — a végpont visszafelé kompatibilis marad. ```json POST https://api.superlabel.ca/api/v1/inventories/carrier-staging-stockin Authorization: Bearer { "carrier_id": 1, "warehouse_id": 10, "data": [ { "carrier_reference_number": "TRK1", "ref": "REF1", "recipient_phone": "+14165550123", "recipient_email": "r@example.com" } ] } ``` ```graphql mutation($carrierId: Int!, $warehouseId: Int, $packages: Json) { submitCarrierPackages(carrierId: $carrierId, warehouseId: $warehouseId, packages: $packages) } ``` - Hitelesítés: a szokásos Bearer token. Az ügyfélfiókoknak fuvarozói feltöltési engedéllyel kell rendelkezniük (fuvarozó + raktár); a client, employee és partner fiókok a saját raktári hatókörüket használják. - Csomagonként: member_number és/vagy carrier_reference_number a fuvarozó beállításai szerint; opcionálisan carrier_order_id, batch, ref, grid_code (csak személyzet), recipient_phone, recipient_email. - A válasz minden sora visszaad egy pickup_code értéket; ugyanezt a kódot kapja meg a címzett az átvételi értesítésben. A címzett elérhetőségét titkosítva tároljuk, és soha nem küldjük vissza. Ha telefon és e-mail is meg van adva, mindkét csatorna értesítést kap; a telefon/e-mail elsőbbséget élvez a tagsági kötéshez tartozó alkalmazáson belüli értesítéssel szemben. ## Kompatibilitási ígéret Lásd a változáskezelési szabályzatot: kizárólag additív válaszok, új végpontok a régiek mellett, a webhook-törzsek alapértelmezés szerint befagyasztva, az alapértelmezések sosem változnak, a kivezetéseket legalább 30 nappal előre bejelentjük `Deprecation` / `Sunset` fejlécekkel. Ezeket a garanciákat minden kiadásnál automatizált, bájtszintű kompatibilitási tesztek kényszerítik ki.