FurtodoBox je český výrobce modulárních výdejních a doručovacích boxů. Boxy vyrábíme v Ostravě a aplikaci, která je řídí, vyvíjí náš vlastní tým. Díky tomu umí každý box komunikovat s okolním světem — dá se propojit s e-shopem, skladem nebo firemním (ERP) systémem, ať jedete na Pohodě, Heliosu, Money, ABRA, SAP nebo Microsoft Dynamics, případně s knihovním softwarem. Této komunikační vrstvě se technicky říká API a je to přesně to, co z boxu dělá plnohodnotnou součást vaší infrastruktury, ne izolovaný ostrov.
Co to znamená v praxi
Představte si, že vyřídíte objednávku. Váš systém v ten okamžik sám řekne boxu, že má připravit zásilku pro konkrétního zákazníka. Box si vyhradí schránku a vygeneruje přístupový kód. Zákazníkovi se odešle upozornění s kódem, on si zásilku kdykoliv vyzvedne — a váš systém se o tom hned dozví, aniž by se musel kohokoliv ptát.
Celý oběh zásilky se tak uzavře automaticky:
- Váš systém zadá boxu úkol — připrav zásilku, přijmi reklamaci, rezervuj schránku.
- Box si poradí se zákazníkem — vydá přístupový kód a může se postarat i o e-mail a SMS, klidně v jazyce zákazníka.
- Box vám sám hlásí, co se stalo — zásilka připravena, vyzvednuta, vrácena, zaplacena. Nemusíte nic hlídat ani opisovat.
Výsledkem je provoz bez ručního přepisování dat mezi systémy a bez papírků s kódy. Ušetříte čas personálu a omezíte chyby, které ruční zadávání vždycky přináší.
Že to funguje, není teorie
Takhle už dnes fungují třeba knihovny. Knihovní systémy Koha a Tritius komunikují s našimi boxy napřímo — čtenář si rezervuje knihu ve svém katalogu, systém založí výpůjčku do boxu a čtenář dostane kód k vyzvednutí. Knihovník přitom nemusí u boxu udělat jediný úkon navíc.
Stejný princip využijí e-shopy a výdejní místa, autoservisy s předáváním klíčů (KeyBox) nebo firmy, které si přes box předávají zásilky a dokumenty mezi sebou.
A teď konkrétně pro vaše vývojáře
Pokud vás zajímá, jak náročné je box napojit, dobrá zpráva: opravdu málo. API je standardní REST nad HTTPS, data ve formátu JSON, ověření probíhá dvojicí hlaviček X-API-KEY a X-API-SECRET, které vám vygenerujeme. K dispozici je i testovací prostředí (https://sandbox.moje.furtodoit.com/api), kde si vše odladíte bez dopadu na ostrý provoz.
Co API umí
- Založení zásilky k vyzvednutí
- Rezervace schránky
- Zjištění stavu zásilky
- Historie událostí zásilky
- Zrušení zásilky
- Prodloužení doby vyzvednutí
- Přehled volné kapacity boxu
- Seznam boxů
- Seznam dopravců
- Webhooky událostí (podepsané HMAC‑SHA256)
Založení zásilky k vyzvednutí je jediný požadavek. V curl to vypadá takto:
curl -X POST https://moje.furtodo.com/api/v1/consignments/delivery \
-H "X-API-KEY: vas_api_klic" \
-H "X-API-SECRET: vas_api_secret" \
-H "Content-Type: application/json" \
-d '{
"destinationBoxId": "5e8f000c-3be7-4c1b-8a2b-365b0657c835",
"externalOrderNumber": "OBJ-2026-0042",
"expirationInDays": 5,
"recipient": { "name": "Jan", "surname": "Novák" },
"pickUpContact": {
"email": "jan.novak@example.cz",
"phone": "+420602123456",
"preferredLanguage": "cs"
}
}'Totéž v PHP — žádná knihovna navíc, stačí běžné cURL rozšíření:
<?php
$payload = json_encode([
'destinationBoxId' => '5e8f000c-3be7-4c1b-8a2b-365b0657c835',
'externalOrderNumber' => 'OBJ-2026-0042',
'expirationInDays' => 5,
'recipient' => ['name' => 'Jan', 'surname' => 'Novák'],
'pickUpContact' => [
'email' => 'jan.novak@example.cz',
'phone' => '+420602123456',
'preferredLanguage' => 'cs',
],
]);
$ch = curl_init('https://moje.furtodo.com/api/v1/consignments/delivery');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => $payload,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
'X-API-KEY: ' . getenv('FURTODO_API_KEY'),
'X-API-SECRET: ' . getenv('FURTODO_API_SECRET'),
],
]);
$consignment = json_decode(curl_exec($ch), true);
// $consignment['pins'] obsahuje kód pro vložení (type 1) a pro vyzvednutí (type 2)Box v odpovědi rovnou vrátí identifikátor zásilky a přístupové kódy — jeden pro vložení obsluhou, druhý pro vyzvednutí zákazníkem:
{
"id": "4b223472-15c6-41c1-9146-f321db96a87a",
"status": 1,
"externalOrderNumber": "OBJ-2026-0042",
"pins": [
{ "code": "111111", "type": 1 },
{ "code": "222222", "type": 2 }
]
}Do pole externalOrderNumber si vložíte vlastní číslo objednávky, takže si zásilku v boxu kdykoliv spárujete se záznamem ve svém systému.
Box vás upozorní sám (webhooky)
Aby vše běželo na pozadí, nemusíte se stavu zásilky ptát dokola. Zaregistrujete u nás svůj HTTPS endpoint a my na něj pošleme oznámení pokaždé, když nastane událost — zásilka připravena, vyzvednuta, vrácena, zrušena nebo zaplacena. Každé oznámení je podepsané (HMAC‑SHA256 v hlavičce X-API-SIGNATURE), takže si ověříte, že přišlo opravdu od nás:
<?php
$body = file_get_contents('php://input');
$signature = hash_hmac('sha256', $body, getenv('FURTODO_WEBHOOK_SECRET'));
if (!hash_equals($signature, $_SERVER['HTTP_X_API_SIGNATURE'] ?? '')) {
http_response_code(401);
exit;
}
$event = json_decode($body, true);
// $event['type'] === 1 → zásilka připravena k vyzvednutí
// $event['data']['consignmentId'] → kterou zásilku se to týká
http_response_code(200);A to je v jádru celé. Kompletní přehled endpointů (čtení stavu, historie událostí, zrušení či prodloužení zásilky, volná kapacita boxu, seznam dopravců) najdete v dokumentaci na moje.furtodo.com/docs/api.
Řešíte konkrétní nasazení? Ozvěte se nám — projdeme s vámi, jak box zapadne do vašich procesů, a přístupy do sandboxu i produkce připravíme.
Typické využití API
- E-shop — automatické vydání objednávky zákazníkovi.
- Autoservis — předání klíčů od vozu po servisu.
- Knihovna — výdej rezervovaných knih.
- Interní logistika — předávání dokumentů a zásilek mezi pobočkami.
Časté dotazy
Jak se výdejní box FurtodoBox napojí na e-shop nebo firemní systém?
Přes standardní REST API nad HTTPS. Váš systém pošle boxu požadavek, například založení zásilky k vyzvednutí, data se předávají ve formátu JSON a požadavek se ověřuje dvojicí hlaviček X-API-KEY a X-API-SECRET. Box v odpovědi vrátí identifikátor zásilky a přístupové PIN kódy. Speciální knihovna není potřeba, stačí běžný HTTP klient.
Podporuje FurtodoBox API webhooky?
Ano. Zaregistrujete svůj HTTPS endpoint a box na něj sám odešle oznámení při každé události — zásilka připravena, vyzvednuta, vrácena, zrušena nebo zaplacena. Každé oznámení je podepsané pomocí HMAC‑SHA256 v hlavičce X-API-SIGNATURE, takže si ověříte jeho pravost. Stav zásilky se tak nemusíte opakovaně dotazovat.
Existuje testovací prostředí pro vývojáře?
Ano. K dispozici je oddělený sandbox, ve kterém integraci odladíte bez dopadu na ostrý provoz. Přístupy do sandboxu i do produkce vám vygenerujeme na vyžádání.
S jakými systémy už FurtodoBox spolupracuje?
Boxy jsou napřímo propojené například s knihovními systémy Koha a Tritius — čtenář si rezervuje knihu a systém sám založí výpůjčku do boxu. Stejný princip využívají e-shopy a výdejní místa, autoservisy s předáváním klíčů (KeyBox) i firmy, které si přes box předávají zásilky a dokumenty.
Kde najdu technickou dokumentaci API?
Kompletní dokumentaci najdete na moje.furtodo.com/docs/api.