# Průvodce novinkami integrace Každá níže uvedená změna je striktně aditivní: stávající endpointy, pole odpovědí, HTTP stavové kódy, bajty payloadů webhooků i starší hlavička `Signature` zůstávají beze změny. Integrace, které neudělají nic, fungují přesně jako dosud. Každou funkci si osvojte nezávisle, v libovolném pořadí. Poskytováno živě na adrese https://api.superlabel.ca/api/documentation/integration-updates?lang=cs (`?download=1` pro uložení). Doprovodné dokumenty: OpenAPI (https://api.superlabel.ca/api/documentation?lang=cs), kolekce Postman (https://api.superlabel.ca/api/documentation/postman-collection), slovník a tok stavů (https://api.superlabel.ca/api/documentation/order-status-flow?lang=cs). --- ## 1. Stornování podle sledovacího čísla (idempotentní) `POST https://api.superlabel.ca/api/v1/orders/cancel` — zadejte právě jedno z `order_id`, `tracking_number`, `external_tracking_number`. ```json POST /api/v1/orders/cancel Authorization: Bearer { "external_tracking_number": "WP1234567890" } ``` - Úspěch: `200 {"result":true,"id":123456,"already_cancelled":false,...}` - Již stornováno (bezpečné opakování): `200` s `"already_cancelled": true` - Číslo odpovídá několika aktivním objednávkám: `409` s `"matched_order_ids": [...]` — opakujte s `order_id`. - Starší `GET /v1/orders/{orderId}/cancel` zůstává beze změny. ## 2. Inkrementální rekonciliační feedy Projděte vše, co se v daném okně změnilo; díky kurzorovému stránkování žádný záznam nevynecháte ani nezapočítáte dvakrát. - `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?...` `updated_from` / `updated_to` přijímají unixové časové razítko nebo řetězce `Y-m-d H:i:s` v časovém pásmu platformy. Následujte `next_cursor`, dokud `has_more` není false; porovnávejte s unixovými poli `*_timestamp`, nikdy s řetězci v lokálním čase. Položky sledovacích událostí obsahují `occurred_at` / `occurred_timestamp` (čas skutečné obchodní události; u historických záznamů se rovná času vytvoření). ## 3. Strojově čitelné chybové kódy a trasování požadavků Často používané chybové odpovědi při vytváření/stornování nyní vedle nezměněného `message` nesou stabilní pole `code`: `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`. Kódy jsou stabilní identifikátory — mohou se objevit nové, stávající nikdy nemění význam. Každá API odpověď zároveň vrací `X-Request-ID`; uveďte jej při hlášení problému. ## 4. Vylepšení detekce duplicit S `auto_deduplication=1` obsahují záznamy `exist_package_ref` / `exist_external_tracking_number` blokovaného vytvoření nyní také existující `order_id` a `order_ref` a obálka nese `"duplicate": true`. Volitelný striktní režim: pošlete `strict_duplicate_check=1` a obdržíte HTTP `409` místo staršího `200` + `result:false` (vynecháním příznaku zachováte původní chování). ## 5. Možnosti dávkového vytváření - `per_order_transaction: 1` (na nejvyšší úrovni těla dávky): každá objednávka se potvrzuje nezávisle — jedno selhání již nevrátí zpět ostatní. Pokud se zpracování předčasně přeruší, stále obdržíte řádky za vše, co bylo dokončeno, plus závěrečný řádek `{"result":false,"batch_aborted":true}`. - Dávky nad 100 objednávek obdrží informativní hlavičku odpovědi `X-Batch-Size-Warning`; pro velké objemy upřednostněte `POST /v1/client/batchOrderCreateAsync`. ## 6. Synchronizace souborů dokladu o doručení Položky `proofs[]` ve sledovacích odpovědích nyní navíc obsahují: ```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 } ``` Používejte `file_id` jako klíč pro deduplikaci / inkrementální synchronizaci. `signed_url` je expirující odkaz (7 dní) — po vypršení si nový vyžádejte opětovným dotazem na sledování. Trvalé odkazy `url` / `full_url` zůstávají beze změny. ## 7. Webhooky: hlavičky podpisu v2 (všechna doručení) Každý webhook nyní NAVÍC posílá, vedle nezměněné starší hlavičky `Signature`: | Hlavička | Význam | |---|---| | `X-Webhook-Event-Id` | UUID, stabilní napříč opakováními — používejte k deduplikaci | | `X-Webhook-Timestamp` | unixové sekundy prvního odeslání | | `X-Webhook-Signature-V2` | HMAC-SHA256 z `"."` | Ověření (libovolný jazyk): `expected = HMAC_SHA256(timestamp + "." + raw_body, your_secret)`; porovnejte s hlavičkou v konstantním čase. Časové razítko je zafixováno při prvním odeslání a znovu použito při opakováních (opakování mohou běžet až ~3 hodiny), proto kombinujte velkorysé toleranční okno s deduplikací podle `X-Webhook-Event-Id`, místo přísného limitu proti replay útokům. Vaše stávající ověřování starší hlavičky `Signature` funguje beze změny — na v2 přejděte, kdykoli budete chtít. Oba podpisy si můžete otestovat proti svému endpointu na stránce průvodce webhooky (`/webhooks-guide`). ## 8. Webhooky: volitelná obálka payloadu Nastavte `webhook_payload_envelope = 1` v nastavení webhooků a v JSON těle událostí objektového tvaru obdržíte: `event_id`, `event_time` (ISO8601 s posunem), `event_timestamp` (unix), a tam, kde to dává smysl — `is_correction: true` (dříve doručená/předaná objednávka se vrátila do toku) a `occurred_at` / `occurred_timestamp` u sledovacích událostí. Bez tohoto příznaku zůstává váš payload bajt po bajtu shodný jako dříve. Payloady ve tvaru seznamu (`order.create_async`) se nikdy nemění. ## 9. Nové webhookové události (volitelné URL) - `pod.files_updated` — fotografie/podpis z doručení byly dodatečně přidány nebo odebrány. Nakonfigurujte `pod_files_webhook_url`. Payload: `{"action":"added|removed","order_id":...,"order_ref":..., "tracking_number":[...],"external_tracking_number":[...], "file":{"file_id":...,"type":1|2,"note":null}, "event_id":..., ...}` - `order.deleted` — objednávka byla trvale smazána. Nakonfigurujte `order_deleted_webhook_url`. Payload: `{"action":"deleted","order_id":..., "order_ref":...,"tracking_number":[...],"external_tracking_number":[...], "event_id":..., ...}` Obě události vždy obsahují pole obálky a odesílají se pouze tehdy, je-li jejich URL nakonfigurována. ## 10. Webhooky: možnosti doručování - **Více endpointů na událost**: každé nastavení URL webhooku přijímá jednu URL (jako dosud), seznam oddělený čárkami nebo JSON pole. Každý endpoint má vlastní cyklus doručení a opakování. - **Ověřování TLS**: nastavte `webhook_verify_ssl = 1`, aby odchozí volání ověřovala váš certifikát. Výchozí zůstává vypnuto (historické chování). - **order.created pro všechny typy objednávek**: nastavte `order_created_webhook_all_types = 1` a rozšíříte událost vytvoření objednávky i mimo objednávky lokálního doručení. Výchozí zachovává historický rozsah. - **Podpisové tajné klíče**: nová nastavení obdrží silný náhodný tajný klíč; stávající klíče se nikdy automaticky nerotují. ## 11. Rozsahy API tokenů a povolené IP adresy (volitelné) Jednotlivé tokeny lze omezit na `orders:read`, `orders:write` a/nebo `webhooks:manage` a na seznam povolených IP adres. Neomezené tokeny (výchozí stav a všechny dříve existující tokeny) se chovají přesně jako dosud. Omezený token volající mimo své rozsahy/IP adresy obdrží `403`. Pro omezení tokenu kontaktujte podporu. ## 12. Odeslání balíků dopravce (Smart Locker) Externí dopravci odesílají balíky do přípravné zóny skladu jedním dávkovým voláním. Volitelně lze připojit telefon/e-mail příjemce, aby byl příjemce upozorněn kódem k vyzvednutí, jakmile je balík vložen do chytré skříňky. Pole příjemce jsou volitelná — endpoint zůstává zpětně kompatibilní. ```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) } ``` - Autentizace: token Bearer jako obvykle. Zákaznické účty musí mít oprávnění k nahrávání dopravce (dopravce + sklad); účty client, employee a partner používají vlastní rozsah skladu. - Na balík: member_number a/nebo carrier_reference_number podle nastavení dopravce; volitelně carrier_order_id, batch, ref, grid_code (pouze personál), recipient_phone, recipient_email. - Každý řádek odpovědi vrací pickup_code; stejný kód je doručen příjemci v oznámení o vyzvednutí. Kontakt příjemce je uložen šifrovaně a nikdy se nevrací. Když jsou zadány telefon i e-mail, jsou upozorněny oba kanály; telefon/e-mail mají přednost před oznámením v aplikaci přes členské propojení. ## Příslib kompatibility Viz zásady řízení změn: pouze aditivní odpovědi, nové endpointy vedle starých, těla webhooků ve výchozím stavu zmrazena, výchozí hodnoty se nikdy nemění, vyřazení oznámena nejméně 30 dní předem s hlavičkami `Deprecation` / `Sunset`. Tyto záruky jsou vynucovány automatizovanými testy kompatibility na úrovni bajtů při každém vydání.