Přeskočit na hlavní obsah

Synchronizace objednávek a zásilek přes API

Kompletní návod pro propojení e-shopu s Retinem. Vytváření objednávek, připojování faktur a automatické sledování zásilek.

Kryštof Řeháček avatar
Autor: Kryštof Řeháček
Aktualizováno před více než 2 měsíci

Tento návod vám ukáže, jak propojit váš e-shop s Retinem pro automatické sledování zásilek. Orders API synchronizuje objednávky a tracking data do Retina, který pak automaticky sleduje stav zásilek u dopravců.

Kompletní API dokumentaci naleznete na app.retino.com/api/docs.

Co budete potřebovat

Před začátkem si připravte:

  • API token z nastavení Retina

  • Store ID (vytvoříte tamtéž v sekci "Store IDs")

  • Možnost volat REST API z vašeho e-shopu (webhooky nebo background joby)

Jak integrace funguje

Kompletní workflow má čtyři kroky, které odpovídají životnímu cyklu objednávky:

Krok

Kdy

Co se stane

1. Vytvoření objednávky

Zákazník dokončí nákup

Objednávka se vytvoří v Retinu

2. Nahrání faktury

E-shop vygeneruje fakturu

PDF faktury se nahraje do Retina

3. Připojení faktury

Hned po nahrání

Faktura se propojí s objednávkou

4. Vytvoření zásilky

Objednávka je expedována

Retino začne sledovat tracking number

Co Orders API synchronizuje:

  • Objednávky – vytváření a aktualizace objednávek v Retinu

  • Tracking data – propojení zásilek s objednávkami

Co Retino dělá automaticky po synchronizaci:

  • Sledování zásilek – pravidelné kontroly stavu u dopravce

  • Tracking stránka – poskytuje zákazníkům aktuální stav zásilky

Co musíte nastavit samostatně:

  • Transakční e-maily – aktivujete v nastavení Retina (viz "Další kroky" níže)

Krok 1: Vytvoření objednávky

Když zákazník dokončí nákup, odešlete objednávku do Retina pomocí POST /api/v2/orders.

Minimální příklad:

curl -X POST "https://app.retino.com/api/v2/orders" \  -H "Authorization: váš_api_token" \  -H "Content-Type: application/json" \  -d '{    "code": "OBJ-2025-001",    "store_id": "vas-eshop",    "price": {"with_vat": "1599.00"},    "customer": {      "email": "[email protected]",      "phone": "+420123456789"    },    "shipping_address": {      "name": "Jan Novák",      "street": "Testovací",      "house_number": "1",      "city": "Praha",      "postal_code": "11000",      "country": "CZ"    }  }'

Odpověď obsahuje UUID objednávky:

{  "id": "550e8400-e29b-41d4-a716-446655440000",  "code": "OBJ-2025-001",  ...}

Důležité: UUID objednávky (id) si uložte – budete ho potřebovat v dalších krocích.

Kroky 2–3: Nahrání a připojení faktury

Připojení faktury probíhá ve dvou krocích, protože fakturu nejprve nahrajete a pak ji připojíte k objednávce.

2a. Nahrajte PDF faktury

curl -X POST "https://app.retino.com/api/v2/files" \  -H "Authorization: váš_api_token" \  -F "file=@faktura_OBJ-2025-001.pdf"

Odpověď:

{  "id": "7f3d5c2a-8b9e-4f1a-9d6c-3e7b2a5f8c1d",  "filename": "faktura_OBJ-2025-001.pdf",  ...}

2b. Připojte fakturu k objednávce

curl -X POST "https://app.retino.com/api/v2/orders/550e8400-e29b-41d4-a716-446655440000/documents" \  -H "Authorization: váš_api_token" \  -H "Content-Type: application/json" \  -d '{    "type": "INVOICE",    "file_id": "7f3d5c2a-8b9e-4f1a-9d6c-3e7b2a5f8c1d"  }'

Faktura je nyní připojena k objednávce.

Krok 4: Vytvoření sledované zásilky

Když expedujete zásilku a získáte tracking number od dopravce, vytvořte sledovanou zásilku pomocí POST /api/v2/tracking-shipping:

curl -X POST "https://app.retino.com/api/v2/tracking-shipping" \  -H "Authorization: váš_api_token" \  -H "Content-Type: application/json" \  -d '{    "tracking_number": "DR12345678901CZ",    "carrier_hint": "Česká pošta",    "order": "550e8400-e29b-41d4-a716-446655440000",    "delivery_type": "TO_ADDRESS"  }'

Co se stane:

  1. Retino propojí zásilku s objednávkou

  2. Automaticky detekuje dopravce (pokud není zadán carrier_hint)

  3. Začne pravidelně kontrolovat stav zásilky u dopravce

  4. Poskytne zákazníkovi tracking stránku s aktuálním stavem

Tip: Pole carrier_hint není povinné, ale pomáhá s rychlejší detekcí dopravce. Zadejte název dopravce, pokud ho znáte (např. "PPL", "DPD", "Zásilkovna").

Typy doručení

Při vytváření zásilky specifikujte typ doručení pomocí delivery_type:

  • TO_ADDRESS – doručení na adresu zákazníka

  • TO_BRANCH – vyzvednutí na pobočce (Zásilkovna, PPL ParcelShop, atd.)

Pro doručení na pobočku můžete přidat detaily výdejního místa v poli parcel_shop.

Praktické tipy pro integraci

Použijte webhooky pro automatizaci

Při vytvoření objednávky:

  1. E-shop webhook se spustí po dokončení nákupu

  2. Webhook zavolá kroky 1–3 (objednávka + faktura)

  3. Objednávka je synchronizována do Retina

Při expedici:

  1. Skladový systém webhook se spustí po vytvoření zásilky

  2. Webhook zavolá krok 4 (vytvoření tracking)

  3. Retino začne automaticky sledovat zásilku

Ukládejte si UUID objednávek

Po vytvoření objednávky v Retinu si uložte její UUID do vaší databáze. Budete ho potřebovat pro:

  • Připojení faktury

  • Vytvoření zásilky

  • Aktualizaci objednávky

Ošetřete chybové stavy

Pokud některý krok selže (např. faktura se nepodaří nahrát), můžete:

  • Objednávku vytvořit i bez faktury – faktura není povinná

  • Fakturu přidat později pomocí stejného endpointu

  • Zásilku vytvořit i bez objednávky – propojení není povinné

Časté scénáře

Scénář 1: Standardní objednávka s dopravou na adresu

Situace: Zákazník si objedná produkt s dopravou PPL na domácí adresu.

Postup:

  1. Při dokončení nákupu vytvořte objednávku (krok 1)

  2. Po vygenerování faktury ji nahrajte a připojte (kroky 2–3)

  3. Při expedici vytvořte zásilku s delivery_type: "TO_ADDRESS" (krok 4)

  4. Retino začne sledovat zásilku a poskytne tracking stránku

Scénář 2: Vyzvednutí na Zásilkovně

Situace: Zákazník si zvolil vyzvednutí na pobočce Zásilkovny.

Postup:

  1. Vytvořte objednávku standardně (krok 1)

  2. Připojte fakturu (kroky 2–3)

  3. Při expedici vytvořte zásilku s delivery_type: "TO_BRANCH"

  4. Retino sleduje, kdy je zásilka připravena k vyzvednutí

Příklad vytvoření zásilky na pobočku:

curl -X POST "https://app.retino.com/api/v2/tracking-shipping" \  -H "Authorization: váš_api_token" \  -H "Content-Type: application/json" \  -d '{    "tracking_number": "Z123456789",    "carrier_hint": "Zásilkovna",    "order": "UUID_OBJEDNAVKY",    "delivery_type": "TO_BRANCH"  }'

Scénář 3: Aktualizace stavu objednávky

Situace: Objednávka prochází sklademním procesem a chcete informovat zákazníka o postupu.

Postup:

Aktualizujte stav objednávky pomocí PATCH /api/v2/orders/{id}/status:

# Kompletace
curl -X PATCH "https://app.retino.com/api/v2/orders/UUID/status?status_value=PICKING" \  -H "Authorization: váš_api_token"

# Zabaleno
curl -X PATCH "https://app.retino.com/api/v2/orders/UUID/status?status_value=PACKED" \  -H "Authorization: váš_api_token"

# Expedováno
curl -X PATCH "https://app.retino.com/api/v2/orders/UUID/status?status_value=DISPATCHED" \  -H "Authorization: váš_api_token

Prvotní import existujících objednávek

Pokud přecházíte z jiného systému nebo začínáte s Retinem, můžete importovat historické objednávky pomocí hromadného endpointu.

Doporučený postup:

  1. Exportujte objednávky za posledních 30 měsíců z vašeho e-shopu

  2. Pro každou objednávku s tracking number vytvořte i zásilku

  3. Import proveďte mimo špičku (např. v noci)

Příklad hromadného importu:

curl -X POST "https://app.retino.com/api/v2/orders/bulk" \  -H "Authorization: váš_api_token" \  -H "Content-Type: application/json" \  -d '[    {      "code": "OBJ-001",      "store_id": "vas-eshop",      "price": {"with_vat": "1000.00"},      "customer": {"email": "[email protected]"}    },    {      "code": "OBJ-002",      "store_id": "vas-eshop",      "price": {"with_vat": "2000.00"},      "customer": {"email": "[email protected]"}    }  ]'

Tip: Importujte objednávky v dávkách po max. 100 kusech. API vrátí informaci, které objednávky se podařilo zpracovat a které selhaly.

Časté problémy

Store ID neexistuje

Chyba: "Store ID 'xyz' does not exist"

Řešení: Vytvořte Store ID v nastavení API před odesláním první objednávky.

Soubor s tímto ID neexistuje

Chyba při připojování faktury: "File with this ID does not exist"

Řešení: Ujistěte se, že nejprve nahrajete soubor přes POST /api/v2/files a až pak použijete vrácené UUID v file_id.

Zásilka se nepropojí s objednávkou

Důvod: Používáte code objednávky místo id.

Řešení: V poli order při vytváření zásilky použijte UUID objednávky (pole id), ne číslo objednávky (pole code).

Zásilka se nesleduje

Stav zásilky je PENDING

Důvod: Retino ještě nenašel dopravce nebo tracking number není platné.

Řešení:

  • Zkontrolujte, že tracking number je správné

  • Přidejte carrier_hint pro rychlejší detekci

  • Počkejte 5–10 minut – detekce dopravce může chvíli trvat

Další kroky

Důležité: Orders API synchronizuje objednávky a tracking data, ale nenastavuje automaticky transakční e-maily. E-maily jsou samostatná funkce, kterou musíte aktivovat v nastavení Retina.

  1. Nastavte transakční e-maily v Retinu (volitelné, ale doporučené pro automatické notifikace zákazníkům)

  2. Otestujte celý workflow s jednou testovací objednávkou

  3. Implementujte webhooky v e-shopu pro automatickou synchronizaci

  4. Monitorujte první objednávky v Retinu a zkontrolujte, že vše funguje správně

Technická dokumentace: app.retino.com/api/docs

Nastavení API: app.retino.com/settings/api-v2/

Související články
Tickets API
Tracking API
Orders API: Synchronizace objednávek
Návod: Jak nastavit transakční e-maily krok po kroku
Dostali jste odpověď na svou otázku?