# Sprievodca aktualizáciami integrácie

Každá zmena nižšie je striktne aditívna: existujúce endpointy, polia odpovedí, HTTP stavové kódy, bajty webhook payloadov aj starší hlavičkový `Signature` zostávajú nezmenené. Integrácie, ktoré neurobia nič, fungujú presne ako doteraz. Každú funkciu môžete zaviesť nezávisle, v ľubovoľnom poradí.

Poskytované naživo na adrese https://api.superlabel.ca/api/documentation/integration-updates?lang=sk (`?download=1` na uloženie). Sprievodné dokumenty: OpenAPI (https://api.superlabel.ca/api/documentation?lang=sk), Postman kolekcia (https://api.superlabel.ca/api/documentation/postman-collection), slovník stavov a tok (https://api.superlabel.ca/api/documentation/order-status-flow?lang=sk).

---

## 1. Zrušenie podľa sledovacieho čísla (idempotentné)

`POST https://api.superlabel.ca/api/v1/orders/cancel` — zadajte práve jedno z `order_id`, `tracking_number`, `external_tracking_number`.

```json
POST /api/v1/orders/cancel
Authorization: Bearer <token>
{ "external_tracking_number": "WP1234567890" }
```

- Úspech: `200 {"result":true,"id":123456,"already_cancelled":false,...}`
- Už zrušené (bezpečné opakovanie): `200` s `"already_cancelled": true`
- Číslo zodpovedá viacerým aktívnym objednávkam: `409` s `"matched_order_ids": [...]` — zopakujte s `order_id`.
- Starší `GET /v1/orders/{orderId}/cancel` zostáva nezmenený.

## 2. Inkrementálne rekonciliačné feedy

Prejdite všetko, čo sa zmenilo v danom okne; vďaka kurzorovej paginácii nikdy nevynecháte ani nezapočítate záznam 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` akceptujú unixové časové pečiatky alebo reťazce `Y-m-d H:i:s` v časovom pásme platformy. Nasledujte `next_cursor`, kým `has_more` nie je false; porovnávajte s unixovými poľami `*_timestamp`, nikdy s reťazcami lokálneho času. Položky sledovacích udalostí obsahujú `occurred_at` / `occurred_timestamp` (čas obchodného výskytu; pri historických záznamoch sa rovná času vytvorenia).

## 3. Strojovo čitateľné chybové kódy a trasovanie požiadaviek

Vysokofrekvenčné chybové odpovede pri vytváraní/rušení teraz nesú stabilné pole `code` popri nezmenenom `message`:
`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 sú stabilné identifikátory — môžu pribudnúť nové, existujúce nikdy nemenia význam. Každá odpoveď API navyše vracia `X-Request-ID`; uveďte ho pri nahlasovaní problému.

## 4. Vylepšenia detekcie duplicít

S `auto_deduplication=1` teraz položky `exist_package_ref` / `exist_external_tracking_number` zablokovaného vytvorenia obsahujú existujúce `order_id` a `order_ref` a obálka nesie `"duplicate": true`. Voliteľný striktný režim: pošlite `strict_duplicate_check=1` a namiesto staršieho `200` + `result:false` dostanete HTTP `409` (vynechajte príznak, ak chcete zachovať pôvodné správanie).

## 5. Možnosti dávkového vytvárania

- `per_order_transaction: 1` (najvyššia úroveň tela dávky): každá objednávka sa zapíše nezávisle — jedno zlyhanie už nevráti späť ostatné. Ak sa spracovanie predčasne preruší, stále dostanete riadky za všetko dokončené plus záverečný riadok `{"result":false,"batch_aborted":true}`.
- Dávky s viac než 100 objednávkami dostanú informatívnu hlavičku odpovede `X-Batch-Size-Warning`; pre veľké objemy uprednostnite `POST /v1/client/batchOrderCreateAsync`.

## 6. Synchronizácia súborov dokladov o doručení

Položky `proofs[]` v sledovacích odpovediach teraz navyše 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žite `file_id` ako kľúč pre deduplikáciu / inkrementálnu synchronizáciu. `signed_url` je odkaz s obmedzenou platnosťou (7 dní) — po vypršaní si znova vyžiadajte sledovanie a získajte čerstvý. Trvalé odkazy `url` / `full_url` zostávajú nezmenené.

## 7. Webhooky: hlavičky podpisu v2 (všetky doručenia)

Každý webhook teraz NAVYŠE posiela, popri nezmenenej staršej hlavičke `Signature`:

| Hlavička | Význam |
|---|---|
| `X-Webhook-Event-Id` | UUID, stabilné naprieč opakovaniami — použite na deduplikáciu |
| `X-Webhook-Timestamp` | unixové sekundy pri prvom odoslaní |
| `X-Webhook-Signature-V2` | HMAC-SHA256 z `"<timestamp>.<raw body>"` |

Overenie (v ľubovoľnom jazyku): `expected = HMAC_SHA256(timestamp + "." + raw_body, your_secret)`; porovnajte s hlavičkou v konštantnom čase. Časová pečiatka sa fixuje pri prvom odoslaní a opätovne sa používa pri opakovaniach (opakovania môžu bežať až ~3 hodiny), preto kombinujte veľkorysé tolerančné okno s deduplikáciou cez `X-Webhook-Event-Id` namiesto prísneho limitu proti replay útokom. Vaše existujúce overovanie staršej hlavičky `Signature` funguje bez zmeny ďalej — v2 zaveďte, kedykoľvek chcete. Oba podpisy si môžete otestovať voči svojmu endpointu zo stránky sprievodcu webhookmi (`/webhooks-guide`).

## 8. Webhooky: voliteľná obálka payloadu

Nastavte `webhook_payload_envelope = 1` vo svojich nastaveniach webhookov a v JSON tele objektovo tvarovaných udalostí dostanete: `event_id`, `event_time` (ISO8601 s posunom), `event_timestamp` (unix), plus — kde je to relevantné — `is_correction: true` (predtým doručená/odovzdaná objednávka sa vrátila do toku) a `occurred_at` / `occurred_timestamp` na sledovacích udalostiach. Bez tohto príznaku zostáva váš payload bajt po bajte identický s doterajším. Payloady v tvare zoznamu (`order.create_async`) sa nikdy nemenia.

## 9. Nové webhook udalosti (voliteľné URL)

- `pod.files_updated` — fotografia/podpis doručenia bola dodatočne pridaná alebo odstránená. 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 bola natrvalo odstránená. Nakonfigurujte `order_deleted_webhook_url`. Payload: `{"action":"deleted","order_id":...,
  "order_ref":...,"tracking_number":[...],"external_tracking_number":[...],
  "event_id":..., ...}`

Obe udalosti vždy obsahujú polia obálky a posielajú sa len vtedy, keď je nakonfigurovaná ich URL.

## 10. Webhooky: možnosti doručovania

- **Viacero endpointov na udalosť**: každé nastavenie webhook URL akceptuje jednu URL (ako doteraz), zoznam oddelený čiarkami alebo JSON pole. Každý endpoint má vlastný cyklus doručovania a opakovaní.
- **Overovanie TLS**: nastavte `webhook_verify_ssl = 1`, aby odchádzajúce volania overovali váš certifikát. Predvolene zostáva vypnuté (historické správanie).
- **order.created pre všetky typy objednávok**: nastavte `order_created_webhook_all_types = 1`, ak chcete udalosť vytvorenia objednávky rozšíriť aj mimo objednávok lokálneho doručenia. Predvolené nastavenie zachováva historický rozsah.
- **Podpisové tajomstvá**: prvé nastavenie dostane silné náhodné tajomstvo; existujúce tajomstvá sa nikdy automaticky nerotujú.

## 11. Rozsahy API tokenov a zoznamy povolených IP (voliteľné)

Jednotlivé tokeny možno obmedziť na `orders:read`, `orders:write` a/alebo `webhooks:manage` a na zoznam povolených IP adries. Neobmedzené tokeny (predvolené nastavenie a všetky doterajšie tokeny) sa správajú presne ako doteraz. Obmedzený token volajúci mimo svojich rozsahov/IP dostane `403`. O obmedzenie tokenu požiadajte podporu.

## 12. Odoslanie balíkov dopravcu (Smart Locker)

Externí dopravcovia odosielajú balíky do prípravnej zóny skladu jedným dávkovým volaním. Voliteľne možno pripojiť telefón/e-mail príjemcu, aby bol príjemca upozornený kódom na vyzdvihnutie hneď po vložení balíka do inteligentnej skrinky. Polia príjemcu sú voliteľné — endpoint zostáva spätne kompatibilný.

```json
POST https://api.superlabel.ca/api/v1/inventories/carrier-staging-stockin
Authorization: Bearer <token>
{ "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)
}
```

- Autentifikácia: token Bearer ako zvyčajne. Zákaznícke účty musia mať oprávnenie na nahrávanie dopravcu (dopravca + sklad); účty client, employee a partner používajú vlastný rozsah skladu.
- Na balík: member_number a/alebo carrier_reference_number podľa nastavení dopravcu; voliteľne carrier_order_id, batch, ref, grid_code (len personál), recipient_phone, recipient_email.
- Každý riadok odpovede vráti pickup_code; rovnaký kód sa doručí príjemcovi v oznámení o vyzdvihnutí.

Kontakt príjemcu sa ukladá šifrovane a nikdy sa nevracia. Ak sú zadané telefón aj e-mail, upozornia sa oba kanály; telefón/e-mail majú prednosť pred upozornením v aplikácii cez členské prepojenie.

## Prísľub kompatibility

Pozrite si politiku riadenia zmien: iba aditívne odpovede, nové endpointy popri starých, telá webhookov predvolene zmrazené, predvolené hodnoty sa nikdy nemenia, ukončenia podpory oznamované minimálne 30 dní vopred s hlavičkami `Deprecation` / `Sunset`. Tieto záruky vynucujú automatizované testy kompatibility na úrovni bajtov pri každom vydaní.