REST API · verze v1

ICECOLD API

JSON API pro zásilky, štítky, teplotní protokoly a stav doručení. Ověření tokenem, idempotentní vytváření zásilek a webhooky pro všechno, co se na trase stane.

  • Base URLhttps://it.icecoldtrans.cz/api/v1
  • FormátJSON UTF-8
  • Sandboxhttps://it.icecoldtrans.cz/sandbox/v1

01 · Začátek

Rychlý start

Zásilku založíte jedním požadavkem. Číslo ICE-XXXX-XXXX vám vrátíme v odpovědi a použijete ho pro štítek, sledování i webhooky.

curl -X POST https://it.icecoldtrans.cz/api/v1/shipments \
  -H "Authorization: Bearer $ICECOLD_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: obj-2026-1184" \
  -d '{
    "reference": "OBJ-2026-1184",
    "mode": "chilled",
    "date": "2026-11-24",
    "window": "08:00-12:00",
    "pieces": 3,
    "weight": 12.4,
    "delivery": {
      "name": "Petra Dvořáková",
      "street": "Vršovická 1184/32",
      "city": "Praha 10",
      "zip": "100 00",
      "phone": "+420604118972"
    }
  }'

Odpověď 201 Created

{
  "number": "ICE-2619-4471",
  "status": "planned",
  "mode": "chilled",
  "date": "2026-11-24",
  "window": "08:00-12:00",
  "label_url": "https://it.icecoldtrans.cz/api/v1/shipments/ICE-2619-4471/label",
  "tracking_url": "https://icecoldtrans.cz/?z=ICE-2619-4471",
  "created_at": "2026-11-21T09:14:02+01:00"
}

Povinná pole při vytvoření zásilky

PoleTypPopis
referencestringVaše číslo objednávky, vrací se ve všech událostech.
modeenumchilled (1–5 °C) nebo frozen (−18 °C).
datedateDatum doručení ve formátu YYYY-MM-DD.
delivery.namestringPříjemce zásilky.
delivery.streetstringUlice a číslo.
delivery.citystringMěsto doručení.
delivery.zipstringPSČ; slouží k ověření doručovací oblasti.
piecesintegerPočet kusů, 1–99.
weightnumberHmotnost v kg.

02 · Bezpečnost

Autentizace

Každý požadavek posílá token v hlavičce Authorization. Token je vázaný na firmu a prostředí — sandboxový token nikdy nefunguje v produkci a naopak.

Authorization: Bearer $ICECOLD_TOKEN
Content-Type: application/json
Accept: application/json
Token nikdy neposílejte do prohlížeče.

Volání API patří na server. Pokud potřebujete sledování pro zákazníka, použijte veřejný endpoint /tracking/{number}, který klíč nevyžaduje.

Idempotence

U vytváření zásilky posílejte hlavičku Idempotency-Key s číslem objednávky. Opakovaný požadavek se stejným klíčem do 24 hodin vrátí původní zásilku místo duplicity.

03 · Vývoj

Sandbox

Testovací prostředí má stejné endpointy i chování jako produkce, ale vlastní databázi. Zásilky v něm nikam nejedou a nikomu nechodí e-maily ani SMS.

Base URLhttps://it.icecoldtrans.cz/sandbox/v1
Cenazdarma, bez omezení počtu zásilek
Datamažeme po 30 dnech nečinnosti
Resetna vyžádání e-mailem podpoře

Sandboxový token dostanete e-mailem obvykle do hodiny. Do testovacích zásilek můžete posílat libovolná jména i adresy — validace PSČ zůstává stejná jako v produkci.

04 · Zásilky

Zásilky

POST /shipments Založí novou zásilku

Vrací 201 Created s číslem zásilky. Povinná pole najdete v rychlém startu.

GET /shipments Seznam zásilek

Filtry: status, date_from, date_to, reference, per_page (max. 100). Stránkování přes page a hlavičky Link.

GET /shipments/{number} Detail zásilky

Vrací zásilku včetně časové osy, přiřazeného vozu, řidiče a uložených teplot.

Stavy zásilky

StavVýznam
plannedZásilka přijata, čeká na naložení.
loadedNaloženo v depu, známe teplotu při nakládce.
in_transitNa trase, platí doručovací okno.
deliveredDoručeno příjemci.
delayedZpoždění, nové okno je v poli window.
returnedVrací se do depa, důvod v poli reason.

05 · Štítek

Štítek 100 × 150 mm

GET /shipments/{number}/label PDF štítek

Vrací PDF připravené pro termotisk. Volitelný parametr format=zpl vrátí ZPL pro Zebra tiskárny.

curl -L https://it.icecoldtrans.cz/api/v1/shipments/ICE-2619-4471/label \
  -H "Authorization: Bearer $ICECOLD_TOKEN" \
  -o stitek-ICE-2619-4471.pdf

06 · Teploty

Teplotní protokol

GET /shipments/{number}/temperatures Měření z přepravy

Vrací všechna měření včetně odchylek a času doručení. Data jsou připravená k párování s HACCP deníkem.

{
  "number": "ICE-2619-4471",
  "mode": "chilled",
  "min": 2.9,
  "max": 4.6,
  "readings": [
    { "at": "2026-11-24T06:42:00+01:00", "celsius": 3.1, "zone": "chilled" },
    { "at": "2026-11-24T07:18:00+01:00", "celsius": 2.9, "zone": "chilled" }
  ]
}

07 · Sledování

Veřejné sledování

GET /tracking/{number} Bez API klíče

Endpoint pro vaše zákazníky. Vrací stav, doručovací okno a jméno řidiče — nic víc, co by prozradilo interní data. Odkaz můžete vložit do e-mailu po odeslání objednávky.

08 · Události

Webhooky

POST /webhooks Registrace odběru

Zaregistrujete URL a seznam událostí. Doručujeme do 60 sekund, při neúspěchu opakujeme 5× s rostoucím odstupem.

UdálostKdy dorazí
shipment.createdZásilka byla přijata do systému a naplánována.
shipment.loadedZásilka je naložena v depu, přiložena teplota při nakládce.
shipment.deliveredDoručeno příjemci, včetně jména přejímajícího a teploty.
shipment.delayedZměna doručovacího okna nebo zpoždění na trase.
shipment.returnedZásilka se vrací zpět do depa, důvod je v payloadu.
temperature.alertOdchylka od zvoleného režimu 1–5 °C nebo −18 °C.

Ověření podpisu

Každý požadavek nese hlavičky X-ICECOLD-Signature a X-ICECOLD-Timestamp. Podpis je HMAC-SHA256 z těla požadavku a tajemství, které dostanete při registraci. Od 1. 12. 2026 je ověření povinné.

$raw = file_get_contents('php://input');
$expected = hash_hmac(
    'sha256',
    $_SERVER['HTTP_X_ICECOLD_TIMESTAMP'] . '.' . $raw,
    $webhookSecret
);

if (!hash_equals($expected, $_SERVER['HTTP_X_ICECOLD_SIGNATURE'] ?? '')) {
    http_response_code(401);
    exit;
}

Ukázka payloadu

{
  "event": "shipment.delivered",
  "id": "evt_8f21c4",
  "created_at": "2026-11-24T11:42:10+01:00",
  "data": {
    "number": "ICE-2619-4471",
    "reference": "OBJ-2026-1184",
    "status": "delivered",
    "delivered_at": "2026-11-24T11:42:00+01:00",
    "received_by": "M. Dvořáková",
    "temperature_c": 3.2
  }
}

Každou událost berte jako idempotentní — stejné id může dorazit opakovaně. Události si můžete přehrát i ručně v klientském portálu.

09 · Chyby

Chybové stavy

Chyby vracíme s poli error.type, error.message a u validace i s polem errors podle jednotlivých polí.

HTTPTypKdy
400invalid_requestChybný JSON nebo chybějící povinné pole.
401unauthorizedChybí nebo vypršel přístupový token.
403forbiddenKlíč nemá oprávnění pro danou operaci.
404not_foundZásilka nebo zdroj neexistuje.
409duplicate_numberStejné číslo zásilky už v systému je.
422validation_failedHodnota neprošla validací, detail je v `errors`.
429rate_limitedPřekročen limit požadavků, respektujte `Retry-After`.
500server_errorChyba na naší straně, bezpečně opakujte požadavek.
{
  "error": {
    "type": "validation_failed",
    "message": "Pole delivery.zip nepatří do doručovací oblasti.",
    "errors": { "delivery.zip": "unsupported_area" }
  }
}

10 · Provoz

Limity a verze

120 požadavků / minna jeden API klíč
Max. 100 položekna stránku seznamu
Verzování v URL/api/v1/…, staré verze běží 12 měsíců
Změnyoznamujeme e-mailem a v novinkách

Při překročení limitu vracíme 429 s hlavičkou Retry-After. Doporučujeme exponenciální odstup a respektování hlavičky, ne okamžité opakování.

Něco v dokumentaci chybí?

Napište nám. Dokumentaci píšeme podle toho, s čím se u napojení skutečně potýkáte.

Napsat podpoře