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"
}
}'
<?php
$payload = [
'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',
],
];
$ch = curl_init('https://it.icecoldtrans.cz/api/v1/shipments');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('ICECOLD_TOKEN'),
'Content-Type: application/json',
'Idempotency-Key: obj-2026-1184',
],
CURLOPT_POSTFIELDS => json_encode($payload, JSON_UNESCAPED_UNICODE),
]);
$response = json_decode((string) curl_exec($ch), true, 512, JSON_THROW_ON_ERROR);
echo $response['number']; // ICE-2619-4471
echo $response['label_url']; // PDF štítek 100 × 150 mm
const res = await fetch('https://it.icecoldtrans.cz/api/v1/shipments', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.ICECOLD_TOKEN}`,
'Content-Type': 'application/json',
'Idempotency-Key': 'obj-2026-1184',
},
body: JSON.stringify({
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',
},
}),
});
if (!res.ok) throw new Error(`ICECOLD API: ${res.status}`);
const shipment = await res.json();
console.log(shipment.number, shipment.tracking_url);
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
| Pole | Typ | Popis |
|---|---|---|
reference | string | Vaše číslo objednávky, vrací se ve všech událostech. |
mode | enum | chilled (1–5 °C) nebo frozen (−18 °C). |
date | date | Datum doručení ve formátu YYYY-MM-DD. |
delivery.name | string | Příjemce zásilky. |
delivery.street | string | Ulice a číslo. |
delivery.city | string | Město doručení. |
delivery.zip | string | PSČ; slouží k ověření doručovací oblasti. |
pieces | integer | Počet kusů, 1–99. |
weight | number | Hmotnost 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
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.
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
/shipments
Založí novou zásilku
Vrací 201 Created s číslem zásilky. Povinná pole najdete v rychlém startu.
/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.
/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
| Stav | Význam |
|---|---|
planned | Zásilka přijata, čeká na naložení. |
loaded | Naloženo v depu, známe teplotu při nakládce. |
in_transit | Na trase, platí doručovací okno. |
delivered | Doručeno příjemci. |
delayed | Zpoždění, nové okno je v poli window. |
returned | Vrací se do depa, důvod v poli reason. |
05 · Štítek
Štítek 100 × 150 mm
/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
/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í
/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
/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álost | Kdy dorazí |
|---|---|
shipment.created | Zásilka byla přijata do systému a naplánována. |
shipment.loaded | Zásilka je naložena v depu, přiložena teplota při nakládce. |
shipment.delivered | Doručeno příjemci, včetně jména přejímajícího a teploty. |
shipment.delayed | Změna doručovacího okna nebo zpoždění na trase. |
shipment.returned | Zásilka se vrací zpět do depa, důvod je v payloadu. |
temperature.alert | Odchylka 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í.
| HTTP | Typ | Kdy |
|---|---|---|
400 | invalid_request | Chybný JSON nebo chybějící povinné pole. |
401 | unauthorized | Chybí nebo vypršel přístupový token. |
403 | forbidden | Klíč nemá oprávnění pro danou operaci. |
404 | not_found | Zásilka nebo zdroj neexistuje. |
409 | duplicate_number | Stejné číslo zásilky už v systému je. |
422 | validation_failed | Hodnota neprošla validací, detail je v `errors`. |
429 | rate_limited | Překročen limit požadavků, respektujte `Retry-After`. |
500 | server_error | Chyba 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
/api/v1/…, staré verze běží 12 měsíců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.